Consigli su Android N e versioni precedenti

Quando interagiscono con le TV, gli utenti in genere preferiscono fornire un input minimo prima di guardare i contenuti. Uno scenario ideale per molti utenti di TV è: sedersi, accendere e guardare. Il percorso che in genere preferiscono è quello con il minor numero di passaggi per accedere ai contenuti che gli piacciono.

Nota: utilizza le API descritte qui solo per fornire consigli nelle app in esecuzione su versioni di Android fino ad Android 7.1 (livello API 25) incluso. Per fornire consigli per le app in esecuzione su Android 8.0 (livello API 26) e versioni successive, la tua app deve utilizzare i canali di consigli.

Il framework Android facilita l'interazione con input minimi fornendo una riga di consigli nella schermata Home. I consigli sui contenuti vengono visualizzati come prima riga della schermata Home della TV dopo il primo utilizzo del dispositivo. Se contribuisci con i consigli dal catalogo di contenuti della tua app, puoi aiutare gli utenti a tornare alla tua app.

Esempio della riga dei consigli nella schermata Home di Android TV
Figura 1. Un esempio della riga di consigli.

Questa guida spiega come creare e fornire consigli al framework Android in modo che gli utenti possano scoprire e apprezzare i contenuti della tua app. Consulta anche l'implementazione di esempio in the app di esempio Leanback .

Best practice per i consigli

I consigli aiutano gli utenti a trovare rapidamente i contenuti e le app che gli piacciono. La creazione di consigli di alta qualità e pertinenti per gli utenti è un fattore importante per creare un'esperienza utente eccezionale con la tua app TV. Per questo motivo, devi valutare attentamente i consigli che presenti all'utente e gestirli con attenzione.

Tipi di consigli

Quando crei consigli, devi reindirizzare gli utenti alle attività di visualizzazione incomplete o suggerire attività che le estendano a contenuti correlati. Di seguito sono riportati alcuni tipi specifici di consigli da prendere in considerazione:

  • Consigli sui contenuti di continuazione per l'episodio successivo in modo che gli utenti possano riprendere a guardare una serie. In alternativa, utilizza i consigli di continuazione per film, programmi TV o podcast in pausa in modo che gli utenti possano tornare a guardare i contenuti in pausa con pochi clic.
  • Consigli sui nuovi contenuti, ad esempio per un nuovo episodio in prima visione, se l'utente ha finito di guardare un'altra serie. Inoltre, se la tua app consente agli utenti di abbonarsi, seguire o monitorare i contenuti, utilizza i consigli sui nuovi contenuti per gli elementi non guardati nell'elenco dei contenuti monitorati.
  • Consigli sui contenuti correlati in base al comportamento di visualizzazione storico degli utenti.

Per ulteriori informazioni su come progettare le schede dei consigli per un'esperienza utente ottimale, consulta la sezione Riga dei consigli nelle specifiche di progettazione di Android TV.

Aggiorna i consigli

Quando aggiorni i consigli, non rimuoverli e ripubblicarli, perché in questo modo i consigli vengono visualizzati alla fine della riga dei consigli. Una volta riprodotto un elemento di contenuti, ad esempio un film, rimuovilo dai consigli.

Personalizza consigli

Puoi personalizzare le schede dei consigli per comunicare le informazioni sul brand impostando elementi dell'interfaccia utente come l'immagine di primo piano e di sfondo, il colore, l'icona dell'app, il titolo e il sottotitolo della scheda. Per scoprire di più, consulta la sezione Riga dei consigli nelle specifiche di progettazione di Android TV.

Raggruppa i consigli

Se vuoi, puoi raggruppare i consigli in base all'origine dei consigli. Ad esempio, la tua app potrebbe fornire due gruppi di consigli: consigli sui contenuti a cui l'utente è abbonato e consigli sui nuovi contenuti di tendenza di cui l'utente potrebbe non essere a conoscenza.

