Presentare i nuovi utenti alla tua app

Migliora la creazione con Compose
Crea splendide UI con un minimo codice utilizzando Jetpack Compose per il sistema operativo Android TV.
Scrivi per la TV → .

Per mostrare a un nuovo utente come ottenere il massimo dalla tua app, presenta informazioni sull'onboarding all'avvio dell'app. Ecco alcuni esempi di onboarding informazioni:

  • Presenta informazioni dettagliate su quali canali sono disponibili quando un utente accede prima a un'app del canale.
  • Richiama l'attenzione sulle funzionalità più interessanti della tua app.
  • Illustra i passaggi obbligatori o consigliati che gli utenti devono intraprendere quando utilizzando l'app per la prima volta.

La libreria androidx.leanback fornisce le OnboardingSupportFragment corso per presentando informazioni al nuovo utente. Questa guida descrive come utilizzare OnboardingSupportFragment corso da presentare informazioni introduttive mostrate al momento del lancio dell'app per la prima nel tempo.

OnboardingSupportFragment utilizza l'UI TV best practice per presentare le informazioni in modo che corrispondano agli stili dell'interfaccia utente della TV ed è facile da navigare sui dispositivi TV.

Figura 1. Esempio OnboardingSupportFragment.

OnboardingSupportFragment non è appropriato per tutti i casi d'uso. Non usare OnboardingSupportFragment quando devi includere Elementi dell'interfaccia utente che richiedono l'input dell'utente, come pulsanti e campi. Inoltre, non utilizzare OnboardingSupportFragment per le attività che l'utente eseguirà regolarmente. Infine, se devi presentare una UI di più pagine che richiede l'input dell'utente, valuta la possibilità di utilizzare GuidedStepSupportFragment.

Aggiungi un OnboardingSupportFragment

Per aggiungere un OnboardingSupportFragment alla tua app, implementa una classe che si espanda la classe OnboardingSupportFragment. Aggiungi questo frammento a un'attività, utilizzando il file XML di layout dell'attività in modo programmatico. Assicurati che l'attività o utilizza un tema derivato da Theme_Leanback_Onboarding, come descritto nella sezione Personalizza temi.

Nel metodo onCreate() di attività principale dell'app, chiamata startActivity() con un Intent che punta a l'attività genitore del tuo OnboardingSupportFragment. Questo aiuta a garantire che OnboardingSupportFragment appare come all'avvio dell'app.

Per garantire che OnboardingSupportFragment compare solo la prima volta che l'utente avvia l'app, utilizza un Oggetto SharedPreferences per monitorare se l'utente ha già visualizzato OnboardingSupportFragment. Definisci un valore booleano che diventa true quando l'utente termina di visualizzare OnboardingSupportFragment. Controllo questo valore nelle metriche onCreate() e avvia solo il metodo OnboardingSupportFragment attività genitore se il valore è false.

L'esempio seguente mostra un override di onCreate() che verifica la presenza di un SharedPreferences e, se non è impostato su true, chiama startActivity() per visualizzare 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));
    }
}

Dopo che l'utente ha visualizzato OnboardingSupportFragment, contrassegna come visualizzato utilizzando l'oggetto SharedPreferences. Per farlo, sostituisci onFinishFragment() nel tuo OnboardingSupportFragment e imposta il SharedPreferences su true, come mostrato nell'esempio seguente:

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();
}

Aggiungere pagine OnboardingSupportFragment

OnboardingSupportFragment mostra i contenuti in una serie di pagine ordinate. Dopo aver aggiunto il tuo OnboardingSupportFragment, devi definire le pagine di onboarding. Ogni pagina può avere un titolo, una descrizione diverse visualizzazioni secondarie che possono contenere immagini o animazioni.

Figura 2. OnboardingSupportFragment elementi della pagina.

La figura 2 mostra una pagina di esempio in cui i callout contrassegnano la pagina personalizzabile elementi che il tuo OnboardingSupportFragment che è in grado di fornire. Gli elementi della pagina sono:

  1. Il titolo della pagina.
  2. La descrizione della pagina.
  3. La visualizzazione dei contenuti della pagina, in questo caso un semplice segno di spunta verde in una casella grigia. Questa visualizzazione è facoltativa. Utilizza questa visualizzazione per illustrare i dettagli della pagina. Ad esempio, potresti Includi uno screenshot che metta in evidenza la funzionalità dell'app descritta nella pagina.
  4. La visualizzazione sullo sfondo della pagina, in questo caso una semplice sfumatura blu. Questa visualizzazione viene sempre visualizzato in ritardo rispetto alle altre visualizzazioni della pagina. Questa visualizzazione è facoltativa.
  5. La visualizzazione in primo piano della pagina, in questo caso un logo. Questa visualizzazione esegue sempre il rendering davanti a tutte le altre visualizzazioni della pagina. Questa visualizzazione è facoltativa.

