Der Startbildschirm von Android TV oder einfach der Startbildschirm bietet eine Benutzeroberfläche, zeigt empfohlene Inhalte in einer Tabelle mit Channels und Programmen an. Jede Zeile steht für einen Channel. Ein Kanal enthält Infokarten für jedes dort verfügbare Programm:

In diesem Dokument wird beschrieben, wie Sie dem Startbildschirm Kanäle und Programme hinzufügen, Inhalte aktualisieren, Aktionen von Nutzern handhaben und Ihren Nutzern die bestmögliche Erfahrung bieten können. (Wenn Sie mehr über das API erfahren möchten, versuchen Sie es mit der Codelab für den Startbildschirm und schau dir die Android TV-Session zur I/O 2017 an.)

Hinweis:Empfehlungskanäle sind nur in Android 8.0 (API-Level 26) und höher Sie müssen sie nutzen, Empfehlungen für Apps mit Android 8.0 (API-Level 26) und höher Bis Empfehlungen für Apps geben, die unter älteren Android-Versionen laufen, muss die Methode Zeile „Empfehlungen“ .

Die Benutzeroberfläche des Startbildschirms

Apps können neue Kanäle erstellen, die Programme in einem Kanal hinzufügen, entfernen und aktualisieren sowie die Reihenfolge der Programme in einem Kanal steuern. Beispiel: Eine App kann einen Kanal mit dem Namen "Neue Funktionen" erstellen. und Karten für neu verfügbare Programme anzeigen.

Apps können nicht die Reihenfolge steuern, in der Kanäle auf dem Startbildschirm angezeigt werden. Wenn Ihre App einen neuen Kanal erstellt, wird er auf dem Startbildschirm unten in der Kanalliste hinzugefügt. Der Nutzer kann Kanäle neu anordnen, ausblenden und anzeigen.

Der Kanal „Als Nächstes ansehen“

Der Kanal „Empfohlene Videos“ ist die zweite Zeile auf dem Startbildschirm, in der Zeile „Apps“. Dieser Channel wird vom System erstellt und verwaltet. Deine App kann Folgendes hinzufügen: zum Kanal „Als Nächstes ansehen“ hinzugefügt. Weitere Informationen finden Sie unter Programme hinzufügen zu den Kanal „Als Nächstes ansehen“.

App-Kanäle

Die von deiner App erstellten Kanäle folgen alle diesem Lebenszyklus:

1. Der Nutzer entdeckt einen Kanal in deiner App und bittet ihn, ihn dem Startbildschirm hinzuzufügen.
2. Die App erstellt den Kanal und fügt ihn TvProvider hinzu. Der Kanal ist zu diesem Zeitpunkt nicht sichtbar.
3. Die App fordert das System auf, den Kanal anzuzeigen.
4. Das System bittet den Nutzer, den neuen Kanal zu genehmigen.
5. Der neue Kanal wird in der letzten Zeile des Startbildschirms angezeigt.

Standardkanal

Ihre App kann dem Nutzer beliebig viele Kanäle zum Hinzufügen zum Startbildschirm anbieten. In der Regel müssen die Nutzenden Kanäle auswählen und genehmigen, bevor sie auf dem Startbildschirm angezeigt werden. Sie haben für jede App die Möglichkeit, einen Standardkanal zu erstellen. Der Standardkanal ist speziell, da er automatisch auf dem Startbildschirm angezeigt wird. muss die nutzende Person explizit anfordern.

Voraussetzungen

Auf dem Android TV-Startbildschirm werden die TvProvider-APIs von Android verwendet, um die von deiner App erstellten Kanäle und Programme zu verwalten. Fügen Sie dem Manifest Ihrer App die folgende Berechtigung hinzu, um auf die Daten des Anbieters zuzugreifen:

<uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />

Die TvProvider-Supportbibliothek erleichtert die Verwendung des Anbieters. Fügen Sie ihn den Abhängigkeiten in der Datei build.gradle hinzu:

implementation 'androidx.tvprovider:tvprovider:1.0.0'

implementation("androidx.tvprovider:tvprovider:1.0.0")

