Se usó la API de Cloud Translation para traducir esta página.

Cómo presentar tu app a los usuarios que acceden por primera vez

Para mostrar a un usuario nuevo cómo aprovechar al máximo tu aplicación, presenta información de integración al inicio de la app. Estos son algunos ejemplos de cómo incorporar información:

Presenta información detallada sobre qué canales están disponibles cuando un usuario accede por primera vez a la app de un canal.
Destaca las funciones notables de tu app.
Ilustrar los pasos obligatorios o recomendados que deben seguir los usuarios cuando usan la aplicación por primera vez.

La biblioteca androidx.Leanback ofrece Clase OnboardingSupportFragment para presentar información de usuarios que acceden por primera vez. En esta guía, se describe cómo usar la OnboardingSupportFragment clase para presentar información introductoria que se muestra cuando se inicia la aplicación durante la primera tiempo.

OnboardingSupportFragment usa la IU de TV prácticas recomendadas para presentar información de una manera que coincida con los estilos de IU de TV y es fácil navegar en ellos en dispositivos de TV.

Figura 1: Ejemplo OnboardingSupportFragment

OnboardingSupportFragment no es adecuado para todos los casos de uso. No uses OnboardingSupportFragment cuando sea necesario incluir el elemento. Elementos de la IU que requieren entradas del usuario, como botones y campos Tampoco uses OnboardingSupportFragment para las tareas que realizará el usuario. con regularidad. Por último, si necesitas presentar una IU de varias páginas que requiera las entradas del usuario, considera usar GuidedStepSupportFragment

Cómo agregar un elemento OnboardingSupportFragment

Cómo agregar un OnboardingSupportFragment en tu app, implementa una clase que extienda la clase OnboardingSupportFragment. Agrega este fragmento a una actividad, ya sea mediante el XML de diseño de la actividad o programáticamente. Asegúrate de que la actividad o fragmento utiliza un tema derivado de Theme_Leanback_Onboarding, como se describe en la sección Cómo personalizar temas.

En el método onCreate() de tu principal de la app, llamar startActivity() con un Intent que apunte a la actividad principal de tu OnboardingSupportFragment. Esto ayuda a garantizar que tus OnboardingSupportFragment aparece como tan pronto como se inicie la app.

Para ayudar a garantizar que el OnboardingSupportFragment solo aparece primera vez que el usuario inicia tu aplicación, utiliza una Objeto SharedPreferences para hacer un seguimiento de si el usuario ya vio el OnboardingSupportFragment Define un valor booleano valor que cambia a verdadero cuando el usuario termina de visualizar el OnboardingSupportFragment Cheque este valor en la capa de recursos onCreate() y solo iniciarás la OnboardingSupportFragment actividad superior si el valor es falso.

En el siguiente ejemplo, se muestra una anulación de onCreate() que comprueba si hay un SharedPreferences y, si no se establece en true, llama startActivity() para mostrar OnboardingSupportFragment:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    PreferenceManager.getDefaultSharedPreferences(this).apply {
        // Check if we need to display our OnboardingSupportFragment
        if (!getBoolean(MyOnboardingSupportFragment.COMPLETED_ONBOARDING_PREF_NAME, false)) {
            // The user hasn't seen the OnboardingSupportFragment yet, so show it
            startActivity(Intent(this@OnboardingActivity, OnboardingActivity::class.java))
        }
    }
}

Java

@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 OnboardingSupportFragment
    if (!sharedPreferences.getBoolean(
            MyOnboardingSupportFragment.COMPLETED_ONBOARDING_PREF_NAME, false)) {
        // The user hasn't seen the OnboardingSupportFragment yet, so show it
        startActivity(new Intent(this, OnboardingActivity.class));
    }
}

Después de que el usuario ve OnboardingSupportFragment, marcarlo como visto usando el objeto SharedPreferences. Para ello, anula onFinishFragment() en tu OnboardingSupportFragment y configura tu SharedPreferences value como true, como se muestra en el siguiente ejemplo:

Kotlin

