KappS Base de conhecimento · Blog

Notificações de desenvolvedor em tempo real do Google Play em 2026

Blog Tutorial

As notificações em tempo real para desenvolvedores (RTDN) são como o Google Play avisa seu backend de que algo aconteceu com uma compra. Não existe painel de webhooks nem chave de API por app: o Play publica uma mensagem em um tópico do Cloud Pub/Sub dentro do seu próprio projeto do Google Cloud, e seu servidor a recebe por push HTTPS ou por pull. Se as operações de receita ainda dependem de jobs agendados que consultam a Developer API, a RTDN é a evolução — a documentação do Google observa que o uso ineficiente da Play Developer API "pode levar a restrições de cota da API".

Este tutorial segue a ordem em que você realmente faz o trabalho: criar o tópico, conceder direitos de publicação no Play, escolher push ou pull, ativar notificações no Play Console, depois decodificar o payload e agir sobre ele. Cada nome de campo, tipo de notificação e etapa do console abaixo vem das duas páginas oficiais do Google, citadas ao final.

O que é o RTDN, em uma linha: uma mensagem para cada mudança de estado de compra — cerca de 1 KB por notificação, aproximadamente 2 KB por publicação mais pull — e a obrigação permanente de chamar a Google Play Developer API depois, porque a notificação "não fornece informações completas sobre a compra".

Etapa 1 — Crie o tópico Pub/Sub no seu próprio projeto do GCP

O RTDN é configurado por app Android, mas a camada de mensagens é sua. Você precisa de um projeto Google Cloud com a API Cloud Pub/Sub ativada e de um tópico para o qual o Play publicará. Você pode reutilizar o projeto que já usa para a Play Developer API ou criar um separado: para vários apps, é preciso usar o mesmo projeto Google Cloud para a Play Developer API, mas cada app individual pode publicar no próprio projeto.

Dimensione antes de construir. A parte de dados de uma notificação é de aproximadamente 1 KB por solicitação, e cada publicação mais pull é uma solicitação separada — cerca de 2 KB por notificação. O volume mensal depende dos seus ciclos de cobrança e do comportamento dos usuários, mas planeje pelo menos uma notificação por usuário por ciclo de cobrança e depois confira os preços e cotas do Pub/Sub para esse número.

Etapa 2 — Dê permissão ao Google Play para publicar

Um tópico recém-criado rejeita silenciosamente as publicações do Play até você conceder acesso, e é justamente essa etapa que muita gente esquece. No Google Cloud Console: selecione o projeto, abra Pub/Sub, localize seu tópico, abra os detalhes de permissões dele e adicione a conta de serviço

google-play-developer-notifications@system.gserviceaccount.com

e conceda a ela o papel Pub/Sub Publisher. Salve para concluir a configuração do tópico. Uma particularidade empresarial: se a configuração de compartilhamento restrito ao domínio da sua organização bloquear a concessão, você precisa adicionar uma exceção para essa conta de serviço da Google Play antes que o Play possa publicar qualquer coisa.

Passo 3 — escolha push ou pull para a assinatura

Um tópico não é uma caixa de correio que você pode ler; você precisa de uma assinatura vinculada a ele. Uma assinatura push faz o Cloud Pub/Sub enviar requisições HTTPS ao seu backend seguro. Uma assinatura pull exige que seu backend inicie requisições ao Pub/Sub e recupere as mensagens. A orientação do Google para RTDN: em caso de dúvida, use push, "pois em geral é mais fácil de implementar"; o pull é comumente usado para otimizar o uso de recursos quando um grande volume de mensagens é processado.

Duas regras operacionais decorrem dessa escolha. No modelo pull, confirme cada mensagem que você puxou, ou o Pub/Sub continuará reenviando-a. No modelo push, um código de resposta bem-sucedido do seu endpoint serve como confirmação — um endpoint lento ou com falha significa entrega repetida.