Um mit Kanälen und Programmen zu arbeiten, musst du die folgenden Importe von Supportbibliotheken in dein Programm aufnehmen:

import android.support.media.tv.Channel
import android.support.media.tv.TvContractCompat
import android.support.media.tv.ChannelLogoUtils
import android.support.media.tv.PreviewProgram
import android.support.media.tv.WatchNextProgram

import android.support.media.tv.Channel;
import android.support.media.tv.TvContractCompat;
import android.support.media.tv.ChannelLogoUtils;
import android.support.media.tv.PreviewProgram;
import android.support.media.tv.WatchNextProgram;

Kanäle

Der erste von deiner App erstellte Kanal wird zum Standardkanal. Der Standardkanal wird automatisch auf dem Startbildschirm angezeigt. Alle anderen von dir erstellten Kanäle müssen vom Nutzer ausgewählt und akzeptiert werden, bevor sie auf dem Startbildschirm angezeigt werden.

Kanal erstellen

Ihre App sollte das System nur dann auffordern, neu hinzugefügte Kanäle anzuzeigen, wenn sie im Vordergrund ausgeführt wird. Dadurch wird verhindert, dass in deiner App ein Dialogfeld angezeigt wird, in dem du aufgefordert wirst, deinen Kanal hinzuzufügen, während der Nutzer eine andere App ausführt. Wenn du versuchst, einen Kanal hinzuzufügen, während du im Hintergrund läuft, gibt die onActivityResult()-Methode der Aktivität den Statuscode RESULT_CANCELED zurück.

So erstellst du einen Kanal:

1. Erstellen Sie einen Channel Builder und legen Sie seine Attribute fest. Das Feld Kanaltyp muss TYPE_PREVIEW sein. Weitere hinzufügen attributes.

   Kotlin

   val builder = Channel.Builder()
   // Every channel you create must have the type TYPE_PREVIEW
   builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
           .setDisplayName("Channel Name")
           .setAppLinkIntentUri(uri)
   

   Java

   Channel.Builder builder = new Channel.Builder();
   // Every channel you create must have the type TYPE_PREVIEW
   builder.setType(TvContractCompat.Channels.TYPE_PREVIEW)
           .setDisplayName("Channel Name")
           .setAppLinkIntentUri(uri);
   

2. Fügen Sie den Kanal in den Anbieter ein:

   Kotlin

   var channelUri = context.contentResolver.insert(
           TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues())
   

   Java

   Uri channelUri = context.getContentResolver().insert(
           TvContractCompat.Channels.CONTENT_URI, builder.build().toContentValues());
   

3. Du musst die Kanal-ID speichern, um dem Kanal Programme hinzufügen zu können . Extrahieren Sie die Kanal-ID aus dem zurückgegebenen URI:

   Kotlin

   var channelId = ContentUris.parseId(channelUri)
   

   Java

   long channelId = ContentUris.parseId(channelUri);
   

4. Du musst ein Logo für deinen Kanal hinzufügen. Verwenden Sie Uri oder Bitmap. Das Logo Das Symbol sollte 80 dp x 80 dp groß und undurchsichtig sein. Sie wird unter einem Runde Maske:

   

   Kotlin

   // Choose one or the other
   storeChannelLogo(context: Context, channelId: Long, logoUri: Uri) // also works if logoUri is a URL
   storeChannelLogo(context: Context, channelId: Long, logo: Bitmap)
   

   Java

   // Choose one or the other
   storeChannelLogo(Context context, long channelId, Uri logoUri); // also works if logoUri is a URL
   storeChannelLogo(Context context, long channelId, Bitmap logo);
   

5. Standardkanal erstellen (optional): Wenn Ihre App die erste können Sie dafür sorgen, Standardkanal, damit er auf der Startseite angezeigt wird ohne dass die Nutzenden etwas tun müssen. Andere Kanäle, die Sie erstellen sind erst sichtbar, wenn der Nutzer wählt sie aus.

   Kotlin

   TvContractCompat.requestChannelBrowsable(context, channelId)
   

   Java

   TvContractCompat.requestChannelBrowsable(context, channelId);
   