Il sistema classifica e ordina i consigli per ogni gruppo separatamente quando crea o aggiorna la riga dei consigli. Se fornisci informazioni sui gruppi per i tuoi consigli, puoi assicurarti che i tuoi consigli non vengano ordinati in base a consigli non correlati.

Utilizza NotificationCompat.Builder.setGroup() per impostare la stringa della chiave del gruppo di un consiglio. Ad esempio, per contrassegnare un consiglio come appartenente a un gruppo che contiene nuovi contenuti di tendenza, puoi chiamare setGroup("trending").

Crea un servizio di consigli

I consigli sui contenuti vengono creati con l'elaborazione in background. Affinché la tua applicazione contribuisca ai consigli, crea un servizio che aggiunga periodicamente gli elenchi dal catalogo della tua app all'elenco di consigli del sistema.

Il seguente esempio di codice illustra come estendere IntentService per creare un servizio di consigli per la tua applicazione:

Kotlin

class UpdateRecommendationsService : IntentService("RecommendationService") {
    override protected fun onHandleIntent(intent: Intent) {
        Log.d(TAG, "Updating recommendation cards")
        val recommendations = VideoProvider.getMovieList()
        if (recommendations == null) return

        var count = 0

        try {
            val builder = RecommendationBuilder()
                    .setContext(applicationContext)
                    .setSmallIcon(R.drawable.videos_by_google_icon)

            for (entry in recommendations.entrySet()) {
                for (movie in entry.getValue()) {
                    Log.d(TAG, "Recommendation - " + movie.getTitle())

                    builder.setBackground(movie.getCardImageUrl())
                            .setId(count + 1)
                            .setPriority(MAX_RECOMMENDATIONS - count)
                            .setTitle(movie.getTitle())
                            .setDescription(getString(R.string.popular_header))
                            .setImage(movie.getCardImageUrl())
                            .setIntent(buildPendingIntent(movie))
                            .build()
                    if (++count >= MAX_RECOMMENDATIONS) {
                        break
                    }
                }
                if (++count >= MAX_RECOMMENDATIONS) {
                    break
                }
            }
        } catch (e: IOException) {
            Log.e(TAG, "Unable to update recommendation", e)
        }
    }

    private fun buildPendingIntent(movie: Movie): PendingIntent {
        val detailsIntent = Intent(this, DetailsActivity::class.java)
        detailsIntent.putExtra("Movie", movie)

        val stackBuilder = TaskStackBuilder.create(this)
        stackBuilder.addParentStack(DetailsActivity::class.java)
        stackBuilder.addNextIntent(detailsIntent)

        // Ensure a unique PendingIntents, otherwise all
        // recommendations end up with the same PendingIntent
        detailsIntent.setAction(movie.getId().toString())

        val intent = stackBuilder.getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT)
        return intent
    }

    companion object {
        private val TAG = "UpdateRecommendationsService"
        private val MAX_RECOMMENDATIONS = 3
    }
}

Java

public class UpdateRecommendationsService extends IntentService {
    private static final String TAG = "UpdateRecommendationsService";
    private static final int MAX_RECOMMENDATIONS = 3;

    public UpdateRecommendationsService() {
        super("RecommendationService");
    }

    @Override
    protected void onHandleIntent(Intent intent) {
        Log.d(TAG, "Updating recommendation cards");
        HashMap<String, List<Movie>> recommendations = VideoProvider.getMovieList();
        if (recommendations == null) return;

        int count = 0;

        try {
            RecommendationBuilder builder = new RecommendationBuilder()
                    .setContext(getApplicationContext())
                    .setSmallIcon(R.drawable.videos_by_google_icon);

            for (Map.Entry<String, List<Movie>> entry : recommendations.entrySet()) {
                for (Movie movie : entry.getValue()) {
                    Log.d(TAG, "Recommendation - " + movie.getTitle());

                    builder.setBackground(movie.getCardImageUrl())
                            .setId(count + 1)
                            .setPriority(MAX_RECOMMENDATIONS - count)
                            .setTitle(movie.getTitle())
                            .setDescription(getString(R.string.popular_header))
                            .setImage(movie.getCardImageUrl())
                            .setIntent(buildPendingIntent(movie))
                            .build();

                    if (++count >= MAX_RECOMMENDATIONS) {
                        break;
                    }
                }
                if (++count >= MAX_RECOMMENDATIONS) {
                    break;
                }
            }
        } catch (IOException e) {
            Log.e(TAG, "Unable to update recommendation", e);
        }
    }

