O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Adicionar notificações do desenvolvedor em tempo real

Visão geral

O Google Play Faturamento oferece notificações push do servidor que permitem monitorar mudanças de estado para assinaturas gerenciadas pelo Google Play e compras únicas com transações pendentes. Ao ativar as notificações de desenvolvedor em tempo real, você receberá um token de compra diretamente do Cloud Pub/Sub sempre que houver uma atualização em uma transação pendente ou em uma assinatura já existente.

As notificações do desenvolvedor em tempo real não fornecem informações completas sobre o estado da assinatura, por exemplo, se o usuário tem permissão para acessar o conteúdo da assinatura. Ao receber o token, você precisa sempre usá-lo para consultar a API Google Play Developer para ver todas as informações e atualizar seu back-end com o estado atual de titularidade do usuário.

Os tipos de notificação podem mudar no futuro. Você precisa conseguir lidar com tipos de notificação não reconhecidos e pode contar com a API Google Play Developer para consultar a lógica de negócios fundamental.

Para ativar esse recurso:

  1. Configure o Cloud Pub/Sub usando seu próprio projeto do Google Cloud Platform (GCP).
  2. Ative as notificações de desenvolvedor em tempo real para seu app Android.

Configurar o Cloud Pub/Sub

O Cloud Pub/Sub é um serviço de mensagens em tempo real totalmente gerenciado que permite o envio e o recebimento de mensagens entre apps independentes. Ele oferece troca de mensagens durável e de baixa latência que ajuda você a integrar rapidamente os sistemas hospedados no Google Cloud Platform e externamente.

O Google Play Faturamento usa o Cloud Pub/Sub para publicar notificações push sobre tópicos que você assina.

Estabelecer pré-requisitos

Para usar o Cloud Pub/Sub, é preciso ter um projeto no Google Cloud Platform (GCP) com a API Cloud Pub/Sub ativada. Se você não conhece o GCP e o Cloud Pub/Sub, leia o Guia de início rápido.

Para receber as notificações push, é necessário criar um servidor de back-end seguro para consumir as mensagens enviadas para seu tópico. Seu servidor pode usar as Bibliotecas de cliente do Cloud Pub/Sub (link em inglês) para consumir as mensagens.

Criar um tópico

Para começar a receber as notificações, é necessário criar um tópico em que o Google Play Faturamento possa publicá-las. Para criar um tópico:

  1. Leia as instruções em Criar um tópico.
  2. Use o Console do Google Cloud Platform para criar o tópico.

Criar uma assinatura no Pub/Sub

Para receber mensagens publicadas em um tópico, você precisa criar uma assinatura do Pub/Sub para esse tópico. Para criar uma assinatura do Pub/Sub:

  1. Leia o Guia do assinante do Cloud Pub/Sub para determinar se é preciso configurar a assinatura como uma assinatura de push ou assinatura de pull. Uma assinatura de envio por pull requer que seu servidor de back-end seguro inicie solicitações ao servidor do Cloud Pub/Sub para recuperar mensagens. Uma assinatura de envio por push requer que o Cloud Pub/Sub inicie solicitações ao seu servidor de back-end seguro para entregar mensagens.
  2. Leia as instruções em Adicione uma inscrição.
  3. Use o Console do Google Cloud Platform para criar a assinatura.

Conceder direitos de publicação no tópico

O Cloud Pub/Sub requer que você conceda privilégios ao Google Play Faturamento para publicar notificações no seu tópico da seguinte forma:

  1. Abra o Console do Google Cloud.
  2. Selecione seu projeto e clique em Pub/Sub na navegação à esquerda.
  3. Localize seu tópico e abra os detalhes das permissões.
    Figura 1. Acesso à configuração Permissões do tópico.
  4. Adicione a conta de serviço google-play-developer-notifications@system.gserviceaccount.com e conceda a ela a função de editora do Pub/Sub.
    Figura 2. Adição de uma conta de serviço do Google Play como editora do Pub/Sub.
  5. Salve para concluir a configuração do tópico.
    Figura 3. Tópico configurado.

Ativar notificações de desenvolvedor em tempo real para o app

Para ativar as notificações de desenvolvedor em tempo real para seu app:

  1. Abra o Google Play Console.
  2. Selecione seu app Android.
  3. Navegue até a página Ferramentas de desenvolvimento > Serviços e APIs.
  4. Role até a seção Notificações do desenvolvedor em tempo real na parte inferior da página.

    Figura 4. Seção de notificações do desenvolvedor em tempo real.

  5. No campo Nome do tópico, insira o nome completo do tópico do Cloud Pub/Sub que você configurou anteriormente. O nome do tópico precisa estar no formato projects/{project_id}/topics/{topic_name}, em que project_id é o identificador exclusivo do seu projeto, e topic_name é o nome do tópico criado anteriormente.

  6. Clique em Enviar mensagem de teste. O teste de publicação ajuda a garantir que tudo esteja configurado corretamente. Se a publicação de teste for bem-sucedida, uma mensagem será exibida informando isso. Se houver um assinante executando o tópico em questão, ele receberá essa mensagem de teste.

    Se a publicação falhar, um erro será exibido. Verifique se o nome do tópico está correto e se a conta de serviço google-play-developer-notifications@system.gserviceaccount.com tem acesso ao tópico como editora do Pub/Sub.

  7. Clique em Atualizar tópico.

