Guide d'intégration du SDK Engage pour la TV

La fonctionnalité Continuer à regarder utilise le cluster Continuation pour afficher les vidéos inachevées et les prochains épisodes à regarder de la même saison TV, à partir de plusieurs applications dans un même groupe d'UI. Vous pouvez mettre en avant leurs entités dans ce cluster de continuation. Ce guide vous explique comment améliorer l'engagement des utilisateurs grâce à l'expérience "Reprendre la lecture" à l'aide du SDK Engage.

Travail préalable

Avant de commencer, procédez comme suit :

1. Mettre à jour pour cibler l'API 19 ou version ultérieure

2. Ajoutez la bibliothèque com.google.android.engage à votre application :

   Il existe des SDK distincts à utiliser pour l'intégration : un pour les applications mobiles et un pour les applications TV.

   Mobile

   
     dependencies {
       implementation 'com.google.android.engage:engage-core:1.5.5
     }
   

   TV

   
     dependencies {
       implementation 'com.google.android.engage:engage-tv:1.0.2
     }
   

3. Définissez l'environnement du service Engage sur "production" dans le fichier AndroidManifest.xml.

   Mobile

   
   <meta-data
       android:name="com.google.android.engage.service.ENV"
       android:value="PRODUCTION" />
   

   TV

   
   <meta-data
       android:name="com.google.android.engage.service.ENV"
       android:value="PRODUCTION" />
   

4. Ajouter l'autorisation pour WRITE_EPG_DATA pour l'APK TV

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

5. Vérifiez la publication de contenu fiable à l'aide d'un service en arrière-plan, tel que androidx.work, pour la planification.

6. Pour offrir une expérience de visionnage fluide, publiez les données de "Continuer à regarder" lorsque ces événements se produisent :

   1. Première connexion : lorsque l'utilisateur se connecte pour la première fois, publiez les données pour vous assurer que son historique de visionnage est immédiatement disponible.
   2. Création ou changement de profil (applications multiprofils) : si votre application est compatible avec plusieurs profils, publiez des données lorsqu'un utilisateur crée ou change de profil.
   3. Interruption de la lecture vidéo : pour aider les utilisateurs à reprendre la lecture là où ils l'ont laissée, publiez des données lorsqu'ils mettent en pause ou arrêtent une vidéo, ou lorsque l'application se ferme pendant la lecture.
   4. Mises à jour de la section "Reprendre la lecture" (si elle est disponible) : lorsqu'un utilisateur supprime un élément de sa section "Reprendre la lecture", reflétez ce changement en publiant des données mises à jour.
   5. Vidéo terminée :
      1. Pour les films, supprimez le film terminé de la section "Continuer la lecture". Si le film fait partie d'une série, ajoutez le film suivant pour maintenir l'engagement de l'utilisateur.
      2. Pour les épisodes, supprimez l'épisode terminé et ajoutez le prochain épisode de la série, s'il est disponible, pour encourager les utilisateurs à continuer à regarder la série.

Exemple de code

Cette application exemple montre aux développeurs comment s'intégrer aux API de découverte de vidéos pour envoyer des données utilisateur personnalisées à Google. L'application exemple montre également comment créer un module commun qui peut être importé dans les applications mobiles et TV, quand appeler les API de publication et de suppression, et comment utiliser les Workers pour appeler les API de publication et de suppression.

Intégration

AccountProfile

Pour permettre une expérience "Reprendre la lecture" personnalisée sur Google TV, fournissez des informations sur le compte et le profil. Utilisez AccountProfile pour fournir :

1. ID de compte : identifiant unique représentant le compte de l'utilisateur dans votre application. Il peut s'agir de l'ID de compte réel ou d'une version correctement masquée.

2. ID de profil (facultatif) : si votre application accepte plusieurs profils dans un même compte, indiquez un identifiant unique pour le profil utilisateur spécifique (encore une fois, réel ou masqué).

// If your app only supports account
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .build()

// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
    .setAccountId("your_users_account_id")
    .setProfileId("your_users_profile_id")
    .build()

Créer des entités

Le SDK a défini différentes entités pour représenter chaque type d'élément. Le cluster de continuation accepte les entités suivantes :

1. MovieEntity
2. TvEpisodeEntity
3. LiveStreamingVideoEntity
4. VideoClipEntity

Spécifiez les URI et les affiches spécifiques à la plate-forme pour ces entités.

Créez également des URI de lecture pour chaque plate-forme (Android TV, Android ou iOS, par exemple), si ce n'est pas déjà fait. Ainsi, lorsqu'un utilisateur continue de regarder du contenu sur chaque plate-forme, l'application utilise un URI de lecture ciblé pour lire le contenu vidéo.

// Required. Set this when you want continue watching entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_TV)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
    .build()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
val playbackUriAndroid = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
    .build()

// Optional. Set this when you want continue watching entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_IOS)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
    .build()

val platformSpecificPlaybackUris =
    Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

Les images de couverture nécessitent un URI et des dimensions en pixels (hauteur et largeur). Ciblez différents facteurs de forme en fournissant plusieurs images d'affiche, mais vérifiez que toutes les images conservent un format 16:9 et une hauteur minimale de 200 pixels pour que l'entité "Reprendre la lecture" s'affiche correctement, en particulier dans l'Espace Divertissement de Google. Les images dont la hauteur est inférieure à 200 pixels ne seront peut-être pas diffusées.

val images = Arrays.asList(
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
        .setImageHeightInPixel(300)
        .setImageWidthInPixel(169)
        .build(),
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image2.png"))
        .setImageHeightInPixel(640)
        .setImageWidthInPixel(360)
        .build()
    // Consider adding other images for different form factors
)

MovieEntity

Cet exemple montre comment créer un MovieEntity avec tous les champs requis :

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

En fournissant des informations telles que les genres et les classifications de contenu, vous permettez à Google TV de présenter votre contenu de manière plus dynamique et de le mettre en relation avec les bons spectateurs.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

Les entités restent automatiquement disponibles pendant 60 jours, sauf si vous spécifiez une durée d'expiration plus courte. Ne définissez une expiration personnalisée que si vous avez besoin que l'entité soit supprimée avant cette période par défaut.

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = DisplayTimeWindow.Builder()
    .setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()

TvEpisodeEntity

Cet exemple montre comment créer un TvEpisodeEntity avec tous les champs requis :

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build()

La chaîne du numéro d'épisode (par exemple, "2") et la chaîne du numéro de saison (par exemple, "1") seront développées dans le format approprié avant d'être affichées sur la fiche "Reprendre la lecture". Notez qu'il doit s'agir d'une chaîne numérique. N'indiquez pas "e2", "épisode 2", "s1" ou "saison 1".

Si une série TV spécifique ne comporte qu'une seule saison, définissez le numéro de saison sur 1.

Pour maximiser les chances que les spectateurs trouvent vos contenus sur Google TV, pensez à fournir des données supplémentaires telles que les genres, les classifications de contenu et les périodes de disponibilité. Ces informations peuvent améliorer l'affichage et les options de filtrage.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title")
    .build()

VideoClipEntity

Voici un exemple de création d'un VideoClipEntity avec tous les champs obligatoires.

VideoClipEntity représente un extrait généré par un utilisateur, comme une vidéo YouTube.

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build()

Vous pouvez éventuellement définir le créateur, l'image du créateur, l'heure de création en millisecondes ou la plage de disponibilité .

LiveStreamingVideoEntity

Voici un exemple de création d'un LiveStreamingVideoEntity avec tous les champs obligatoires.

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build()

Vous pouvez éventuellement définir l'heure de début, le diffuseur, l'icône du diffuseur ou la période de disponibilité de l'entité de diffusion en direct.

Pour obtenir des informations détaillées sur les attributs et les exigences, consultez la documentation de référence de l'API.

Fournir des données sur le cluster "Continuation"