Inizializza le informazioni sulla pagina quando Prima creazione di OnboardingSupportFragment o collegati all'attività principale, come richiesto dal sistema informazioni quando crea la vista del frammento. Puoi inizializzare la pagina nel costruttore della classe o in una sostituzione onAttach().

Esegui l'override di ciascuno dei seguenti metodi, che forniscono informazioni sulla pagina al sistema:

Esegui l'override di ciascuno dei seguenti metodi per fornire visualizzazioni secondarie facoltative per visualizzare immagini o animazioni:

  • onCreateBackgroundView() restituisce un View che create per agire da visualizzazione di sfondo o nullo se non è necessaria alcuna visualizzazione di sfondo.
  • onCreateContentView() restituisce un View che create per fungere da visualizzazione del contenuto o nullo se non è necessaria alcuna visualizzazione del contenuto.
  • onCreateForegroundView() restituisce un View che create in modo che agisca da visualizzazione in primo piano o nullo se non è necessaria alcuna visualizzazione in primo piano.

Il sistema aggiunge alla pagina gli elementi View che crei layout. L'esempio seguente sostituisce onCreateContentView() e restituisce 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;
}

Schermata iniziale con logo

Il tuo OnboardingSupportFragment può iniziare con una schermata con un logo facoltativo che presenta la tua app. Se vuoi visualizzare Drawable come schermata del logo, chiama setLogoResourceId() con l'ID del tuo Drawable in onCreate() di OnboardingSupportFragment. Il sistema entra in dissolvenza e visualizza per un breve momento Drawable, dopodiché la Drawable viene dissolvenza prima di visualizzare la prima pagina di OnboardingSupportFragment.

Se vuoi fornire un'animazione personalizzata per la schermata del logo, anziché chiamata setLogoResourceId(), override onCreateLogoAnimation() e restituisci un Animator che esegue il rendering dell'animazione personalizzata, come illustrato nell'esempio seguente:

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);
}

Personalizza le animazioni delle pagine

Il sistema utilizza animazioni predefinite quando viene visualizzata la prima pagina del OnboardingSupportFragment e quando l'utente passa a una pagina diversa. Puoi personalizzare queste animazioni i metodi di override OnboardingSupportFragment.

Per personalizzare l'animazione visualizzata sulla prima pagina: eseguire l'override onCreateEnterAnimation() e restituisce un Animator. L'esempio seguente crea un Animator che scala la visualizzazione dei contenuti orizzontalmente:

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;
}

Per personalizzare l'animazione utilizzata quando l'utente passa a una pagina diversa: eseguire l'override onPageChanged(). Nel metodo onPageChanged(), crea Animator oggetti che consentono di rimuovere la pagina precedente e di visualizzare quella successiva, aggiungile a un AnimatorSet e gioca al set. Le seguenti esempio utilizza un'animazione di dissolvenza in uscita per rimuovere la pagina precedente, aggiorna la immagine di visualizzazione contenuti e utilizza un'animazione di dissolvenza in entrata per visualizzare la pagina successiva:

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();
}

Per maggiori dettagli su come creare Animator oggetti e AnimatorSet oggetti, vedi . Panoramica dell'animazione della proprietà.

Personalizza temi

Qualsiasi OnboardingSupportFragment l'implementazione deve utilizzare Tema Theme_Leanback_Onboarding o un tema che eredita da Theme_Leanback_Onboarding. Imposta il parametro tema per OnboardingSupportFragment in uno dei seguenti modi:

  • Imposta l'attività principale di OnboardingSupportFragment in modo da utilizzare tema desiderato. L'esempio seguente mostra come impostare un'attività da utilizzare Theme_Leanback_Onboarding nel file manifest dell'app: 
    <activity
   android:name=".OnboardingActivity"
   android:enabled="true"
   android:exported="true"
   android:theme="@style/Theme.Leanback.Onboarding">
</activity>
  • Imposta il tema nell'attività principale utilizzando lo LeanbackOnboardingTheme_onboardingTheme in un tema di attività personalizzato. Punta questo attributo a un altro tema personalizzato che solo OnboardingSupportFragment utilizzati nell'attività. Utilizza questo approccio se la tua attività utilizza già un tema personalizzato che non vuoi applicare OnboardingSupportFragment stili ad altro visualizzazioni nell'attività.
  • Esegui override onProvideTheme() e restituisci il tema desiderato. Utilizza questo approccio se in più attività usano i tuoi OnboardingSupportFragment o se l'attività principale non può utilizzare il tema desiderato. L'esempio seguente esegue l'override di onProvideTheme() e restituisce Theme_Leanback_Onboarding:

    Kotlin

    override fun onProvideTheme(): Int = R.style.Theme_Leanback_Onboarding

    Java

    @Override
public int onProvideTheme() {
   return R.style.Theme_Leanback_Onboarding;
}
Indietro
Utilizzare i controlli per il trasporto
Avanti
Aggiungere un passaggio guidato