    private PendingIntent buildPendingIntent(Movie movie) {
        Intent detailsIntent = new Intent(this, DetailsActivity.class);
        detailsIntent.putExtra("Movie", movie);

        TaskStackBuilder stackBuilder = TaskStackBuilder.create(this);
        stackBuilder.addParentStack(DetailsActivity.class);
        stackBuilder.addNextIntent(detailsIntent);
        // Ensure a unique PendingIntents, otherwise all
        // recommendations end up with the same PendingIntent
        detailsIntent.setAction(Long.toString(movie.getId()));

        PendingIntent intent = stackBuilder.getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT);
        return intent;
    }
}

Affinché questo servizio venga riconosciuto ed eseguito dal sistema, registralo utilizzando il file manifest dell'app. Il seguente snippet di codice illustra come dichiarare questa classe come servizio: 

<manifest ... >
  <application ... >
    ...

    <service
            android:name="com.example.android.tvleanback.UpdateRecommendationsService"
            android:enabled="true" />
  </application>
</manifest>

Crea consigli

Una volta avviato, il servizio di consigli deve creare consigli e passarli a al framework Android. Il framework riceve i consigli come oggetti Notification che utilizzano un modello specifico e sono contrassegnati con una categoria specifica.

Imposta i valori

Per impostare i valori degli elementi dell'interfaccia utente per la scheda dei consigli, crea una classe di creazione che segue il pattern di creazione descritto di seguito. Innanzitutto, imposta i valori degli elementi della scheda dei consigli.

Kotlin

class RecommendationBuilder {
    ...

    fun setTitle(title: String): RecommendationBuilder {
        this.title = title
        return this
    }

    fun setDescription(description: String): RecommendationBuilder {
        this.description = description
        return this
    }

    fun setImage(uri: String): RecommendationBuilder {
        imageUri = uri
        return this
    }

    fun setBackground(uri: String): RecommendationBuilder {
        backgroundUri = uri
        return this
    }

...

Java

public class RecommendationBuilder {
    ...

    public RecommendationBuilder setTitle(String title) {
            this.title = title;
            return this;
        }

        public RecommendationBuilder setDescription(String description) {
            this.description = description;
            return this;
        }

        public RecommendationBuilder setImage(String uri) {
            imageUri = uri;
            return this;
        }

        public RecommendationBuilder setBackground(String uri) {
            backgroundUri = uri;
            return this;
        }
...

Crea la notifica

Dopo aver impostato i valori, crea la notifica, assegnando i valori dalla classe di creazione alla notifica e chiamando NotificationCompat.Builder.build().

Inoltre, assicurati di chiamare setLocalOnly() in modo che la notifica NotificationCompat.BigPictureStyle non venga visualizzata su altri dispositivi.

Il seguente esempio di codice mostra come creare un consiglio.

Kotlin

class RecommendationBuilder {
    ...

    @Throws(IOException::class)
    fun build(): Notification {
        ...

        val notification = NotificationCompat.BigPictureStyle(
        NotificationCompat.Builder(context)
                .setContentTitle(title)
                .setContentText(description)
                .setPriority(priority)
                .setLocalOnly(true)
                .setOngoing(true)
                .setColor(context.resources.getColor(R.color.fastlane_background))
                .setCategory(Notification.CATEGORY_RECOMMENDATION)
                .setLargeIcon(image)
                .setSmallIcon(smallIcon)
                .setContentIntent(intent)
                .setExtras(extras))
                .build()

        return notification
    }
}

Java

public class RecommendationBuilder {
    ...

