Partager les droits d'accès des applications avec Google TV à l'aide du SDK Engage

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

Ce guide explique aux développeurs comment partager les données d'abonnement et de droits d'accès à l'application avec Google TV à l'aide du SDK Engage. Les utilisateurs peuvent trouver les contenus auxquels ils ont accès et permettre à Google TV de leur proposer des recommandations de contenus très pertinentes, directement dans les expériences Google TV sur téléviseur, mobile et tablette.

Prérequis

Vous devez intégrer le flux d'actions multimédias avant de pouvoir utiliser l'API d'attribution de droits aux appareils. Si vous ne l'avez pas encore fait, suivez la procédure d'intégration du flux d'actions multimédias.

Travail préalable

Suivez les instructions de la section Travaux préparatoires du guide de démarrage.

Publiez des informations sur l'abonnement pour les événements suivants :
1. L'utilisateur se connecte à votre application.
2. L'utilisateur passe d'un profil à un autre (si les profils sont compatibles).
3. L'utilisateur souscrit un nouvel abonnement.
4. L'utilisateur met à niveau un abonnement existant.
5. L'abonnement de l'utilisateur expire.

Intégration

Cette section fournit les exemples de code et les instructions nécessaires pour implémenter SubscriptionEntity afin de gérer différents types d'abonnements.

Abonnement de niveau intermédiaire

Pour les utilisateurs disposant d'abonnements de base à des services de fournisseurs de contenus multimédias (par exemple, un service qui propose un seul niveau d'abonnement donnant accès à tous les contenus payants), fournissez les informations essentielles suivantes :

SubscriptionType : indiquez clairement l'abonnement spécifique dont dispose l'utilisateur.
- SUBSCRIPTION_TYPE_ACTIVE : l'utilisateur dispose d'un abonnement payant actif.
- SUBSCRIPTION_TYPE_ACTIVE_TRIAL : l'utilisateur dispose d'un abonnement d'essai.
- SUBSCRIPTION_TYPE_INACTIVE : l'utilisateur dispose d'un compte, mais n'a pas d'abonnement ni d'essai actifs.
Important : Seuls les utilisateurs disposant d'un abonnement SUBSCRIPTION_TYPE_ACTIVE ou SUBSCRIPTION_TYPE_ACTIVE_TRIAL peuvent bénéficier de recommandations de contenu personnalisées en fonction de leur abonnement.
ExpirationTimeMillis : durée facultative en millisecondes. Indiquez la date d'expiration de l'abonnement.
ProviderPackageName : spécifiez le nom du package de l'application qui gère l'abonnement.

Exemple de flux du fournisseur de contenu multimédia.