Alterar nome do tópico

Para alterar o nome do tópico sem eliminar mensagens, realize as seguintes etapas:

  1. Crie e configure o novo tópico e assinatura.
  2. Comece a ler e processar as mensagens publicadas no novo tópico.
  3. Atualize o nome do tópico para o app no Play Console.
  4. Usando o Stackdriver ou o Play Console do Cloud, aguarde até que o tópico antigo pare de receber mensagens enquanto assegura que o novo tópico esteja recebendo mensagens.
  5. Exclua o tópico antigo depois que ele parar de receber mensagens.

Excluir um tópico

Para excluir um tópico:

  1. Remova o nome do tópico do seu app usando o Google Play Console.
  2. Quando as mensagens pararem de chegar, exclua o tópico do Pub/Sub usando o Google ou o Console do Google Cloud Platform.

Observação: a exclusão do tópico no Pub/Sub antes da remoção do nome pode resultar na perda de mensagens. Você precisa reconfigurar o tópico usando o Pub/Sub para corrigir esse problema.

Escalonar o processamento de notificações

Devido à variedade de notificações que podem ser enviadas para o tópico do Pub/Sub, pode não ser prático ter um único processamento binário de todas as notificações. Há várias opções de pesquisa ao decidir como escalonar seu processamento de notificação. Essas opções incluem:

  • usar notificações no estilo push e pull;
  • configurar várias assinaturas para um tópico;
  • republicar a mensagem de notificação para outros projetos do Pub/Sub.

Por exemplo, uma única assinatura pode ter vários processos que recebem mensagens dela. As mensagens dessa assinatura são divididas entre os leitores de forma automática. Cada um dos processos pode processar a notificação ou encaminhar a solicitação para um serviço mais especializado.

Novos tipos de notificação podem ser adicionados ao longo do tempo. Os assinantes precisam estar prontos para lidar corretamente com novas notificações, se aparecerem, geralmente confirmando o recebimento da mensagem.

Observação: se você preferir usar uma assinatura push, registre seus endpoints antes de adicionar o endpoint de push. Para ver mais informações, consulte Como registrar os endpoints

Para ver mais informações, consulte a Visão geral do assinante do Pub/Sub.

Monitorar o tráfego de notificações

Para monitorar o tráfego de notificações, use o Google Stackdriver. Esse serviço permite monitorar o tráfego em um tópico e configurar alertas para determinadas condições. Por exemplo, você pode alertar se a contagem de mensagens não confirmadas for muito alta, o que provavelmente significa que há um problema com os assinantes, ou se a contagem da publicação for muito baixa, o que pode significar que há um problema para publicar no tópico.

Determinar preços e cotas

Consulte Preços e Cotas para ver mais detalhes sobre esses itens.

Estimar o uso de dados

A parte de dados da notificação de assinatura tem aproximadamente 1 KB de dados por solicitação. Cada publicação e envio por pull requer uma solicitação separada, ou aproximadamente 2 KB de dados por notificação. O número de notificações por mês depende do seu ciclo de faturamento e do comportamento dos seus usuários. Espere pelo menos uma notificação por usuário durante um ciclo de faturamento.

SLA

O serviço de notificações para desenvolvedores em tempo real não oferece um SLA de latência oficial. No entanto, a maioria das notificações será publicada alguns segundos após a ocorrência do evento. Você precisa monitorar as métricas de uso na sua página do Stackdriver, como o número de mensagens não confirmadas, para garantir que está processando todas as mensagens de maneira rápida.

Especificação do JSON

Cada publicação feita em um tópico Pub/Sub contém um único campo de dados codificado em base64.

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "eyAidmVyc2lvbiI6IHN0cmluZywgInBhY2thZ2VOYW1lIjogc3RyaW5nLCAiZXZlbnRUaW1lTWlsbGlzIjogbG9uZywgIm9uZVRpbWVQcm9kdWN0Tm90aWZpY2F0aW9uIjogT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24sICJzdWJzY3JpcHRpb25Ob3RpZmljYXRpb24iOiBTdWJzY3JpcHRpb25Ob3RpZmljYXRpb24sICJ0ZXN0Tm90aWZpY2F0aW9uIjogVGVzdE5vdGlmaWNhdGlvbiB9",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

