Compartilhar direitos de acesso do app com o Google TV usando o SDK Engage

Este guia contém instruções para desenvolvedores compartilharem dados de assinatura e direitos do app com o Google TV usando o SDK Engage. Os usuários podem encontrar o conteúdo a que têm direito e permitir que o Google TV ofereça recomendações de conteúdo altamente relevantes diretamente nas experiências do Google TV em TVs, dispositivos móveis e tablets.

Pré-requisitos

É necessário integrar o feed de ações de mídia antes de usar a API de direitos do dispositivo. Se ainda não tiver feito isso, conclua o processo de integração do feed de ações de mídia .

Pré-trabalho

Conclua as instruções de pré-trabalho no guia para iniciantes.

1. Publique informações de assinatura nos seguintes eventos:
   1. O usuário faz login no seu app.
   2. O usuário alterna entre perfis (se os perfis forem compatíveis).
   3. O usuário compra uma nova assinatura.
   4. O usuário faz upgrade de uma assinatura.
   5. A assinatura do usuário expira.

Integração

Esta seção fornece os exemplos de código e as instruções necessárias para implementar SubscriptionEntity e gerenciar vários tipos de assinatura.

Assinatura de nível comum

Para usuários com assinaturas básicas de serviços de provedores de mídia, por exemplo, um serviço que tem um nível de assinatura que concede acesso a todo o conteúdo pago, forneça estes detalhes essenciais:

1. SubscriptionType: indica claramente o plano de assinatura específico que o usuário tem.

   • SUBSCRIPTION_TYPE_ACTIVE: o usuário tem uma assinatura paga ativa.
   • SUBSCRIPTION_TYPE_ACTIVE_TRIAL: o usuário tem uma assinatura de teste.
   • SUBSCRIPTION_TYPE_INACTIVE: o usuário tem uma conta, mas não tem uma assinatura ou teste ativo.

2. ExpirationTimeMillis: tempo opcional em milissegundos. Especifique quando a assinatura vai expirar.

3. ProviderPackageName: especifique o nome do pacote do app que processa a assinatura.

Exemplo do feed de provedor de mídia de amostra.

"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
  }

O exemplo a seguir cria uma SubscriptionEntity para um usuário:

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()

Assinatura Premium

Se o app oferecer pacotes de assinatura Premium de vários níveis, que incluem conteúdo ou recursos expandidos além do nível comum, represente isso adicionando um ou mais direitos à assinatura.

Esse direito tem os seguintes campos:

1. Identifier: string de identificador obrigatória para esse direito. Ela precisa corresponder a um dos identificadores de direitos (observe que esse não é o campo de ID) fornecidos no feed do provedor de mídia publicado no Google TV.
2. Name: são informações auxiliares e usadas para correspondência de direitos. Embora seja opcional, fornecer um nome de direito legível para humanos melhora a compreensão dos direitos do usuário para desenvolvedores e equipes de suporte. Por exemplo: Sling Orange.
3. ExpirationTimeMillis: especifique opcionalmente o tempo de expiração em milissegundos para esse direito, se ele for diferente do tempo de expiração da assinatura. Por padrão, o direito vai expirar com a assinatura.

Para o snippet de feed de provedor de mídia de amostra a seguir:

"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"
  }

O exemplo a seguir cria uma SubscriptionEntity para um usuário inscrito:

// 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()

Assinatura do pacote de serviços vinculados

Embora as assinaturas normalmente pertençam ao provedor de mídia do app de origem, uma assinatura pode ser atribuída a um pacote de serviços vinculados especificando o nome do pacote de serviços vinculados na assinatura.

O exemplo de código a seguir demonstra como criar uma assinatura de usuário.

// 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()

Além disso, se o usuário tiver outra assinatura de um serviço subsidiário, adicione outra assinatura e defina o nome do pacote de serviços vinculados de acordo.

// 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()

Opcionalmente, adicione direitos a uma assinatura de serviço vinculado também.

Fornecer conjunto de assinaturas

