Questa pagina è stata tradotta dall'API Cloud Translation.

Presentare i nuovi utenti alla tua app

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

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

La libreria androidx.leanback fornisce la classe OnboardingSupportFragment per presentare le informazioni per i nuovi utenti. Questa guida descrive come utilizzare la classe OnboardingSupportFragment per presentare informazioni introduttive che vengono mostrate al primo avvio dell'app.

OnboardingSupportFragment utilizza le best practice relative all'interfaccia utente TV per presentare le informazioni in modo che corrispondano agli stili dell'interfaccia utente della TV e siano facili da navigare sui dispositivi TV.

Figura 1. Un esempio: OnboardingSupportFragment.

OnboardingSupportFragment non è appropriato per tutti i casi d'uso. Non utilizzare OnboardingSupportFragment quando devi includere elementi dell'interfaccia utente che richiedono l'input dell'utente, ad esempio pulsanti e campi. Inoltre, non utilizzare OnboardingSupportFragment per attività che l'utente svolgerà 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 estende la classe OnboardingSupportFragment. Aggiungi questo frammento a un'attività, utilizzando il file XML di layout dell'attività o in modo programmatico. Assicurati che l'attività o il frammento utilizzino un tema derivato da Theme_Leanback_Onboarding, come descritto nella sezione Personalizza temi.

Nel metodo onCreate() dell'attività principale dell'app, chiama startActivity() con un Intent che rimanda all'attività principale del tuo OnboardingSupportFragment. In questo modo avrai la certezza che l'app OnboardingSupportFragment venga visualizzata all'avvio dell'app.

Per assicurarti che l'elemento OnboardingSupportFragment venga visualizzato 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 l'OnboardingSupportFragment. Controlla questo valore nel metodo onCreate() dell'attività principale e avvia l'attività principale OnboardingSupportFragment solo se il valore è false.

L'esempio seguente mostra un override di onCreate() che verifica un valore SharedPreferences e, se non è impostato su true, chiama startActivity() per mostrare 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, contrassegnalo come visualizzato utilizzando l'oggetto SharedPreferences. Per farlo, esegui l'override di onFinishFragment() in OnboardingSupportFragment e imposta il valore 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

Un 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 e diverse visualizzazioni secondarie che possono contenere immagini o animazioni.

Figura 2. OnboardingSupportFragment elementi della pagina.

La Figura 2 mostra una pagina di esempio con callout che contrassegnano gli elementi personalizzabili della pagina che OnboardingSupportFragment può fornire. Gli elementi della pagina sono:

Il titolo della pagina.
La descrizione della pagina.
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, puoi includere uno screenshot che metta in evidenza la funzionalità dell'app descritta nella pagina.
La visualizzazione sullo sfondo della pagina, in questo caso una semplice sfumatura blu. Questa visualizzazione è sempre inferiore alle altre visualizzazioni della pagina. Questa visualizzazione è facoltativa.
La visualizzazione in primo piano della pagina, in questo caso un logo. Questa visualizzazione viene sempre mostrata prima di tutte le altre visualizzazioni della pagina. Questa visualizzazione è facoltativa.

Inizializza le informazioni della pagina quando l'elemento OnboardingSupportFragment viene creato per la prima volta o viene collegato all'attività padre, poiché il sistema richiede le informazioni sulla pagina al momento della creazione della vista del frammento. Puoi inizializzare le informazioni sulla pagina nel costruttore della classe o in una sostituzione di onAttach().

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

getPageCount() restituisce il numero di pagine in OnboardingSupportFragment.
getPageTitle() restituisce il titolo per il numero di pagina richiesto.
getPageDescription() restituisce la descrizione per il numero di pagina richiesto.

Sostituisci ciascuno dei seguenti metodi per fornire sottoview facoltative per visualizzare immagini o animazioni:

onCreateBackgroundView() restituisce un valore View creato da utilizzare come visualizzazione in background oppure nullo se non è necessaria alcuna visualizzazione in background.
onCreateContentView() restituisce un valore View creato da utilizzare come visualizzazione del contenuto oppure nullo se non è necessaria alcuna visualizzazione del contenuto.
onCreateForegroundView() restituisce un valore View creato che funge da visualizzazione in primo piano oppure nullo se non è necessaria alcuna visualizzazione in primo piano.

Il sistema aggiunge al layout di pagina l'elemento View che hai creato. L'esempio seguente esegue l'override di 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

OnboardingSupportFragment può iniziare con una schermata del logo facoltativa che introduce la tua app. Se vuoi visualizzare un Drawable come schermata del logo, chiama setLogoResourceId() con l'ID di Drawable nel metodo onCreate() di OnboardingSupportFragment. Il sistema entra in dissolvenza e visualizza per un breve momento l'Drawable, poi dissolve l'Drawable prima di visualizzare la prima pagina di OnboardingSupportFragment.

Se vuoi fornire un'animazione personalizzata per la schermata del logo, invece di chiamare setLogoResourceId(), sostituisci onCreateLogoAnimation() e restituisci un oggetto Animator che esegue il rendering dell'animazione personalizzata, come 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 dell'OnboardingSupportFragment e quando l'utente apre un'altra pagina. Puoi personalizzare queste animazioni sostituendo i metodi in OnboardingSupportFragment.

Per personalizzare l'animazione visualizzata sulla prima pagina, esegui l'override di onCreateEnterAnimation() e restituisci 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, esegui l'override di onPageChanged(). Nel tuo metodo onPageChanged(), crea Animator oggetti che rimuovono la pagina precedente e mostrano la pagina successiva, aggiungili a AnimatorSet e riproduci il set. L'esempio seguente utilizza un'animazione di dissolvenza in uscita per rimuovere la pagina precedente, aggiorna l'immagine della visualizzazione dei 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 ulteriori dettagli su come creare oggetti Animator e AnimatorSet oggetti, consulta la pagina Panoramica dell'animazione della proprietà.

Personalizza temi

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

Imposta l'attività principale di OnboardingSupportFragment per utilizzare il tema desiderato. L'esempio seguente mostra come impostare un'attività per 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 l'attributo LeanbackOnboardingTheme_onboardingTheme in un tema di attività personalizzato. Punta questo attributo a un altro tema personalizzato utilizzato solo dagli oggetti OnboardingSupportFragment nella tua attività. Utilizza questo approccio se la tua attività utilizza già un tema personalizzato e non vuoi applicare gli stili di OnboardingSupportFragment ad altre visualizzazioni dell'attività.
Esegui l'override di onProvideTheme() e restituisci il tema desiderato. Utilizza questo approccio se più attività utilizzano il tuo OnboardingSupportFragment o se l'attività principale non può utilizzare il tema desiderato. L'esempio seguente sostituisce 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;
}
```