AppEngagePublishClient permet de publier le cluster "Continuation". Vous utilisez la méthode publishContinuationCluster() pour publier un objet ContinuationCluster.

Tout d'abord, vous devez utiliser isServiceAvailable() pour vérifier si le service est disponible pour l'intégration.

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

Lorsque le service reçoit la requête, les actions suivantes ont lieu dans une seule transaction :

• Les données ContinuationCluster existantes du développeur partenaire sont supprimées.
• Les données de la requête sont analysées et stockées dans le ContinuationCluster mis à jour.

En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

Les API de publication sont des API upsert. Elles remplacent le contenu existant. Si vous devez mettre à jour une entité spécifique dans ContinuationCluster, vous devrez publier à nouveau toutes les entités.

Les données ContinuationCluster ne doivent être fournies que pour les comptes adultes. Publiez uniquement lorsque le profil de compte appartient à un adulte.

Synchronisation multi-appareil

L'indicateur SyncAcrossDevices contrôle si les données ContinuationCluster d'un utilisateur sont synchronisées sur différents appareils tels que les téléviseurs, les téléphones, les tablettes, etc. La synchronisation multi-appareils est désactivée par défaut.

Valeurs :

• true : les données ContinuationCluster sont partagées sur tous les appareils de l'utilisateur pour une expérience de visionnage fluide. Nous vous recommandons vivement cette option pour profiter d'une expérience optimale sur tous les appareils.
• false : les données ContinuationCluster sont limitées à l'appareil actuel.

Obtenir le consentement :

L'application multimédia doit fournir un paramètre clair permettant d'activer ou de désactiver la synchronisation multi-appareils. Explique les avantages pour l'utilisateur, puis enregistre sa préférence une seule fois et applique-la dans publishContinuationCluster en conséquence.

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

Pour profiter pleinement de notre fonctionnalité multi-appareils, vérifiez que l'application obtient le consentement de l'utilisateur et activez SyncAcrossDevices sur true. Cela permet de synchroniser facilement le contenu sur les appareils, ce qui améliore l'expérience utilisateur et augmente l'engagement. Par exemple, un partenaire qui a implémenté cette fonctionnalité a enregistré une augmentation de 40 % des clics sur "Reprendre la lecture", car son contenu était diffusé sur plusieurs appareils.

Supprimer les données de découverte vidéo

Pour supprimer manuellement les données d'un utilisateur du serveur Google TV avant la période de conservation standard de 60 jours, utilisez la méthode client.deleteClusters(). Lorsque le service reçoit la demande, il supprime toutes les données existantes sur la découverte de vidéos pour le profil du compte ou pour l'ensemble du compte.

L'énumération DeleteReason définit la raison de la suppression des données. Le code suivant supprime les données "Reprendre la lecture" lors de la déconnexion.

// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
    DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

Tests

Utilisez l'application de validation pour vérifier que l'intégration du SDK Engage fonctionne correctement. L'application de validation fournit des outils pour vous aider à valider vos données et à confirmer que les intents de diffusion sont gérés correctement.

Après avoir appelé l'API de publication, vérifiez que vos données sont correctement publiées en consultant l'application de validation. Votre cluster de continuation doit s'afficher sur une ligne distincte dans l'interface de l'application.

• Définissez Engage Service Flag uniquement pour les builds hors production dans le fichier manifeste Android de votre application.
• Installez et ouvrez l'application Engage Verify.
• Si isServiceAvailable est défini sur false, cliquez sur le bouton "Activer/Désactiver" pour l'activer.
• Saisissez le nom du package de votre application pour afficher automatiquement les données publiées une fois que vous commencez à les publier.
• Testez ces actions dans votre application :
  • Connectez-vous.
  • Passez d'un profil à un autre(le cas échéant).
  • Démarrer, puis mettre en pause une vidéo, ou revenir à la page d'accueil
  • Fermez l'application pendant la lecture d'une vidéo.
  • Supprime un élément de la ligne "Reprendre la lecture" (si cette option est disponible).