6. Lege fest, dass dein Standardkanal angezeigt wird, bevor deine App geöffnet wird. Sie können Fügen Sie dazu einen BroadcastReceiver hinzu, der auf das Ereignis android.media.tv.action.INITIALIZE_PROGRAMS Aktion, die der Startbildschirm wird gesendet, nachdem die App installiert wurde:

   <receiver
     android:name=".RunOnInstallReceiver"
     android:exported="true">
       <intent-filter>
         <action android:name="android.media.tv.action.INITIALIZE_PROGRAMS" />
         <category android:name="android.intent.category.DEFAULT" />
       </intent-filter>
   </receiver>
   

   Beim Sideloading Ihrer App während der Entwicklung können Sie diesen Schritt testen, indem Sie das Auslösen der Absicht durch ADB, your.package.name/.YourReceiverName gehört zu deiner App BroadcastReceiver:

   adb shell am broadcast -a android.media.tv.action.INITIALIZE_PROGRAMS -n \
       your.package.name/.YourReceiverName
   

   In seltenen Fällen kann es vorkommen, dass Ihre App die Übertragung gleichzeitig empfängt, startet Ihre App. Achte darauf, dass mit deinem Code nicht versucht wird, den Standardkanal hinzuzufügen mehrfach verwenden.

Kanal aktualisieren

Das Aktualisieren von Channels funktioniert ähnlich wie das Erstellen von Channels.

Verwenden Sie einen anderen Channel.Builder, um die zu ändernden Attribute festzulegen.

Verwende die ContentResolver, um den Kanal zu aktualisieren. Verwende die Kanal-ID, die du beim ursprünglichen Hinzufügen des Kanals gespeichert hast:

context.contentResolver.update(
        TvContractCompat.buildChannelUri(channelId),
        builder.build().toContentValues(),
        null,
        null
)

context.getContentResolver().update(TvContractCompat.buildChannelUri(channelId),
    builder.build().toContentValues(), null, null);

Verwende storeChannelLogo(), um das Logo eines Kanals zu aktualisieren.

Löschen eines Kanals

context.contentResolver.delete(TvContractCompat.buildChannelUri(channelId), null, null)

context.getContentResolver().delete(TvContractCompat.buildChannelUri(channelId), null, null);

Programme

Hinzufügen von Programmen zu einem App-Kanal

Erstellen Sie eine PreviewProgram.Builder und legen Sie ihre Attribute fest:

val builder = PreviewProgram.Builder()
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId)

PreviewProgram.Builder builder = new PreviewProgram.Builder();
builder.setChannelId(channelId)
        .setType(TvContractCompat.PreviewPrograms.TYPE_CLIP)
        .setTitle("Title")
        .setDescription("Program description")
        .setPosterArtUri(uri)
        .setIntentUri(uri)
        .setInternalProviderId(appProgramId);

Fügen Sie je nach Art des Programms weitere Attribute hinzu. Um die Attribute anzuzeigen, die für die einzelnen Programmtypen verfügbar sind, finden Sie in den Tabellen unten.

Fügen Sie das Programm in den Anbieter ein:

var programUri = context.contentResolver.insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
        builder.build().toContentValues())

Uri programUri = context.getContentResolver().insert(TvContractCompat.PreviewPrograms.CONTENT_URI,
      builder.build().toContentValues());

Rufe die Programm-ID zur späteren Verwendung ab:

val programId = ContentUris.parseId(programUri)

long programId = ContentUris.parseId(programUri);

Programme zum Kanal „Als Nächstes ansehen“ hinzufügen

Informationen zum Einfügen von Sendungen in den Kanal „Als Nächstes ansehen“ findest du unter Programme zur Wiedergabeseite hinzufügen Nächster Kanal.

Programm aktualisieren

Sie können die Angaben zu einem Programm ändern. Sie können beispielsweise den Leihpreis für einen Film aktualisieren oder eine Fortschrittsanzeige aktualisieren, die anzeigt, wie lange der Nutzer sich ein Programm angesehen hat.

