Ce guide explique aux développeurs comment partager des données d'abonnement et d' accès à des applications avec Google TV à l'aide du SDK Engage. Les utilisateurs peuvent trouver le contenu auquel ils ont droit et permettre à Google TV de leur fournir des recommandations de contenu très pertinentes, directement dans les expériences Google TV sur les téléviseurs, les mobiles et les tablettes.
Prérequis
Vous devez intégrer le flux d'actions multimédias avant de pouvoir utiliser l'API de droits d'accès 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 "Travail préalable" du guide de démarrage.
- Publiez les informations d'abonnement lors des événements suivants :
- L'utilisateur se connecte à votre application.
- L'utilisateur passe d'un profil à un autre (si les profils sont compatibles).
- L'utilisateur souscrit un nouvel abonnement.
- L'utilisateur met à niveau un abonnement existant.
- 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 commun
Pour les utilisateurs disposant d'abonnements de base aux services de fournisseurs de contenus multimédias (par exemple, un service qui propose un niveau d'abonnement donnant accès à tous les contenus payants), fournissez les informations essentielles suivantes :
SubscriptionType: indiquez clairement le forfait d'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.
ExpirationTimeMillis: durée facultative en millisecondes. Indiquez la date d'expiration de l'abonnement.ProviderPackageName: spécifiez le nom de package de l'application qui gère l'abonnement.
Exemple pour l'exemple de flux de fournisseur de contenus multimédias.
"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 des contenus ou des fonctionnalités supplémentaires par rapport au 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. Elle 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 contenus multimédias 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: spécifiez éventuellement la date d'expiration en millisecondes pour ce droit d'accès, si elle est différente de la date d'expiration de l'abonnement. Par défaut, le droit d'accès expirera en même temps que l'abonnement.
Pour l'extrait de flux de fournisseur de contenus multimédias 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 à un forfait de services associés
Bien que les abonnements appartiennent généralement au fournisseur de contenus multimédias de l'application d'origine, un abonnement peut être attribué à un forfait de services associés en spécifiant le nom du forfait de services associés 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 forfait de services associés 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 la tâche 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 avoir qu'un seul abonnement au service.
Utilisez addLinkedSubscription() ou addLinkedSubscriptions(), qui acceptent une liste d'abonnements associés, pour permettre à l'utilisateur de disposer d'aucun ou de plusieurs abonnements associés.
Lorsque le service reçoit la requête, 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
publishSubscriptionClusterchaque fois que l'état d'abonnement d'un utilisateur change (activation, désactivation, mise à niveau, rétrogradation, etc.).Pour assurer une validation régulière et une précision continue, appelez
publishSubscriptionClusterau moins une fois par mois.Pour supprimer les données Engage, 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. Cela supprime toutes les données Engage existantes pour le profil de compte ou pour l’ensemble du compte, selon leDeleteReasondonné.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 Engage 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 la suppression de l'abonnement utilisateur lorsque l'utilisateur révoque son consentement :
// If the user revokes the consent to share across device, make the call // to remove subscription and other Engage 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 Engage data. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile(accountProfile) .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION) .build() )
Tests
Cette section fournit un guide pas à pas pour tester l'implémentation de l'abonnement. 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.
Publiez lorsque :
- L'utilisateur se connecte pour la première fois.
- L'utilisateur change de profil (si les profils sont compatibles).
- 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()etpublishClusters()dans logcat, lors des é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.
Accédez à l'application et effectuez chacune des actions suivantes :
- Connectez-vous.
- Passez d'un profil à un autre (si cette fonctionnalité est compatible).
- Souscrivez un nouvel abonnement.
- Mettez à 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 dans toutes les entités.
Figure 1. Abonnement réussi Les problèmes sont également mis en évidence dans l'application de validation.
Figure 2.Abonnement non réussi Pour afficher les problèmes liés à l'abonnement groupé, utilisez la télécommande du téléviseur pour vous concentrer sur cet abonnement groupé spécifique et cliquez pour afficher les problèmes. Vous devrez peut-être d'abord vous concentrer sur la ligne et vous déplacer vers la droite pour trouver la carte "Abonnement groupé". Les problèmes sont mis en évidence en rouge, comme illustré à la figure 3. Utilisez également la télécommande pour descendre 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 au droit d'accès, utilisez la télécommande du téléviseur pour vous concentrer sur ce droit d'accès spécifique et cliquez pour afficher les problèmes. Les problèmes sont mis en évidence en rouge.
Figure 4.Détails de l'erreur d'abonnement