Kanäle auf dem Startbildschirm

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:

Startbildschirm des Fernsehers

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:

Cool

implementation 'androidx.tvprovider:tvprovider:1.0.0'

Kotlin

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:

Kotlin

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

Java

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:

    Maske mit Symbolen für den Startbildschirm des Fernsehers

    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:

Kotlin

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

Java

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

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

Löschen eines Kanals

Kotlin

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

Java

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:

Kotlin

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

Java

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:

Kotlin

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

Java

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

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

Kotlin

val programId = ContentUris.parseId(programUri)

Java

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:

Kotlin

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

Java

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

Programm löschen

Kotlin

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

Java

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:

Kotlin

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
}

Java

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:

Attribut Hinweise
SCHREIBMASCHINE auf TYPE_PREVIEW festgelegt.
DISPLAY_NAME auf den Namen des Channels festgelegt.
APP_LINK_INTENT_URI Wenn der Nutzer das Logo des Kanals auswählt, sendet das System einen Intent, um eine Aktivität zu starten, bei der für den Kanal relevante Inhalte präsentiert werden. Legen Sie dieses Attribut auf den URI fest, der im Intent-Filter für diese Aktivität verwendet wird.

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:

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.

Zurück
Empfehlungen für TV-Inhalte
Weiter
Attribute für Videoprogramme