Verwenden Sie einen PreviewProgram.Builder, um die zu ändernden Attribute festzulegen. Rufen Sie dann getContentResolver().update auf, um das Programm zu aktualisieren. Gib die Programm-ID an, die du beim ursprünglichen Hinzufügen des Programms gespeichert hast:

context.contentResolver.update(
        TvContractCompat.buildPreviewProgramUri(programId),
                builder.build().toContentValues(), null, null
)

context.getContentResolver().update(TvContractCompat.buildPreviewProgramUri(programId),
    builder.build().toContentValues(), null, null);

Programm löschen

context.contentResolver
        .delete(TvContractCompat.buildPreviewProgramUri(programId), null, null)

context.getContentResolver().delete(TvContractCompat.buildPreviewProgramUri(programId), null, null);

Nutzeraktionen verarbeiten

Deine App kann Nutzern beim Entdecken von Inhalten helfen, indem sie eine Benutzeroberfläche zum Anzeigen und Hinzufügen von Kanälen bereitstellt. Deine App sollte auch Interaktionen mit deinen Kanälen verarbeiten, nachdem sie auf dem Startbildschirm angezeigt wurden.

Kanäle finden und hinzufügen

Ihre App kann ein UI-Element bereitstellen, über das der Nutzer Kanäle auswählen und hinzufügen kann, z. B. eine Schaltfläche zum Hinzufügen des Kanals.

Nachdem der Nutzer einen bestimmten Kanal angefordert hat, führen Sie diesen Code aus, um die Berechtigung des Nutzers zu erhalten, ihn zur Benutzeroberfläche des Startbildschirms hinzuzufügen:

val intent = Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE)
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId)
try {
  activity.startActivityForResult(intent, 0)
} catch (e: ActivityNotFoundException) {
  // handle error
}

Intent intent = new Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE);
intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId);
try {
   activity.startActivityForResult(intent, 0);
} catch (ActivityNotFoundException e) {
  // handle error
}

Es wird ein Dialogfeld angezeigt, in dem der Nutzer aufgefordert wird, den Kanal zu genehmigen. Verarbeite das Ergebnis der Anfrage mit der onActivityResult-Methode deiner Aktivität (Activity.RESULT_CANCELED oder Activity.RESULT_OK).

Ereignisse auf dem Android TV-Startbildschirm

Wenn der Nutzer mit den von der App veröffentlichten Programmen/Kanälen interagiert, sendet der Startbildschirm Intents an die App:

• Der Startbildschirm sendet die im APP_LINK_INTENT_URI-Attribut eines Kanals gespeicherten Uri an die App, wenn der Nutzer das Logo des Kanals auswählt. Die App sollte nur ihre Hauptbenutzeroberfläche oder eine Ansicht für den ausgewählten Kanal starten.
• Der Startbildschirm sendet den im INTENT_URI-Attribut eines Programms gespeicherten Uri an die App, wenn der Nutzer ein Programm auswählt. Die App sollte die ausgewählten Inhalte wiedergeben.
• Der Nutzer kann angeben, dass er nicht mehr an einem Programm interessiert ist, und möchte, dass es von der Benutzeroberfläche des Startbildschirms entfernt wird. Das System entfernt das Programm von der Benutzeroberfläche und sendet der App, zu der das Programm gehört, einen Intent (android.media.tv.ACTION_PREVIEW_PROGRAM_BROWSABLE_DISABLED oder android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED) mit der Programm-ID. Die App sollte das Programm vom Anbieter entfernen und nicht wieder einlegen.

Erstellen Sie Intent-Filter für alle Uris, die der Startbildschirm für Nutzerinteraktionen sendet. Beispiel:

<receiver
   android:name=".WatchNextProgramRemoved"
   android:enabled="true"
   android:exported="true">
   <intent-filter>
       <action android:name="android.media.tv.ACTION_WATCH_NEXT_PROGRAM_BROWSABLE_DISABLED" />
   </intent-filter>
</receiver>

Best Practices