Etapa 4 — ativar o RTDN no Play Console e enviar um teste

  1. Abra o Google Play Console, selecione seu app e vá em Monetizar → Configuração de monetização.
  2. Na seção Notificações em tempo real para desenvolvedores no topo dessa página, marque Ativar notificações em tempo real.
  3. No campo Nome do tópico, insira o nome completo do tópico no formato projects/{project_id}/topics/{topic_name}.
  4. Clique em Enviar mensagem de teste. Para pull, abra a assinatura no Cloud Console, clique em Ver mensagens e faça o pull; depois confirme o recebimento. Para push, verifique se a mensagem de teste chegou ao seu endpoint.
  5. Escolha o escopo das notificações. Assinaturas e todas as compras anuladas traz apenas eventos de assinatura e de compra anulada. Todas as notificações para assinaturas e produtos únicos também envia eventos de compra de produtos únicos, como ONE_TIME_PRODUCT_PURCHASED e ONE_TIME_PRODUCT_CANCELED.
  6. Clique em Salvar alterações.

Quando a publicação de teste falha, o console mostra um erro e há apenas duas causas realistas: o nome do tópico está errado, ou google-play-developer-notifications@system.gserviceaccount.com não tem a função Pub/Sub Publisher no tópico. Corrija a concessão, não o app.

O que uma mensagem realmente contém

Cada publicação no tópico tem o mesmo envelope: um mapa attributes, um campo data codificado em base64, um messageId e o caminho subscription. Decodifique data e você obtém um DeveloperNotification carregando quatro fatos — version, packageName, eventTimeMillis — mais exatamente um campo de payload. Esses campos de payload são mutuamente exclusivos: subscriptionNotification, oneTimeProductNotification, voidedPurchaseNotification ou testNotification.

messageId é um identificador único da notificação, e o guia de referência recomenda verificar essa unicidade para não processar notificações duplicadas e fazer chamadas redundantes às APIs de backend — o que desperdiça exatamente a cota de API que o RTDN existe para proteger.

Tipos de notificação de assinatura

Um subscriptionNotification carrega um inteiro notificationType, um purchaseToken e seu próprio version. O conjunto atual:

  • 1 — SUBSCRIPTION_RECOVERED: recuperada de retenção na conta ou retomada após pausa.
  • 2 — SUBSCRIPTION_RENEWED: uma assinatura ativa foi renovada.
  • 3 — SUBSCRIPTION_CANCELED: cancelada de forma voluntária ou involuntária; no caso de cancelamento voluntário, é enviado quando o usuário cancela.
  • 4 — SUBSCRIPTION_PURCHASED: uma nova assinatura foi comprada.
  • 5 — SUBSCRIPTION_ON_HOLD: entrou em retenção de conta, se você ativou esse recurso.
  • 6 — SUBSCRIPTION_IN_GRACE_PERIOD: entrou no período de tolerância, se você o ativou.
  • 7 — SUBSCRIPTION_RESTARTED: o usuário restaurou uma assinatura cancelada em Play → Conta → Assinaturas antes de ela expirar.
  • 9 — SUBSCRIPTION_DEFERRED: o prazo de recorrência foi estendido.
  • 10 — SUBSCRIPTION_PAUSED / 11 — SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED: pausada, ou o agendamento de pausa foi alterado.
  • 12 — SUBSCRIPTION_REVOKED: revogada antes do horário de expiração.
  • 13 — SUBSCRIPTION_EXPIRED: a assinatura expirou.
  • 17 — SUBSCRIPTION_ITEMS_CHANGED: um item de um pacote de assinatura foi alterado.
  • 18 — SUBSCRIPTION_CANCELLATION_SCHEDULED: cancelamento agendado para o fim de um período de compromisso de parcelamento.
  • 19 — SUBSCRIPTION_PRICE_CHANGE_UPDATED: os detalhes de mudança de preço de um item de assinatura foram atualizados.
  • 20 — SUBSCRIPTION_PENDING_PURCHASE_CANCELED: uma transação de assinatura pendente foi cancelada.
  • 22 — SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED: o período de consentimento para aumento de preço da assinatura começou, ou o usuário consentiu; enviado apenas em regiões onde o aumento de preço é exigido.