• Après chaque action, vérifiez que votre application a appelé l'API publishContinuationClusters et que les données s'affichent correctement dans l'application de validation.

• L'application de validation affichera une coche verte "Tout va bien" pour les entités correctement implémentées.

  

• L'application de validation signalera les entités problématiques.

  

• Pour résoudre les problèmes liés aux entités comportant des erreurs, utilisez la télécommande de votre téléviseur pour sélectionner l'entité dans l'application de validation, puis cliquez dessus. Les problèmes spécifiques s'affichent et sont mis en évidence en rouge pour que vous puissiez les examiner (voir l'exemple ci-dessous).

  

API REST

Le SDK Engage propose une API REST pour offrir une expérience de visionnage cohérente sur les plates-formes autres qu'Android, comme iOS et Roku TV. L'API permet aux développeurs de mettre à jour l'état "Reprendre la lecture" pour les utilisateurs inscrits sur des plates-formes autres qu'Android.

Prérequis

• Vous devez d'abord terminer l'intégration basée sur le SDK Engage sur l'appareil. Cette étape essentielle établit l'association nécessaire entre l'ID utilisateur Google et le AccountProfile de votre application.
• Accès à l'API et authentification : pour afficher et activer l'API dans votre projet Google Cloud, vous devez suivre une procédure d'autorisation. Toutes les requêtes API nécessitent une authentification.

Obtenir l'accès

Pour pouvoir afficher et activer l'API dans la console Google Cloud, vous devez enregistrer votre compte.

1. 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 tous les comptes Google que vous souhaitez utiliser pour appeler l'API.
2. Configurez un compte avec la console Google Cloud à l'aide d'une adresse e-mail associée à Google Workspace.
3. Créer un projet
4. Créez un compte de service pour l'authentification de l'API. Une fois le compte de service créé, vous disposerez de deux éléments :
   • ID d'un compte de service.
   • Un fichier JSON contenant la clé de votre compte de service. Gardez ce fichier bien en sécurité, car vous en aurez besoin pour authentifier votre client auprès de l'API ultérieurement.
5. Les espaces de travail et les comptes Google associés peuvent désormais utiliser les API REST. Une fois la modification propagée, vous serez informé si l'API est prête à être appelée par vos comptes de service.
6. Suivez ces étapes pour préparer un appel d'API délégué.

Publier un cluster "Continuation"

Pour publier les données de découverte de vidéos, 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 contenu multimédia
• accountId : ID unique du compte de l'utilisateur dans votre système. Il doit correspondre à la accountId utilisée 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 à l'ID de profil utilisé dans le chemin d'accès sur l'appareil.

L'URL du compte sans profil est la suivante :

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 peuvent être MovieEntity ou TVEpisodeEntity. Ce champ est obligatoire.

Corps de la requête

Le champ entities contient des movieEntity et des tvEpisodeEntity individuels.

Chaque objet du tableau d'entités doit être l'un des types MediaEntity disponibles, à savoir MovieEntity et TvEpisodeEntity, ainsi que les champs communs et spécifiques au type.

L'extrait de code suivant présente le payload 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": [
          "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"
      }
    }
  ]
}

Supprimer les données vidéo Discovery

Utilisez l'API clearClusters pour supprimer les données de découverte de vidéos.

Utilisez l'URL POST pour supprimer les entités des données de découverte de vidéos. Pour supprimer les données du cluster de continuation, envoyez une requête POST à l'API clearClusters en utilisant la syntaxe suivante.

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

Où :

• package_name : nom du package du fournisseur de contenu multimédia.
• accountId : ID unique du compte de l'utilisateur dans votre système. Il doit correspondre à la accountId utilisée 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 à l'ID de profil utilisé dans le chemin d'accès sur l'appareil.

La charge utile de l'API clearClusters 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 "Reprendre la lecture" 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, comme regarder une partie d'un film ou un épisode en entier. Pour en savoir plus, consultez les consignes relatives au canal "À regarder ensuite" pour les développeurs d'applis.