• Bei vielen TV-Apps ist eine Anmeldung erforderlich. In diesem Fall ist BroadcastReceiver der auf android.media.tv.action.INITIALIZE_PROGRAMS wartet, sollte Kanalinhalte für nicht authentifizierte Nutzer.Ihre App kann beispielsweise anfangs die besten oder aktuell beliebtesten Inhalte anzuzeigen. Nachdem sich der Nutzer angemeldet hat, personalisierte Inhalte anzuzeigen. Dies ist eine große Chance für Apps, um Up-Selling zu betreiben. bevor sie sich anmelden.
• Wenn Ihre App nicht im Vordergrund ausgeführt wird und Sie einen Kanal oder eine Programm mit dem JobScheduler, um die Arbeit zu planen (siehe: JobScheduler und JobService).
• Bei einem fehlerhaften Verhalten deiner App kann das System die Anbieterberechtigungen deiner App widerrufen. (z. B. kontinuierliches Spamming des Anbieters mit Daten). Achten Sie darauf, den Code, der auf den Anbieter zugreift, in Try-Catch-Klauseln Sicherheitsausnahmen.

• Bevor Sie Programme und Kanäle aktualisieren, fragen Sie den Anbieter nach den Daten, die Daten aktualisieren und abgleichen müssen. Beispielsweise ist es nicht notwendig, ein Programm, das Nutzende von der Benutzeroberfläche entfernen lassen möchten. Verwenden Sie einen Hintergrundjob, fügt Ihre Daten beim Anbieter ein bzw. aktualisiert sie nach der Abfrage der vorhandenen und fordern dann die Genehmigung für Ihre Channels an. Sie können diesen Job ausführen, wenn und wann immer die App ihre Daten aktualisieren muss.

  Kotlin

  context.contentResolver
    .query(
        TvContractCompat.buildChannelUri(channelId),
            null, null, null, null).use({
                cursor-> if (cursor != null and cursor.moveToNext()) {
                             val channel = Channel.fromCursor(cursor)
                             if (channel.isBrowsable()) {
                                 //update channel's programs
                             }
                         }
            })
  

  Java

  try (Cursor cursor = context.getContentResolver()
        .query(
            TvContractCompat.buildChannelUri(channelId),
            null,
            null,
            null,
            null)) {
                if (cursor != null && cursor.moveToNext()) {
                    Channel channel = Channel.fromCursor(cursor);
                    if (channel.isBrowsable()) {
                        //update channel's programs
                    }
                }
            }
  

• Verwenden Sie für alle Bilder eindeutige URIs (Logos, Symbole, Inhaltsbilder). Achten Sie darauf, einen anderen URI zu verwenden, wenn Sie ein Bild aktualisieren. Alle Bilder werden im Cache gespeichert. Wenn Sie den URI beim Ändern des Bildes nicht ändern, wird das alte Bild weiterhin angezeigt.

• Denken Sie daran, dass WHERE-Klauseln nicht zulässig sind und Aufrufe an Anbieter mit WHERE-Klauseln eine Sicherheitsausnahme auslösen.

Attribute

In diesem Abschnitt werden die Kanal- und Programmattribute separat beschrieben.

Kanalattribute

Die folgenden Attribute müssen für jeden Kanal angegeben werden:

Darüber hinaus verfügt ein Kanal über sechs Felder, die für die interne App-Nutzung reserviert sind. In diesen Feldern können Schlüssel oder andere Werte gespeichert werden, mit denen die App den Kanal seiner internen Datenstruktur zuordnen kann:

• INTERNE_PROVIDER_ID
• INTERNE_PROVIDER_DATA
• INTERN_ANBIETER_FLAG1
• INTERN_ANBIETER_FLAG2
• INTERN_ANBIETER_FLAG3
• INTERN_ANBIETER_FLAG4

Programmattribute

Die Attribute für die einzelnen Programmtypen finden Sie auf den einzelnen Seiten:

• Attribute des Videoprogramms
• Attribute des Audioprogramms
• Attribute des Programms für Glücksspiele
• Attribute des Programms „Empfohlene Videos“

Beispielcode

Weitere Informationen zum Erstellen von Apps, die mit dem Startbildschirm interagieren und Kanäle und Programme zum Android TV-Startbildschirm hinzufügen, findest du in unserem Codelab für den Startbildschirm.