Execute o job de publicação de conteúdo enquanto o app estiver em primeiro plano.

Use o método publishSubscriptionCluster() da classe AppEngagePublishClient para publicar um objeto SubscriptionCluster.

Inicialize o cliente e verifique a disponibilidade do serviço conforme descrito no guia para iniciantes.

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

Use setSubscription() para verificar se o usuário tem apenas uma assinatura do serviço.

Use addLinkedSubscription() ou addLinkedSubscriptions(), que aceitam uma lista de assinaturas vinculadas, para permitir que o usuário tenha zero ou mais assinaturas vinculadas.

Quando o serviço recebe a solicitação, uma nova entrada é criada e a antiga é excluída automaticamente após 60 dias. O sistema sempre usa a entrada mais recente. Em caso de erro, a solicitação inteira é rejeitada e o estado existente é mantido.

Manter a assinatura atualizada

1. Para fornecer atualizações imediatas após as mudanças, chame publishSubscriptionCluster sempre que o estado de assinatura de um usuário mudar, como ativação, desativação, upgrades e downgrades.

2. Para fornecer validação regular para precisão contínua, chame publishSubscriptionCluster pelo menos uma vez por mês.

3. Para excluir os dados do Engage, exclua manualmente os dados de um usuário do servidor do Google TV antes do período de armazenamento padrão de 60 dias. Use o método client.deleteClusters. Isso exclui todos os dados do Engage existentes para o perfil da conta ou para toda a conta, dependendo do DeleteReason fornecido.

   O snippet de código a seguir mostra como remover uma assinatura de usuário:

   // 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()
     )
   

   O snippet de código a seguir demonstra a remoção da assinatura do usuário quando ele revoga o consentimento:

   // 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()
   )
   

   O código a seguir demonstra como remover dados de assinatura na exclusão do perfil do usuário.

   // 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()
   )
   

Teste

Esta seção fornece um guia detalhado para testar a implementação da assinatura. Verifique a precisão dos dados e a funcionalidade adequada antes do lançamento.

Lista de verificação de integração de publicação

1. A publicação precisa acontecer quando o app está em primeiro plano e o usuário está interagindo ativamente com ele.

2. Publique quando:

   • O usuário faz login pela primeira vez.
   • O usuário muda de perfil (se os perfis forem compatíveis).
   • O usuário compra uma nova assinatura.
   • O usuário faz upgrade da assinatura.
   • A assinatura do usuário expira.

3. Verifique se o app está chamando corretamente as APIs isServiceAvailable() e publishClusters() no logcat, nos eventos de publicação.

4. Verifique se os dados estão visíveis no app de verificação. O app de verificação mostra a assinatura como uma linha separada. Quando a API de publicação é invocada, os dados aparecem no app de verificação.

5. Acesse o app e execute cada uma das seguintes ações:

   • Faça login.
   • Alterne entre perfis (se compatível).
   • Compre uma nova assinatura.
   • Faça upgrade de uma assinatura.
   • Expire a assinatura.

Verificar integração

Para testar a integração, use o app de verificação.

1. Para cada um dos eventos, verifique se o app invocou a API publishSubscription. Verifique os dados publicados no app de verificação. Verifique se tudo está verde no app de verificação.

2. Se todas as informações da entidade estiverem corretas, ela vai mostrar uma marca de seleção verde "Tudo certo" em todas as entidades.

   

3. Os problemas também são destacados no app de verificação.

   

4. Para conferir os problemas na assinatura agrupada, use o controle remoto da TV para se concentrar nessa assinatura específica e clique para conferir os problemas. Talvez seja necessário se concentrar na linha e mover para a direita para encontrar o card de assinatura agrupada. Os problemas são destacados em vermelho, conforme mostrado na Figura 3. Além disso, use o controle remoto para rolar para baixo e conferir os problemas nos direitos da assinatura agrupada.

   

5. Para conferir os problemas no direito, use o controle remoto da TV para se concentrar nesse direito específico e clique para conferir os problemas. Os problemas são destacados em vermelho.