Acompanhar o churn com as notificações de developer em tempo real do Google Play

O Google Play informa o seu backend das alterações nas subscrições através das notificações de developer em tempo real (RTDN), publicadas num tópico Google Cloud Pub/Sub. São a base de qualquer acompanhamento sério do churn numa app Android: quem cancelou, quem tem um problema de faturação, quem pausou, quem saiu de facto.

Há um senão que determina tudo o resto: uma notificação só diz que algo mudou. Este guia trata da configuração, de como processar cada mensagem, de como os tipos de notificação correspondem às métricas de churn e dos erros que distorcem os números. Baseia-se na documentação da Google: configurar as RTDN, a referência das RTDN, o ciclo de vida das subscrições e a referência da API para purchases.subscriptionsv2 (todos consultados em novembro de 2026).

Configurar as notificações

O guia de configuração da Google explica os passos:

1. Crie um tópico Pub/Sub num projeto Google Cloud.
2. Dê à conta de serviço google-play-developer-notifications@system.gserviceaccount.com a função Pub/Sub Publisher no tópico.
3. Crie uma subscrição no tópico: push para um endpoint HTTPS no seu backend, ou pull a partir de um worker.
4. Na Play Console, introduza o nome do tópico para a sua app e clique em Send Test Message.
5. Escolha os tipos de notificação: apenas subscrições e compras anuladas, ou tudo, incluindo produtos únicos.

Confirme (acknowledge) todas as mensagens. Nas subscrições pull, a Google diz para confirmar as mensagens obtidas “para evitar entregas repetidas pelo Cloud Pub/Sub”; no push, um código de resposta de sucesso serve de confirmação.

Processar uma mensagem

Cada mensagem Pub/Sub tem um campo data em base64. Descodificado, contém version, packageName, eventTimeMillis e exatamente um de subscriptionNotification, oneTimeProductNotification, voidedPurchaseNotification, pendingRefundReviewNotification ou testNotification.

Uma notificação de subscrição só traz um notificationType e um purchaseToken. A referência da Google é explícita: “tem de chamar a Google Play Developer API depois de receber as notificações de developer em tempo real para obter o estado completo”, porque as notificações “não lhe dão informação completa sobre a compra.” O guia do ciclo de vida chama a purchases.subscriptionsv2.get “a fonte de verdade para a gestão das subscrições.”

Por isso, o processo é:

1. Receber, verificar o messageId para eliminar duplicados (a Google recomenda-o), guardar a mensagem em bruto, confirmar.
2. Chamar purchases.subscriptionsv2.get com o purchase token.
3. Guardar o estado obtido como uma fotografia, com o tipo de notificação e eventTimeMillis.
4. Atualizar o direito de acesso e as suas métricas a partir dessa fotografia, e não apenas da notificação.

Tenha em conta que o purchase token só funciona até 60 dias depois da expiração. Obtenha o estado quando a notificação chega, não semanas depois.

Os tipos de notificação de subscrição

Da referência das RTDN:

Código	Tipo	O que aconteceu
1	SUBSCRIPTION_RECOVERED	Recuperada da suspensão da conta, ou retomada depois de uma pausa
2	SUBSCRIPTION_RENEWED	Uma subscrição ativa renovou
3	SUBSCRIPTION_CANCELED	Cancelada, voluntária ou involuntariamente
4	SUBSCRIPTION_PURCHASED	Nova subscrição comprada
5	SUBSCRIPTION_ON_HOLD	Entrou em suspensão da conta
6	SUBSCRIPTION_IN_GRACE_PERIOD	Entrou no período de tolerância
7	SUBSCRIPTION_RESTARTED	O utilizador restaurou uma subscrição cancelada ainda não expirada
9	SUBSCRIPTION_DEFERRED	Data de renovação prolongada
10	SUBSCRIPTION_PAUSED	A pausa entrou em vigor
11	SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED	Pausa agendada ou alterada
12	SUBSCRIPTION_REVOKED	Revogada antes da expiração
13	SUBSCRIPTION_EXPIRED	Expirada
18	SUBSCRIPTION_CANCELLATION_SCHEDULED	Cancelamento de um plano em prestações agendado para o fim do compromisso
20	SUBSCRIPTION_PENDING_PURCHASE_CANCELED	Uma transação pendente foi cancelada

Há mais alguns (itens alterados, atualizações de alteração de preço, consentimento para aumento de preço). O código 8 está obsoleto.

Os estados que importam para o churn

O campo subscriptionState da API é mais fiável do que o tipo de notificação para contar. O guia do ciclo de vida descreve o que cada estado significa para o acesso:

Estado	O utilizador tem acesso?	Significado para o churn
SUBSCRIPTION_STATE_ACTIVE	Sim	Subscritor
SUBSCRIPTION_STATE_IN_GRACE_PERIOD	Sim	Em risco: o pagamento falhou
SUBSCRIPTION_STATE_ON_HOLD	Não	Em risco: o pagamento falhou, acesso bloqueado
SUBSCRIPTION_STATE_PAUSED	Não	Em pausa, não saiu
SUBSCRIPTION_STATE_CANCELED	Até expiryTime	Em risco: renovação parada
SUBSCRIPTION_STATE_EXPIRED	Não	Saiu