    public Notification build() throws IOException {
        ...

        Notification notification = new NotificationCompat.BigPictureStyle(
                new NotificationCompat.Builder(context)
                        .setContentTitle(title)
                        .setContentText(description)
                        .setPriority(priority)
                        .setLocalOnly(true)
                        .setOngoing(true)
                        .setColor(context.getResources().getColor(R.color.fastlane_background))
                        .setCategory(Notification.CATEGORY_RECOMMENDATION)
                        .setLargeIcon(image)
                        .setSmallIcon(smallIcon)
                        .setContentIntent(intent)
                        .setExtras(extras))
                .build();

        return notification;
    }
}

Esegui il servizio di consigli per la corsa

Il servizio di consigli della tua app deve essere eseguito periodicamente per creare consigli attuali raccomandazioni. Per eseguire il servizio, crea una classe che esegua un timer e lo richiami a intervalli regolari. Il seguente esempio di codice estende la classe BroadcastReceiver per avviare l'esecuzione periodica di un servizio di consigli ogni mezz'ora:

Kotlin

class BootupActivity : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        Log.d(TAG, "BootupActivity initiated")
        if (intent.action.endsWith(Intent.ACTION_BOOT_COMPLETED)) {
            scheduleRecommendationUpdate(context)
        }
    }

    private fun scheduleRecommendationUpdate(context: Context) {
        Log.d(TAG, "Scheduling recommendations update")
        val alarmManager = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
        val recommendationIntent = Intent(context, UpdateRecommendationsService::class.java)
        val alarmIntent = PendingIntent.getService(context, 0, recommendationIntent, 0)
        alarmManager.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP,
                INITIAL_DELAY,
                AlarmManager.INTERVAL_HALF_HOUR,
                alarmIntent
        )
    }

    companion object {
        private val TAG = "BootupActivity"
        private val INITIAL_DELAY:Long = 5000
    }
}

Java

public class BootupActivity extends BroadcastReceiver {
    private static final String TAG = "BootupActivity";

    private static final long INITIAL_DELAY = 5000;

    @Override
    public void onReceive(Context context, Intent intent) {
        Log.d(TAG, "BootupActivity initiated");
        if (intent.getAction().endsWith(Intent.ACTION_BOOT_COMPLETED)) {
            scheduleRecommendationUpdate(context);
        }
    }

    private void scheduleRecommendationUpdate(Context context) {
        Log.d(TAG, "Scheduling recommendations update");

        AlarmManager alarmManager = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE);
        Intent recommendationIntent = new Intent(context, UpdateRecommendationsService.class);
        PendingIntent alarmIntent = PendingIntent.getService(context, 0, recommendationIntent, 0);

        alarmManager.setInexactRepeating(AlarmManager.ELAPSED_REALTIME_WAKEUP,
                INITIAL_DELAY,
                AlarmManager.INTERVAL_HALF_HOUR,
                alarmIntent);
    }
}

Questa implementazione della classe BroadcastReceiver deve essere eseguita dopo l'avvio del dispositivo TV su cui è installata. Per farlo, registra questa classe nel manifest dell'app con un filtro per intent che rimane in ascolto del completamento del processo di avvio del dispositivo. Il seguente codice campione mostra come aggiungere questa configurazione al file manifest: 

<manifest ... >
  <application ... >
    <receiver android:name="com.example.android.tvleanback.BootupActivity"
              android:enabled="true"
              android:exported="false">
      <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED"/>
      </intent-filter>
    </receiver>
  </application>
</manifest>

Importante: per ricevere una notifica di avvio completato, la tua app deve richiedere l'autorizzazione RECEIVE_BOOT_COMPLETED. Per ulteriori informazioni, consulta ACTION_BOOT_COMPLETED.

Nel metodo onHandleIntent() della classe del servizio di consigli, pubblica il consiglio nel gestore come segue:

Kotlin

val notification = notificationBuilder.build()
notificationManager.notify(id, notification)

Java

Notification notification = notificationBuilder.build();
notificationManager.notify(id, notification);
Indietro
Visualizza l'anteprima dei video