"actionAccessibilityRequirement": [
  {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2022-06-01T07:00:00Z",
    "availabilityEnds": "2026-05-31T07:00:00Z",
    "requiresSubscription": {
    "@type": "MediaSubscription",
    // Don't match this string,
    // ID is only used to for reconciliation purpose
    "@id": "https://www.example.com/971bfc78-d13a-4419",
    // Don't match this, as name is only used for displaying purpose
    "name": "Basic common name",
    "commonTier": true
  }

L'exemple suivant crée un SubscriptionEntity pour un utilisateur :

val subscription = SubscriptionEntity.Builder()
  setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .build()

Abonnement premium

Si l'application propose des forfaits d'abonnement premium à plusieurs niveaux, qui incluent du contenu ou des fonctionnalités étendus au-delà du niveau commun, représentez-les en ajoutant un ou plusieurs droits d'accès à l'abonnement.

Ce droit d'accès comporte les champs suivants :

Identifier : chaîne d'identifiant obligatoire pour ce droit d'accès. Il doit correspondre à l'un des identifiants de droits d'accès (notez qu'il ne s'agit pas du champ "ID") fournis dans le flux du fournisseur de contenu multimédia publié sur Google TV.
Name : il s'agit d'informations auxiliaires utilisées pour la mise en correspondance des droits d'accès. Bien que facultatif, le fait de fournir un nom de droit d'accès lisible par un humain permet aux développeurs et aux équipes d'assistance de mieux comprendre les droits d'accès des utilisateurs. Exemple : Sling Orange.
ExpirationTimeMillis : vous pouvez éventuellement spécifier la durée de validité de ce droit d'accès en millisecondes, si elle est différente de celle de l'abonnement. Par défaut, le droit d'accès expirera en même temps que l'abonnement.

Pour l'extrait d'exemple de flux de fournisseur de contenu multimédia suivant :

"actionAccessibilityRequirement": [
  {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2022-06-01T07:00:00Z",
    "availabilityEnds": "2026-05-31T07:00:00Z",
    "requiresSubscription": {
    "@type": "MediaSubscription",
    // Don't match this string,
    // ID is only used to for reconciliation purpose
    "@id": "https://www.example.com/971bfc78-d13a-4419",

    // Don't match this, as name is only used for displaying purpose
    "name": "Example entitlement name",
    "commonTier": false,
    // match this identifier in your API. This is the crucial
    // entitlement identifier used for recommendation purpose.
    "identifier": "example.com:entitlementString1"
  }

L'exemple suivant crée un SubscriptionEntity pour un utilisateur abonné :

// Subscription with entitlements.
// The entitlement expires at the same time as its subscription.
val subscription = SubscriptionEntity.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds
  .setExpirationTimeMillis(1767052800000)
  .addEntitlement(
    SubscriptionEntitlement.Builder()
    // matches with the identifier in media provider feed
    .setEntitlementId("example.com:entitlementString1")
    .setDisplayName("entitlement name1")
    .build()
  )
  .build()

// Subscription with entitlements
// The entitement has different expiration time from its subscription
val subscription = SubscriptionEntity.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds
  .setExpirationTimeMillis(1767052800000)
  .addEntitlement(
    SubscriptionEntitlement.Builder()
    .setEntitlementId("example.com:entitlementString1")
    .setDisplayName("entitlement name1")
    // You may set the expiration time for entitlement
    // December 15, 2025 10:00:00 AM in milliseconds
    .setExpirationTimeMillis(1765792800000)
    .build())
  .build()

Abonnement au forfait de services associés

Bien que les abonnements appartiennent généralement au fournisseur de contenu multimédia de l'application d'origine, un abonnement peut être attribué à un forfait de service associé en spécifiant le nom du forfait de service associé dans l'abonnement.

L'exemple de code suivant montre comment créer un abonnement utilisateur.

// Subscription for linked service package
val subscription = SubscriptionEntity.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("com.google.android.example")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .build()

De plus, si l'utilisateur dispose d'un autre abonnement à un service filiale, ajoutez un autre abonnement et définissez le nom du package de service associé en conséquence.

// Subscription for linked service package
val linkedSubscription = Subscription.Builder()
  .setSubscriptionType(
    SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
  )
  .setProviderPackageName("linked service package name")
  // Optional
  // December 30, 2025 12:00:00AM in milliseconds since epoch
  .setExpirationTimeMillis(1767052800000)
  .addBundledSubscription(
    BundledSubscription.Builder()
      .setBundledSubscriptionProviderPackageName(
        "bundled-subscription-package-name"
      )
      .setSubscriptionType(SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE)
      .setExpirationTimeMillis(111)
      .addEntitlement(
        SubscriptionEntitlement.Builder()
        .setExpirationTimeMillis(111)
        .setDisplayName("Silver subscription")
        .setEntitlementId("subscription.tier.platinum")
        .build()
      )
      .build()
  )
    .build()

Vous pouvez également ajouter des droits d'accès à un abonnement à un service associé.

Fournir un ensemble d'abonnements

Exécutez le job de publication de contenu lorsque l'application est au premier plan.

Utilisez la méthode publishSubscriptionCluster() de la classe AppEngagePublishClient pour publier un objet SubscriptionCluster.

Veillez à initialiser le client et à vérifier la disponibilité du service, comme décrit dans le guide de démarrage.

client.publishSubscription(
  PublishSubscriptionRequest.Builder()
    .setAccountProfile(accountProfile)
    .setSubscription(subscription)
    .build()
  )

Utilisez setSubscription() pour vérifier que l'utilisateur ne doit disposer que d'un seul abonnement au service.

Utilisez addLinkedSubscription() ou addLinkedSubscriptions(), qui acceptent une liste d'abonnements associés, pour permettre à l'utilisateur d'avoir zéro ou plusieurs abonnements associés.

Lorsque le service reçoit la demande, une nouvelle entrée est créée et l'ancienne est automatiquement supprimée au bout de 60 jours. Le système utilise toujours la dernière entrée. En cas d'erreur, la requête entière est rejetée, et l'état existant est maintenu.

Maintenir l'abonnement à jour

Pour fournir des mises à jour immédiates en cas de modification, appelez publishSubscriptionCluster chaque fois que l'état de l'abonnement d'un utilisateur change (activation, désactivation, mise à niveau, rétrogradation, etc.).
Pour valider régulièrement la précision continue, appelez publishSubscriptionCluster au moins une fois par mois.

Remarque : Google TV supprimant automatiquement les données historiques au-delà de 60 jours pour protéger la confidentialité des utilisateurs, la publication des données d'abonnement des utilisateurs au moins une fois par mois permet de vérifier la validité des données. Contrairement à publishContinuationCluster pour les données "Reprendre la lecture", ne définissez pas l'indicateur syncAcrossDevices, car les informations sur l'abonnement sont utilisées par défaut pour fournir du contenu sur tous les appareils.

Pour supprimer les données de découverte de vidéos, supprimez manuellement les données d'un utilisateur du serveur Google TV avant la période de conservation standard de 60 jours à l'aide de la méthode client.deleteClusters. Toutes les données existantes sur la découverte de vidéos pour le profil du compte ou pour l'ensemble du compte sont supprimées, en fonction de la valeur DeleteReason fournie.

L'extrait de code suivant montre comment supprimer un abonnement utilisateur :

// If the user logs out from your media app, you must make the following call
// to remove subscription and other video discovery data from the current
// google TV device.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
    .setAccountProfile(accountProfile)
  .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
  .build()
  )

L'extrait de code suivant montre comment supprimer l'abonnement d'un utilisateur lorsque celui-ci révoque son consentement :

// If the user revokes the consent to share across device, make the call
// to remove subscription and other video discovery data from all google
// TV devices.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
    .setAccountProfile(accountProfile)
    .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
    .build()
)

Le code suivant montre comment supprimer les données d'abonnement lors de la suppression du profil utilisateur.

// If the user delete a specific profile, you must make the following call
// to remove subscription data and other video discovery data.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
  .setAccountProfile(accountProfile)
  .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION)
  .build()
)