override fun onFinishFragment() {
    super.onFinishFragment()
    // User has seen OnboardingSupportFragment, so mark our SharedPreferences
    // flag as completed so that we don't show our OnboardingSupportFragment
    // the next time the user launches the app
    PreferenceManager.getDefaultSharedPreferences(context).edit().apply {
        putBoolean(COMPLETED_ONBOARDING_PREF_NAME, true)
        apply()
    }
}

Java

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

Cómo agregar páginas OnboardingSupportFragment

Un OnboardingSupportFragment muestra contenido en una serie de páginas ordenadas. Después de que agregues tu OnboardingSupportFragment, debes definir las páginas de incorporación. Cada página puede tener un título, una descripción y varias subvistas que pueden contener imágenes o animaciones.

Figura 2: OnboardingSupportFragment elementos de página.

En la figura 2, se muestra una página de ejemplo con texto destacado que marca una página personalizable. elementos que tu OnboardingSupportFragment puede proporcionar. Los elementos de la página son los siguientes:

El título de la página
La descripción de la página
La vista de contenido de la página, en este caso, una simple marca de verificación verde en un cuadro gris y es opcional) Usa esta vista para ilustrar los detalles de la página. Por ejemplo, podrías incluir una captura de pantalla que destaque la función de la aplicación que se describe en la página.
La vista del segundo plano de la página, en este caso, un simple gradiente azul Esta vista siempre se renderiza detrás de otras vistas de la página. y es opcional)
La vista de primer plano de la página, en este caso, un logotipo Esta vista siempre se renderiza frente a todas las demás vistas de la página. y es opcional)

Inicializa la información de la página cuando Se crea OnboardingSupportFragment por primera vez o adjunta a la actividad superior, como la página de solicitudes del sistema información cuando crea la vista del fragmento. Puedes inicializar la página en el constructor de clase o en una anulación de onAttach()

Anula cada uno de los siguientes métodos, que proporcionan información de la página. al sistema:

getPageCount() devuelve la cantidad de páginas de la OnboardingSupportFragment
getPageTitle() muestra el título del número de página solicitado.
getPageDescription() muestra la descripción de la página solicitada. de la fila.

Anula cada uno de los siguientes métodos para proporcionar subvistas opcionales para mostrar imágenes o animaciones:

onCreateBackgroundView() devuelve una View que create para que funcione como la vista en segundo plano o un valor nulo si no se necesita una vista en segundo plano.
onCreateContentView() devuelve una View que create para que funcione como la vista de contenido o un valor nulo si no se necesita una vista de contenido.
onCreateForegroundView() devuelve una View que create para que actúe como vista en primer plano o nulo si no se necesita una vista en primer plano.

El sistema agrega a la página el elemento View que creas. . En el siguiente ejemplo, se anula onCreateContentView() y muestra un ImageView

Kotlin

private lateinit var contentView: ImageView
...
override fun onCreateContentView(inflater: LayoutInflater?, container: ViewGroup?): View? {
    return ImageView(context).apply {
        scaleType = ImageView.ScaleType.CENTER_INSIDE
        setImageResource(R.drawable.onboarding_content_view)
        setPadding(0, 32, 0, 32)
        contentView = this
    }
}

Java

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

Cómo agregar una pantalla de logotipo inicial

Tu OnboardingSupportFragment puede comenzar con una pantalla de logotipo opcional que presenta tu app. Si quieres mostrar un Drawable como la pantalla de tu logotipo, llama setLogoResourceId() con el ID de tu Drawable por la onCreate() de tu OnboardingSupportFragment. El sistema aplica un fundido de entrada y muestra brevemente la Drawable y, luego, aplica un fundido en Drawable antes de mostrar la primera página de tu OnboardingSupportFragment.

Si quieres proporcionar una animación personalizada para la pantalla de tu logotipo, en lugar de llamando a setLogoResourceId(), anular onCreateLogoAnimation() y muestra un Animator. objeto que renderiza tu animación personalizada, como se muestra en el siguiente ejemplo:

Kotlin

public override fun onCreateLogoAnimation(): Animator =
        AnimatorInflater.loadAnimator(context, R.animator.onboarding_logo_screen_animation)

Java

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

Cómo personalizar animaciones de página

El sistema utiliza animaciones predeterminadas al mostrar la primera página de tu OnboardingSupportFragment y cuando el usuario navega a una página diferente. Puedes personalizar estas animaciones anular métodos en tu OnboardingSupportFragment