O tipo 8 (SUBSCRIPTION_PRICE_CHANGE_CONFIRMED) está marcado como descontinuado na referência, então não crie nova lógica com base nele. Note também que esses números não são um ciclo de vida que você possa inferir — o evento informa que o estado mudou, nunca o estado resultante.

Notificações de produtos de pagamento único

Só é enviado se você selecionou o escopo mais amplo. Um oneTimeProductNotification adiciona um campo sku ao token, com dois tipos: 1 — ONE_TIME_PRODUCT_PURCHASED (um produto de compra única foi comprado com sucesso) e 2 — ONE_TIME_PRODUCT_CANCELED (uma compra única pendente foi cancelada pelo usuário). Nos dois casos ainda é necessária uma chamada à Developer API, porque uma notificação de compra não diz nada sobre se você já consumiu ou reconheceu o produto.

Compras anuladas e o campo refundType

Uma voidedPurchaseNotification é o RTDN com que a maioria das equipes de receita se importa e, em 2026, ele carrega mais do que um token. O payload é purchaseToken, orderId, productType e refundType. productType é 1 para assinatura ou 2 para compra única. refundType é 1 — REFUND_TYPE_FULL_REFUND ou 2 — REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND, sendo que o último se aplica apenas a compras com várias quantidades, que podem ser parcialmente anuladas várias vezes; quando a quantidade total restante é reembolsada, o tipo passa a indicar reembolso total.

O guia de referência é explícito que, para localizar a compra e o pedido certos para ajustar direitos, a própria notificação é suficiente — e que a Google Play API de Compras Anuladas é o complemento no modelo pull, retornando dados de compras anuladas para um intervalo de timestamps. Para reembolsos parciais de várias quantidades, o campo refundableQuantity de purchases.productsv2 informa quantos produtos comprados ainda não foram anulados. Isso se combina diretamente com as mudanças na contabilização de estornos e reembolsos que abordamos no guia de reembolsos e estornos do Play de 2026.

Regras do servidor que mantêm o pipeline correto

  • Trate a notificação como uma pergunta, não como uma resposta. Chame a API do Desenvolvedor após cada RTDN para obter o status completo antes de conceder, estender ou revogar o direito.
  • Elimine duplicatas por messageId. O Pub/Sub entrega pelo menos uma vez; processar em duplicidade significa chamadas de API duplicadas e transições de estado duplicadas.
  • Sempre confirme o recebimento, depois processe. Pull: confirme as mensagens recebidas. Push: retorne um código de sucesso. Se o processamento demorar mais que a confirmação, aceite o reenvio e torne o handler idempotente.
  • Espere vários eventos por usuário. Um único purchaseToken pode gerar notificações de compra, cancelamento e depois expiração para o mesmo assinante — o manipulador precisa ser seguro para execução repetida.
  • Não faça polling para compensar. Consultar a Developer API em paralelo ao RTDN é o erro que dispara restrições de cota.

Verificando sua configuração

O Enviar mensagem de teste do console é a prova ponta a ponta mais rápida: se você tem uma assinatura vinculada, deve recebê-la. Um corpo de testNotification contém apenas um campo version, então é um payload seguro para validar na suíte de testes do seu handler. Sem backend ainda, use a linha de comando do gcloud para puxar a mensagem da assinatura — e lembre-se de confirmá-la. Um pipeline saudável aparece como um fluxo de eventos cujo packageName corresponde ao seu app e cujo eventTimeMillis acompanha a atividade dos assinantes em tempo real.

Uma observação sobre prazos: o trabalho de RTDN no lado do servidor anda junto com o prazo da Billing Library no lado do cliente. Todos os novos apps e atualizações devem usar a Billing Library versão 8 ou superior, com um caminho de extensão até 1º de novembro de 2026 — e a verificação no servidor que consome o RTDN deve estar pronta na mesma época.

Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.

Clique para escolher um arquivo · clique com o botão direito → Colar, ou pressione Ctrl/⌘+V para colar uma captura de tela

Você também pode arrastar um arquivo para esta caixa.

Respondemos ao e-mail que você fornecer. Seus dados ficam com KappS.

✔ Enviado

Recebemos sua mensagem e responderemos em até 24 horas.


← Voltar para editar