Tests

Cette section fournit un guide détaillé pour tester l'implémentation des abonnements. Vérifiez l'exactitude des données et le bon fonctionnement avant le lancement.

Checklist de publication de l'intégration

La publication doit avoir lieu lorsque l'application est au premier plan et que l'utilisateur interagit activement avec elle.
Publier quand :
- L'utilisateur se connecte pour la première fois.
- L'utilisateur modifie son profil (si les profils sont acceptés).
- L'utilisateur souscrit un nouvel abonnement.
- L'utilisateur met à niveau son abonnement.
- L'abonnement de l'utilisateur expire.
Vérifiez si l'application appelle correctement les API isServiceAvailable() et publishClusters() dans logcat, sur les événements de publication.
Vérifiez que les données sont visibles dans l'application de validation. L'application de validation doit afficher l'abonnement sur une ligne distincte. Lorsque l'API de publication est appelée, les données doivent s'afficher dans l'application de validation.

Important : Vérifiez que le indicateur de service Engage n'est pas défini sur "Production".
Accédez à l'application et effectuez chacune des actions suivantes :
- Connectez-vous.
- Passez d'un profil à un autre (si cette option est disponible).
- Souscrivez un nouvel abonnement.
- Mettre à niveau un abonnement existant.
- Faites expirer l'abonnement.

Vérifier l'intégration

Pour tester votre intégration, utilisez l'application de validation.

Pour chacun des événements, vérifiez si l'application a appelé l'API publishSubscription. Vérifiez les données publiées dans l'application de validation. Vérifiez que tout est vert dans l'application de validation.
Si toutes les informations de l'entité sont correctes, une coche verte "Tout va bien" s'affiche pour toutes les entités.

Figure 1. Abonnement souscrit
Les problèmes sont également mis en évidence dans l'application de validation.

Figure 2 : abonnement non souscrit
Pour afficher les problèmes liés à l'abonnement groupé, utilisez la télécommande du téléviseur pour sélectionner cet abonnement, puis cliquez pour afficher les problèmes. Vous devrez peut-être d'abord sélectionner la ligne, puis vous déplacer vers la droite pour trouver la carte "Abonnement groupé". Les problèmes sont mis en évidence en rouge, comme illustré sur la figure 3. Utilisez également la télécommande pour faire défiler l'écran vers le bas et afficher les problèmes liés aux droits d'accès dans l'abonnement groupé.

Figure 3 : erreurs d'abonnement
Pour afficher les problèmes liés à un droit d'accès, utilisez la télécommande du téléviseur pour le sélectionner, puis cliquez dessus pour afficher les problèmes. Les problèmes sont mis en évidence en rouge.

Figure 4.Détails sur les erreurs d'abonnement