Le SDK Engage propose une API REST pour offrir une expérience de reprise de lecture cohérente sur les plates-formes autres que la plate-forme Android, telles qu'iOS et Roku TV. L'API permet aux développeurs de mettre à jour l'état "Continuer à regarder" pour les utilisateurs ayant activé cette fonctionnalité sur des plates-formes autres que la plate-forme Android.
Prérequis
- Vous devez d'abord terminer l'intégration sur l'appareil basée sur le SDK Engage. Cette étape essentielle établit l'association nécessaire entre l'ID utilisateur de Google et l'
AccountProfilede votre application. - Accès et authentification de l'API : pour afficher et activer l'API dans votre projet Google Cloud, vous devez suivre un processus d'ajout à la liste d'autorisation. Toutes les requêtes API nécessitent une authentification.
Demandez votre accès
Pour pouvoir afficher et activer l'API dans la console Google Cloud, votre compte doit être enregistré.
- Le numéro client Google Workspace doit être disponible. Si ce n'est pas le cas, vous devrez peut-être configurer un compte Google Workspace ainsi que les comptes Google que vous souhaitez utiliser pour appeler l'API.
- Configurez un compte dans la console Google Cloud à l'aide d'une adresse e-mail associée à Google Workspace.
- Créer un projet
- Créez un compte de service pour l'authentification de l'API. Une fois le compte de service créé, vous disposez de deux éléments :
- ID d'un compte de service.
- Un fichier JSON contenant la clé de votre compte de service. Conservez ce fichier de manière sécurisée. Vous en aurez besoin pour authentifier votre client auprès de l'API ultérieurement.
- Workspace et les comptes Google associés peuvent désormais utiliser les API REST. Une fois la modification propagée, vous serez informé que l'API est prête à être appelée par vos comptes de service.
- Suivez ces étapes pour vous préparer à effectuer un appel d'API délégué.
Publier le cluster "Continuation"
Pour publier les données Engage, envoyez une requête POST à l'API publishContinuationCluster en utilisant la syntaxe suivante.
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster
Où :
package_name: nom du package du fournisseur de contenus multimédiasaccountId: Identifiant unique du compte de l'utilisateur dans votre système. Il doit correspondre auaccountIdutilisé dans le chemin d'accès sur l'appareil.profileId: ID unique du profil de l'utilisateur dans le compte de votre système. Il doit correspondre au profileId utilisé dans le chemin d'accès sur l'appareil.
L'URL du compte sans profil est :
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster
La charge utile de la requête est représentée dans le champ entities. entities représente une liste d'entités de contenu, qui peut être constituée d'un ou de plusieurs des éléments suivants : MovieEntity, TVEpisodeEntity, LiveStreamingVideoEntity ou VideoClipEntity.
Ce champ est obligatoire.
Corps de la requête
Champ |
Type |
Obligatoire |
Description |
entités |
Liste d'objets MediaEntity |
Oui |
Liste d'entités de contenu (cinq au maximum). Seuls les cinq premiers seront conservés, les autres seront supprimés. Une liste vide est autorisée pour indiquer que l'utilisateur a fini de regarder toutes les entités. |
Le champ entities contient des éléments movieEntity, tvEpisodeEntity, liveStreamingVideoEntity et videoClipEntity individuels.
Champ |
Type |
Description |
movieEntity |
MovieEntity |
Objet représentant un film dans le ContinuationCluster. |
tvEpisodeEntity |
TvEpisodeEntity |
Objet représentant un épisode de série TV dans le ContinuationCluster. |
liveStreamingVideoEntity |
LiveStreamingVideoEntity |
Objet représentant une vidéo en live streaming dans le ContinuationCluster. |
videoClipEntity |
VideoClipEntity |
Objet représentant un extrait vidéo dans ContinuationCluster. |
Chaque objet du tableau d'entités doit être l'un des types MediaEntity disponibles, à savoir MovieEntity, TvEpisodeEntity, LiveStreamingVideoEntity ou VideoClipEntity, ainsi que des champs communs et spécifiques au type.
L'extrait de code suivant présente la charge utile du corps de la requête pour l'API publishContinuationCluster.
{
"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"
}
}
}
]
}
Supprimer les données Engage
Utilisez l'API clearCluster pour supprimer les données Engage.
Pour supprimer les données du cluster de continuation, envoyez une requête POST à l'API clearCluster en utilisant la syntaxe suivante.
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearCluster
Où :
package_name: nom du package du fournisseur de contenus multimédias.accountId: Identifiant unique du compte de l'utilisateur dans votre système. Il doit correspondre auaccountIdutilisé dans le chemin d'accès sur l'appareil.profileId: ID unique du profil de l'utilisateur dans le compte de votre système. Il doit correspondre au profileId utilisé dans le chemin d'accès sur l'appareil.
L'URL du compte sans profil est :
https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/clearCluster
La charge utile de l'API clearCluster ne contient qu'un seul champ, reason, qui contient un DeleteReason spécifiant la raison de la suppression des données.
{
"reason": "DELETE_REASON_LOSS_OF_CONSENT"
}
Tests
Une fois les données publiées, utilisez un compte de test utilisateur pour vérifier que le contenu attendu s'affiche dans la ligne "Continuer à regarder" sur les surfaces Google cibles, telles que Google TV et les applications mobiles Google TV pour Android et iOS.
Lors des tests, prévoyez un délai de propagation raisonnable de quelques minutes et respectez les exigences de visionnage, par exemple en regardant une partie d'un film ou en terminant un épisode. Pour en savoir plus, consultez les consignes relatives au canal "À regarder ensuite" pour les développeurs d'applications.