Para personalizar la animación que aparece en la primera página, haz lo siguiente: anular onCreateEnterAnimation() y muestra un Animator. En el siguiente ejemplo, se crea un Animator que escala la vista de contenido. horizontalmente:

Kotlin

override fun onCreateEnterAnimation(): Animator =
    ObjectAnimator.ofFloat(contentView, View.SCALE_X, 0.2f, 1.0f)
            .setDuration(ANIMATION_DURATION)

Java

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

Para personalizar la animación que se usa cuando el usuario navega a una página diferente, anular onPageChanged() En tu método onPageChanged(), crea objetos Animator. que quiten la página anterior y muestren la siguiente, agrégalas a una AnimatorSet y reproduce el conjunto. Lo siguiente ejemplo, se usa una animación de fundido de salida para quitar la página anterior, se actualiza la de vista de contenido y usa una animación de fundido de entrada para mostrar la página siguiente:

Kotlin

override fun onPageChanged(newPage: Int, previousPage: Int) {
    // Create a fade-out animation for previousPage and, once
    // done, swap the contentView image with the next page's image
    val fadeOut = ObjectAnimator.ofFloat(mContentView, View.ALPHA, 1.0f, 0.0f)
            .setDuration(ANIMATION_DURATION)
            .apply {
                addListener(object : AnimatorListenerAdapter() {

                    override fun onAnimationEnd(animation: Animator) {
                        mContentView.setImageResource(pageImages[newPage])
                    }
                })
            }
    // Create a fade-in animation for nextPage
    val fadeIn = ObjectAnimator.ofFloat(mContentView, View.ALPHA, 0.0f, 1.0f)
            .setDuration(ANIMATION_DURATION)
    // Create AnimatorSet with fade-out and fade-in animators and start it
    AnimatorSet().apply {
        playSequentially(fadeOut, fadeIn)
        start()
    }
}

Java

@Override
protected void onPageChanged(final int newPage, int previousPage) {
    // Create a fade-out animation for previousPage and, once
    // done, swap 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 for nextPage
    Animator fadeIn = ObjectAnimator.ofFloat(mContentView,
            View.ALPHA, 0.0f, 1.0f).setDuration(ANIMATION_DURATION);
    // Create AnimatorSet with fade-out and fade-in animators and start it
    AnimatorSet set = new AnimatorSet();
    set.playSequentially(fadeOut, fadeIn);
    set.start();
}

Para obtener más detalles sobre cómo crear Objetos Animator y Objetos AnimatorSet, consulta Descripción general de la animación de propiedades.

Cómo personalizar temas

Cualquier OnboardingSupportFragment implementación debe usar el Theme_Leanback_Onboarding tema o un tema que se hereda de Theme_Leanback_Onboarding. Establece el tema para tu OnboardingSupportFragment mediante una de las siguientes acciones:

Establece la actividad principal de OnboardingSupportFragment para usar la tema deseado. En el siguiente ejemplo, se muestra cómo configurar una actividad para usar Theme_Leanback_Onboarding en el manifiesto de la app:
```
<activity
   android:name=".OnboardingActivity"
   android:enabled="true"
   android:exported="true"
   android:theme="@style/Theme.Leanback.Onboarding">
</activity>
```
Configura el tema en la actividad principal con la LeanbackOnboardingTheme_onboardingTheme en un tema de actividad personalizado. Apunte este atributo a otro tema personalizado que solo el elemento OnboardingSupportFragment usan los objetos en tu actividad. Usa este enfoque si tu actividad ya usa un tema personalizado y no quieres que OnboardingSupportFragment estilos a otro vistas en la actividad.
Anular onProvideTheme() y muestra el tema deseado. Usa este enfoque si varias actividades utilizan tu OnboardingSupportFragment o si la actividad principal no puede usar el tema deseado. En el siguiente ejemplo, se anula onProvideTheme() y se muestra Theme_Leanback_Onboarding
Kotlin
override fun onProvideTheme(): Int = R.style.Theme_Leanback_Onboarding
Java
@Override public int onProvideTheme() { return R.style.Theme_Leanback_Onboarding; }

Cómo usar los controles de transporte

Cómo agregar un paso guiado