Depois de decodificar o campo de dados codificado em base64, o DeveloperNotification contém os seguintes campos:

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "testNotification": TestNotification
}
Nome da propriedade Valor Descrição
version string A versão da notificação. Inicialmente, será "1.0". Essa versão é diferente dos outros campos de versão.
packageName string O nome do pacote do aplicativo ao qual essa notificação se refere (por exemplo, com.alguma.coisa).
eventTimeMillis long O carimbo de data/hora de quando o evento ocorreu, em milissegundos desde o período.
oneTimeProductNotification OneTimeProductNotification Se esse campo estiver presente, a notificação estará relacionada a um produto de aquisição única. Ele contém mais informações relacionadas ao produto de aquisição única. Esse campo é mutuamente exclusivo com testNotification e subscriptionNotification.
subscriptionNotification SubscriptionNotification Se este campo estiver presente, a notificação estará relacionada a uma assinatura. Ele contém mais informações sobre a assinatura. Esse campo é mutuamente exclusivo com testNotification e oneTimeProductNotification.
testNotification TestNotification Se este campo estiver presente, a notificação estará relacionada a uma publicação de teste. As notificações são enviadas apenas pelo Play Console para desenvolvedores. Esse campo é mutuamente exclusivo com subscriptionNotification e oneTimeProductNotification.

Um OneTimeProductNotification contém os seguintes campos:

{
  "version": string
  "notificationType": int
  "purchaseToken": string
  "sku": string
}
Nome da propriedade Valor Descrição
version string A versão da notificação. Inicialmente, será "1.0". Essa versão é diferente dos outros campos de versão.
notificationType int

O tipo de notificação. Pode ter os seguintes valores:

  • (1) ONE_TIME_PRODUCT_PURCHASED: um produto de aquisição única foi comprado por um usuário.
  • (2) ONE_TIME_PRODUCT_CANCELED: uma compra pendente de um produto de aquisição única foi cancelada pelo usuário.
purchaseToken string O token fornecido ao dispositivo do usuário quando a compra foi feita.
sku string O ID do produto de aquisição única comprado (por exemplo, 'sword_001').

Observação: notificações de produtos de aquisição única são enviadas somente para transações pendentes. Consulte as Notas da versão da biblioteca Google Play Faturamento 2.0 para ver mais informações.

Um SubscriptionNotification contém os seguintes campos:

{
  "version": string
  "notificationType": int
  "purchaseToken": string
  "subscriptionId": string
}
Nome da propriedade Valor Descrição
version string A versão da notificação. Inicialmente, será "1.0". Essa versão é diferente dos outros campos de versão.
notificationType int

O tipo de notificação. Pode ter os seguintes valores:

  • (1) SUBSCRIPTION_RECOVERED: uma assinatura foi recuperada da suspensão de conta.
  • (2) SUBSCRIPTION_RENEWED: uma assinatura ativa foi renovada.
  • (3) SUBSCRIPTION_CANCELED: uma assinatura foi cancelada de forma voluntária ou involuntária. Para cancelamento voluntário, é enviada quando o usuário faz o cancelamento.
  • (4) SUBSCRIPTION_PURCHASED: uma nova assinatura foi comprada.
  • (5) SUBSCRIPTION_ON_HOLD: uma assinatura entrou na suspensão de conta (se ativada).
  • (6) SUBSCRIPTION_IN_GRACE_PERIOD: uma assinatura entrou no período de carência (se ativado).
  • (7) SUBSCRIPTION_RESTARTED: o usuário reativou a assinatura em Play > Conta > Assinaturas (requer ativação da restauração de assinatura).
  • (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED: uma alteração no preço da assinatura foi confirmada pelo usuário.
  • (9) SUBSCRIPTION_DEFERRED: o tempo de renovação de uma assinatura foi estendido.
  • (10) SUBSCRIPTION_PAUSED: uma assinatura foi pausada.
  • (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED: a programação de uma pausa na assinatura foi alterada.
  • (12) SUBSCRIPTION_REVOKED: uma assinatura foi revogada pelo usuário antes do prazo de vencimento.
  • (13) SUBSCRIPTION_EXPIRED: a assinatura expirou.
purchaseToken string O token fornecido ao dispositivo do usuário quando a assinatura foi comprada.
subscriptionId string O ID da assinatura comprada (por exemplo, "monthly001").

Observação: as notificações são enviadas apenas para eventos que exigem mudanças na titularidade do usuário. Por exemplo, a API refund não muda a titularidade do usuário, por isso, não aciona uma notificação.

Um TestNotification contém os seguintes campos:

{
  "version": string
}
Nome da propriedade Valor Descrição
version string A versão da notificação. Inicialmente, será "1.0". Essa versão é diferente dos outros campos de versão.

Exemplos

Veja um exemplo de notificação para uma compra de assinatura:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "subscriptionNotification":
  {
    "version":"1.0",
    "notificationType":4,
    "purchaseToken":"PURCHASE_TOKEN",
    "subscriptionId":"my.sku"
  }
}

Veja um exemplo de notificação de teste:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "testNotification":
  {
    "version":"1.0"
  }
}