Skip to content

Most visited

Recently visited

navigation

Introducing First-time Users to Your App

To show a first-time user how to get the most from your app, present onboarding information at app startup. Here are some examples of onboarding information:

The v17 Leanback support library provides the OnboardingFragment class for presenting first-time user information. This lesson describes how to use the OnboardingFragment class to present introductory information that is shown when the app launches for the first time. OnboardingFragment uses TV UI best practices to present the information in a way that matches TV UI styles, and is easy to navigate on TV devices.

Figure 1. An example OnboardingFragment.

Your OnboardingFragment should not contain UI elements that require user input, such as buttons and fields. Similarly, it should not be used as a UI element for a task the user will do regularly. If you need to present a multi-page UI that requires user input, consider using a GuidedStepFragment.

Add an OnboardingFragment

To add an OnboardingFragment to your app, implement a class that extends the OnboardingFragment class. Add this fragment to an activity, either via the activity's layout XML, or programmatically. Make sure the activity or fragment is using a theme derived from Theme_Leanback_Onboarding, as described in Customize Themes.

In the onCreate() method of your app's main activity, call startActivity() with an Intent that points to your OnboardingFragment's parent activity. This ensures that your OnboardingFragment appears as soon as your app starts.

To ensure that the OnboardingFragment only appears the first time that the user starts your app, use a SharedPreferences object to track whether the user has already viewed the OnboardingFragment. Define a boolean value that changes to true when the user finishes viewing the OnboardingFragment. Check this value in your main activity’s onCreate(), and only start the OnboardingFragment parent activity if the value is false. The following example shows an override of onCreate() that checks for a SharedPreferences value and, if not set to true, calls startActivity() to show the OnboardingFragment:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    SharedPreferences sharedPreferences =
            PreferenceManager.getDefaultSharedPreferences(this);
    // Check if we need to display our OnboardingFragment
    if (!sharedPreferences.getBoolean(
            MyOnboardingFragment.COMPLETED_ONBOARDING_PREF_NAME, false)) {
        // The user hasn't seen the OnboardingFragment yet, so show it
        startActivity(new Intent(this, OnboardingActivity.class));
    }
}

After the user views the OnboardingFragment, mark it as viewed using the SharedPreferences object. To do this, in your OnboardingFragment, override onFinishFragment() and set your SharedPreferences value to true, as shown in the following example:

@Override
protected void onFinishFragment() {
    super.onFinishFragment();
    // User has seen OnboardingFragment, so mark our SharedPreferences
    // flag as completed so that we don't show our OnboardingFragment
    // the next time the user launches the app.
    SharedPreferences.Editor sharedPreferencesEditor =
            PreferenceManager.getDefaultSharedPreferences(getContext()).edit();
    sharedPreferencesEditor.putBoolean(
            COMPLETED_ONBOARDING_PREF_NAME, true);
    sharedPreferencesEditor.apply();
}

Add OnboardingFragment Pages

After you add your OnboardingFragment, you need to define the onboarding pages. An OnboardingFragment displays content in a series of ordered pages. Each page can have a title, description, and several sub-views that can contain images or animations.

Figure 2. OnboardingFragment page elements.

Figure 2 shows an example page with callouts marking customizable page elements that your OnboardingFragment can provide. The page elements are:

  1. The page title.
  2. The page description.
  3. The page content view, in this case a simple green checkmark in a grey box. This view is optional. Use this view to illustrate page details such as a screenshot that highlights the app feature that the page describes.
  4. The page background view, in this case a simple blue gradient. This view always renders behind other views on the page. This view is optional.
  5. The page foreground view, in this case a logo. This view always renders in front of all other views on the page. This view is optional.

Initialize page information when your OnboardingFragment is first created or attached to the parent activity, as the system requests page information when it creates the fragment's view. You can initialize page information in your class constructor or in an override of onAttach().

Override each of the following methods that provide page information to the system:

Override each of the following methods to provide optional sub-views used to display images or animations:

The system adds the View that you create to the page layout. The following example overrides onCreateContentView() and returns an ImageView:

private ImageView mContentView;
...
@Override
protected View onCreateContentView(LayoutInflater inflater, ViewGroup container) {
    mContentView = new ImageView(getContext());
    mContentView.setScaleType(ImageView.ScaleType.CENTER_INSIDE);
    mContentView.setImageResource(R.drawable.onboarding_content_view);
    mContentView.setPadding(0, 32, 0, 32);
    return mContentView;
}

Add an Initial Logo Screen

Your OnboardingFragment can start with an optional logo screen that introduces your app. If you want to display a Drawable as your logo screen, in your OnboardingFragment's onCreate() method, call setLogoResourceId() with the ID of your Drawable. The system will fade in and briefly display this Drawable, and then fade out the Drawable before displaying the first page of your OnboardingFragment.

If you want to provide a custom animation for your logo screen, instead of calling setLogoResourceId(), override onCreateLogoAnimation() and return an Animator object that renders your custom animation, as shown in the following example:

@Override
public Animator onCreateLogoAnimation() {
    return AnimatorInflater.loadAnimator(mContext,
            R.animator.onboarding_logo_screen_animation);
}

Customize Page Animations

The system uses default animations when displaying the first page of your OnboardingFragment and when the user navigates to a different page. You can customize these animations by overriding methods in your OnboardingFragment.

To customize the animation that appears on your first page, override onCreateEnterAnimation() and return an Animator. The following example creates an Animator that scales the content view horizontally:

@Override
protected Animator onCreateEnterAnimation() {
    Animator startAnimator = ObjectAnimator.ofFloat(mContentView,
            View.SCALE_X, 0.2f, 1.0f).setDuration(ANIMATION_DURATION);
    return startAnimator;
}

To customize the animation used when the user navigates to a different page, override onPageChanged(). In your onPageChanged() method, create Animators that remove the previous page and display the next page, add these to an AnimatorSet, and play the set. The following example uses a fade-out animation to remove the previous page, updates the content view image, and uses a fade-in animation to display the next page:

@Override
protected void onPageChanged(final int newPage, int previousPage) {
    // Create a fade-out animation used to fade out previousPage and, once
    // done, swaps the contentView image with the next page's image.
    Animator fadeOut = ObjectAnimator.ofFloat(mContentView,
            View.ALPHA, 1.0f, 0.0f).setDuration(ANIMATION_DURATION);
    fadeOut.addListener(new AnimatorListenerAdapter() {
        @Override
        public void onAnimationEnd(Animator animation) {
            mContentView.setImageResource(pageImages[newPage]);
        }
    });
    // Create a fade-in animation used to fade in nextPage
    Animator fadeIn = ObjectAnimator.ofFloat(mContentView,
            View.ALPHA, 0.0f, 1.0f).setDuration(ANIMATION_DURATION);
    // Create AnimatorSet with our fade-out and fade-in animators, and start it
    AnimatorSet set = new AnimatorSet();
    set.playSequentially(fadeOut, fadeIn);
    set.start();
}

For more details about how to create Animators and AnimatorSets, see Property Animations.

Customize Themes

Any OnboardingFragment implementation must use either the Theme_Leanback_Onboarding theme or a theme that inherits from Theme_Leanback_Onboarding. Set the theme for your OnboardingFragment by doing one of the following:

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)