„Weiter ansehen“ mit der REST API einbinden

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

Das Engage SDK bietet eine REST API, um eine einheitliche Funktion „Auf dem Fernseher weiter ansehen“ auf Nicht-Android-Plattformen wie iOS und Roku TV zu ermöglichen. Mit der API können Entwickler den Status „Weiter ansehen“ für Nutzer, die die Funktion aktiviert haben, von Nicht-Android-Plattformen aus aktualisieren.

Voraussetzungen

Sie müssen zuerst die auf dem Gerät basierende Integration des Engage SDK abschließen. In diesem wichtigen Schritt wird die erforderliche Verknüpfung zwischen der Google-Nutzer-ID und der AccountProfile Ihrer App hergestellt.
API-Zugriff und ‑Authentifizierung: Wenn Sie die API in Ihrem Google Cloud-Projekt aufrufen und aktivieren möchten, müssen Sie ein Zulassungslistenverfahren durchlaufen. Für alle API-Anfragen ist eine Authentifizierung erforderlich.

Zugriff erhalten

Damit Sie in der Google Cloud Console auf die API zugreifen und sie aktivieren können, muss Ihr Konto registriert sein.

Die Google Workspace-Kundennummer sollte verfügbar sein. Falls nicht, müssen Sie möglicherweise ein Google Workspace-Konto sowie alle Google-Konten einrichten, die Sie zum Aufrufen der API verwenden möchten.
Richten Sie ein Konto mit der Google Cloud Console ein. Verwenden Sie dazu eine E-Mail-Adresse, die mit Google Workspace verknüpft ist.
Neues Projekt erstellen
Erstellen Sie ein Dienstkonto für die API-Authentifizierung. Nachdem Sie das Dienstkonto erstellt haben, haben Sie zwei Elemente:
- Eine Dienstkonto-ID.
- Eine JSON-Datei mit Ihrem Dienstkontoschlüssel. Bewahren Sie diese Datei sicher auf. Sie benötigen sie später, um Ihren Client für die API zu authentifizieren.
Workspace und zugehörige Google-Konten können jetzt REST APIs verwenden. Sobald die Änderung übernommen wurde, werden Sie benachrichtigt, ob die API von Ihren Dienstkonten aufgerufen werden kann.
Folgen Sie dieser Anleitung, um einen delegierten API-Aufruf vorzubereiten.

Fortsetzungscluster veröffentlichen

Senden Sie eine POST-Anfrage an die publishContinuationCluster API, um die Daten zur Videoermittlung zu veröffentlichen. Verwenden Sie dazu die folgende Syntax.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

Dabei gilt:

package_name: Der Paketname des Media-Anbieters
accountId: Die eindeutige ID für das Konto des Nutzers in Ihrem System. Sie muss mit der accountId übereinstimmen, die im On-Device-Pfad verwendet wird.
profileId: Die eindeutige ID für das Profil des Nutzers im Konto in Ihrem System. Sie muss mit der im On-Device-Pfad verwendeten „profileId“ übereinstimmen.

Die URL für das Konto ohne Profil lautet:

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

Die Nutzlast für die Anfrage wird im Feld entities dargestellt. entities steht für eine Liste von Inhaltseinheiten, die entweder MovieEntity oder TVEpisodeEntity sein können. Dieses Feld ist erforderlich.

Anfragetext

Field	Typ	Erforderlich	Beschreibung
Entitäten	Liste der MediaEntity-Objekte	Ja	Liste mit maximal fünf Inhaltseinheiten. Nur die fünf besten werden beibehalten, die anderen werden gelöscht. Eine leere Liste ist zulässig, um anzugeben, dass der Nutzer alle Elemente angesehen hat.

Das Feld entities enthält einzelne movieEntity und tvEpisodeEntity.

Field	Typ	Erforderlich	Beschreibung
movieEntity	MovieEntity	Ja	Ein Objekt, das einen Film im ContinuationCluster darstellt.
tvEpisodeEntity	TVEpisodeEntity	Ja	Ein Objekt, das eine TV-Folge im ContinuationCluster darstellt.

Jedes Objekt im Array „entities“ muss einer der verfügbaren MediaEntity-Typen sein, nämlich MovieEntity und TvEpisodeEntity, zusammen mit allgemeinen und typspezifischen Feldern.

Das folgende Code-Snippet zeigt die Nutzlast des Anfragetexts für die publishContinuationCluster API.

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/movie1_img1.png",
          "http://www.example.com/movie1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/episode1_img1.png",
          "http://www.example.com/episode1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    }
  ]
}

Daten zur Videoermittlung löschen

Verwenden Sie die clearClusters API, um die Daten zur Videoermittlung zu entfernen.

Wenn Sie die Daten des Fortsetzungsclusters löschen möchten, senden Sie eine POST-Anfrage an die clearClusters API mit der folgenden Syntax.

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearClusters

Dabei gilt:

package_name: Der Paketname des Media-Anbieters.
accountId: Die eindeutige ID für das Konto des Nutzers in Ihrem System. Sie muss mit der accountId übereinstimmen, die im On-Device-Pfad verwendet wird.
profileId: Die eindeutige ID für das Profil des Nutzers im Konto in Ihrem System. Sie muss mit der im On-Device-Pfad verwendeten „profileId“ übereinstimmen.

Die Nutzlast für die clearClusters API enthält nur ein Feld, reason, das einen DeleteReason enthält, der den Grund für das Entfernen von Daten angibt.

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

Testen

Nachdem Sie Daten erfolgreich gepostet haben, verwenden Sie ein Nutzer-Testkonto, um zu überprüfen, ob die erwarteten Inhalte in der Zeile „Weiter ansehen“ auf den Google-Zielplattformen wie Google TV und den mobilen Google TV-Apps für Android und iOS angezeigt werden.

Bei Tests solltest du eine angemessene Verzögerung von einigen Minuten einplanen und die Wiedergabeanforderungen einhalten, z. B. einen Teil eines Films ansehen oder eine Folge zu Ende ansehen. Weitere Informationen finden Sie in den Empfehlungen zu „Als Nächstes ansehen“ für App-Entwickler.