O período de tolerância e a suspensão da conta têm valores por defeito que vale a pena conhecer. O período de tolerância está ativado por defeito em todos os planos base com renovação automática. A suspensão da conta também está ativada por defeito, com uma duração que a Google calcula como 60 dias menos o período de tolerância. Ambos podem ser alterados na Play Console. Antes de a suspensão da conta começar, a Google faz tentativas de cobrança adicionais durante até 48 horas.

Dos eventos às métricas de churn

Contar o churn na expiração

SUBSCRIPTION_CANCELED significa que a renovação parou, não que o utilizador saiu. Mantém o acesso até expiryTime e pode restaurá-lo (SUBSCRIPTION_RESTARTED). Conte o churn em SUBSCRIPTION_EXPIRED e use os cancelamentos como indicador antecipado.

Separar o churn voluntário do involuntário

O canceledStateContext do recurso de subscrição diz quem cancelou:

• userInitiatedCancellation: voluntário. Pode também conter a resposta ao inquérito de cancelamento do utilizador.
• systemInitiatedCancellation: cancelado pelo sistema, “por exemplo por causa de um problema de faturação”. É o seu churn involuntário.
• developerInitiatedCancellation: foi o comerciante que cancelou.
• replacementCancellation: substituída por uma nova subscrição, por exemplo depois de uma mudança de plano. Não é churn.

O caminho da faturação tem uma sequência reconhecível: SUBSCRIPTION_IN_GRACE_PERIOD, depois SUBSCRIPTION_ON_HOLD, depois SUBSCRIPTION_RECOVERED ou, no fim da suspensão da conta, SUBSCRIPTION_CANCELED seguido imediatamente de SUBSCRIPTION_EXPIRED.

Não conte as pausas como churn

SUBSCRIPTION_RECOVERED é disparado tanto quando uma subscrição sai da suspensão da conta como quando é retomada depois de uma pausa. Verifique o estado anterior antes de a contar como uma recuperação de faturação.

Tratar mudanças de plano e novas inscrições

Os upgrades, downgrades e novas inscrições na app antes da expiração criam uma nova compra com um novo token. A nova subscrição tem um linkedPurchaseToken que aponta para a antiga. Se não seguir estas ligações, cada mudança de plano parece um subscritor que saiu e um subscritor novo.

As novas subscrições a partir da Play Store depois da expiração são diferentes: a Google diz que não trazem linkedPurchaseToken, mas a resposta da API inclui outOfAppPurchaseContext com o token expirado até confirmar a compra. Conte-as como reativações.

Revogações

SUBSCRIPTION_REVOKED significa que o acesso terminou mais cedo: o comerciante revogou-o, ou a compra foi alvo de chargeback. O estado passa a expirado. Reporte-o separadamente do churn normal, junto com as compras anuladas.

Um relatório mensal

1. Ativos no início: subscrições nos estados ativa, período de tolerância ou cancelada mas não expirada.
2. Churn voluntário: expirações cujo contexto é iniciado pelo utilizador.
3. Churn involuntário: expirações cujo contexto é iniciado pelo sistema.
4. Taxa de recuperação de faturação: subscrições que entraram no período de tolerância ou em suspensão da conta e foram recuperadas, sobre todas as que entraram.
5. Restauros: SUBSCRIPTION_RESTARTED.
6. Em pausa: número, e quantas são retomadas.
7. Reativações: novas subscrições na Play Store e novas inscrições na app depois da expiração.

As fórmulas gerais estão em como calcular a taxa de churn.

Erros comuns

• Confiar apenas no tipo de notificação. Obtenha sempre o estado da subscrição.
• Contar os cancelamentos como churn. Inflaciona o churn e esconde os restauros.
• Ignorar os linked purchase tokens. As mudanças de plano tornam-se falso churn.
• Chamar a API tarde demais. Os tokens deixam de funcionar 60 dias depois da expiração.
• Não confirmar as mensagens Pub/Sub. Recebe duplicados e desperdiça quota da API.
• Nenhum ID de conta ofuscado na compra. Não consegue juntar os dados do Play com os seus próprios dados de utilizadores.

Fazer isto com o NoChurn

Aponta as suas notificações de developer em tempo real do Play para o NoChurn e dá-lhe uma conta de serviço com acesso à sua Play Console. O NoChurn obtém o estado da subscrição para cada evento, segue os linked purchase tokens, separa o churn voluntário, de faturação e por revogação, e mantém uma cronologia por cliente, associada através do ID de conta ofuscado que define na compra. O período de tolerância, a suspensão da conta e os cancelamentos alimentam a pontuação de churn de 0 a 100, e pode acrescentar os seus próprios atributos por API. A Google mantém os pagamentos, as novas tentativas e o botão de cancelar. Veja NoChurn + Google Play.