Das Engage SDK bietet eine REST API, um auf Nicht-Android-Plattformen wie iOS und Roku TV eine einheitliche Funktion zum Fortsetzen der Wiedergabe zu ermöglichen. Mit der API können Entwickler den Status „Weiter ansehen“ für angemeldete Nutzer auf Nicht-Android-Plattformen aktualisieren.
Vorbereitung
- Sie müssen zuerst die gerätebasierte Engage SDK-
Integration abschließen. Mit diesem wichtigen Schritt wird die erforderliche Verknüpfung zwischen der Google-Nutzer-ID und dem
AccountProfileIhrer App hergestellt. - API-Zugriff und -Authentifizierung: Wenn Sie die API in Ihrem Google Cloud-Projekt aufrufen und aktivieren möchten, müssen Sie einen Prozess für die Zulassungsliste durchlaufen. Für alle API-Anfragen ist eine Authentifizierung erforderlich.
Zugriff erhalten
Damit Sie die API in der Google Cloud Console aufrufen und aktivieren können, muss Ihr Konto registriert sein.
- Die Google Workspace-Kundennummer sollte verfügbar sein. Wenn sie nicht verfügbar ist, müssen Sie möglicherweise Google Workspace sowie alle Google-Konten einrichten, die Sie zum Aufrufen der API verwenden möchten.
- Richten Sie ein Konto in der Google Cloud Console mit einer E-Mail-Adresse ein, die mit Google Workspace verknüpft ist.
- Erstellen Sie ein neues Projekt.
- 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 bei der API zu authentifizieren.
- Google Workspace und verknüpfte 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 diesen Schritten, um sich auf einen delegierten API-Aufruf vorzubereiten.
Fortsetzungscluster veröffentlichen
Wenn Sie die Engage-Daten veröffentlichen möchten, senden Sie eine POST-Anfrage an die publishContinuationCluster API mit der folgenden Syntax.
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster
Wobei:
package_name: Der Paketname des Media-AnbietersaccountId: Die eindeutige ID für das Konto des Nutzers in Ihrem System. Sie muss mit deraccountIdübereinstimmen, die im gerätebasierten Pfad verwendet wird.profileId: Die eindeutige ID für das Profil des Nutzers im Konto in Ihrem System. Sie muss mit der profileId übereinstimmen, die im gerätebasierten Pfad verwendet wird.
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 Content-Entitäten, die aus einem oder mehreren der folgenden Elemente bestehen können: MovieEntity, TVEpisodeEntity, LiveStreamingVideoEntity oder VideoClipEntity.
Dieses Feld ist erforderlich.
Anfragetext
Feld |
Typ |
Erforderlich |
Beschreibung |
entities |
Liste von MediaEntity-Objekten |
Ja |
Liste von Content-Entitäten mit maximal fünf Einträgen. Nur die ersten fünf werden beibehalten, die übrigen werden gelöscht. Eine leere Liste ist zulässig, um anzugeben, dass der Nutzer alle Entitäten angesehen hat. |
Das Feld entities enthält die einzelnen Elemente movieEntity, tvEpisodeEntity, liveStreamingVideoEntity und videoClipEntity.
Feld |
Typ |
Beschreibung |
movieEntity |
MovieEntity |
Ein Objekt, das einen Film im Fortsetzungscluster darstellt. |
tvEpisodeEntity |
TvEpisodeEntity |
Ein Objekt, das eine Folge im Fortsetzungscluster darstellt. |
liveStreamingVideoEntity |
LiveStreamingVideoEntity |
Ein Objekt, das ein Livestreaming-Video im Fortsetzungscluster darstellt. |
videoClipEntity |
VideoClipEntity |
Ein Objekt, das einen Videoclip im Fortsetzungscluster darstellt. |
Jedes Objekt im Array „entities“ muss einer der verfügbaren
MediaEntity-Typen sein, nämlich MovieEntity,
TvEpisodeEntity,
LiveStreamingVideoEntity, oder
VideoClipEntity,
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": [
{
"uri": "https://www.example.com/movie_entity_uri_for_android",
"platforms": [
"PLATFORM_ANDROID_TV",
"PLATFORM_ANDROID"
]
},
{
"uri": "https://www.example.com/movie_entity_uri_for_iOS",
"platforms": [
"PLATFORM_IOS"
]
}
],
"poster_images": [
{
"url": "http://www.example.com/movie1_img1.png",
"width": 1920,
"height": 1080,
"accessibility_text": "Movie 1 HD poster"
},
{
"url": "http://www.example.com/movie1_imag2.png",
"width": 640,
"height": 360,
"accessibility_text": "Movie 1 SD poster"
}
],
"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": [
{
"uri": "https://www.example.com/episode_entity_uri_for_android_mobile",
"platforms": [
"PLATFORM_ANDROID"
]
},
{
"uri": "https://www.example.com/episode_entity_uri_for_android_tv",
"platforms": [
"PLATFORM_ANDROID_TV"
]
},
{
"uri": "https://www.example.com/episode_entity_uri_for_iOS",
"platforms": [
"PLATFORM_IOS"
]
}
],
"poster_images": [
{
"url": "http://www.example.com/episode1_img1.png",
"width": 1920,
"height": 1080,
"accessibility_text": "Episode 1 HD poster"
},
{
"url": "http://www.example.com/episode1_imag2.png",
"width": 640,
"height": 360,
"accessibility_text": "Episode 1 SD poster"
}
],
"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"
}
},
{
"liveStreamingVideoEntity": {
"name": "Live Sports Championship",
"watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
"last_engagement_time_millis": 1780978284000,
"last_play_back_position_time_millis": 1800000,
"duration_millis": 7200000,
"platform_specific_playback_uris": [
{
"uri": "https://www.example.com/live_streaming_entity_uri_for_android_tv",
"platforms": ["PLATFORM_ANDROID_TV"]
}
],
"poster_images": [
{
"url": "http://www.example.com/live_stream_image1.png",
"width": 1920,
"height": 1080,
"accessibility_text": "Live Sports Championship Cover Image"
}
],
"start_time_epoch_millis": 1780976484000,
"broadcaster": "Global Sports Network",
"broadcaster_icon": {
"url": "https://www.example.com/gsports.jpg",
"width": 512,
"height": 512,
"accessibility_text": "Global Sports Network Logo"
}
}
},
{
"videoClipEntity": {
"name": "How to Brew the Perfect Espresso",
"watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
"last_engagement_time_millis": 1780978284000,
"last_play_back_position_time_millis": 120000,
"duration_millis": 600000,
"platform_specific_playback_uris": [
{
"uri": "https://www.example.com/video_clip_entity_uri_for_android_tv",
"platforms": ["PLATFORM_ANDROID_TV"]
}
],
"poster_images": [
{
"url": "http://www.example.com/video_clip_image1.png",
"width": 1920,
"height": 1080,
"accessibility_text": "Espresso Tutorial Cover Image"
}
],
"created_time_epoch_millis": 1780900000000,
"creator": "Coffee Enthusiast John",
"creator_image": {
"url": "https://www.example.com/image/thumb/creators/john_avatar.jpg",
"width": 256,
"height": 256,
"accessibility_text": "John's Avatar"
}
}
}
]
}
Engage-Daten löschen
Verwenden Sie die clearClusters API, um die Engage-Daten 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
Wobei:
package_name: Der Paketname des Media-AnbietersaccountId: Die eindeutige ID für das Konto des Nutzers in Ihrem System. Sie muss mit deraccountIdübereinstimmen, die im gerätebasierten Pfad verwendet wird.profileId: Die eindeutige ID für das Profil des Nutzers im Konto in Ihrem System. Sie muss mit der profileId übereinstimmen, die im gerätebasierten Pfad verwendet wird.
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"
}
Test
Nachdem Sie Daten erfolgreich gepostet haben, prüfen Sie mit einem Testnutzerkonto, ob die erwarteten Inhalte in der Zeile „Weiter ansehen“ auf den Zielplattformen von Google wie Google TV und den mobilen Google TV-Apps für Android und iOS angezeigt werden.
Bei Tests sollten Sie 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 für Details.