Adicionar notificações do desenvolvedor em tempo real

Visão geral

O Google Play Faturamento fornece notificações push do servidor que permitem monitorar as alterações de estado das assinaturas gerenciadas pelo Play. Ao ativar as notificações do desenvolvedor em tempo real, você receberá um token de compra diretamente no Cloud Pub/Sub sempre que houver uma atualização para uma assinatura 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 estiver familiarizado com 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 Crie 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 de push ou 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 de Permissões do tópico.
  4. Adicione a conta de serviço google-play-developer-notifications@system.gserviceaccount.com e conceda a ela o papel de editor do Pub/Sub.
    Figura 2. Adição de uma conta de serviço do Google Play como editor 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 de 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 para enviar uma 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 editor 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 do desenvolvedor em tempo real não oferece um SLA de latência oficial. No entanto, a maioria das notificações costuma 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 de JSON

Cada publicação feita em um tópico do Pub/Sub contém um único DeveloperNotification codificado em base64 com os seguintes campos:

{
  "version": string,
  "packageName": string
  "eventTimeMillis": long
  "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.
subscriptionNotification SubscriptionNotification Se este campo estiver presente, a notificação estará relacionada a uma assinatura. Ele contém mais informações sobre a assinatura. Este campo é mutuamente exclusivo com testNotification.
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. Este campo é mutuamente exclusivo com subscriptionNotification.

Uma 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 código da assinatura comprada (por exemplo, "monthly001").

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

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