Rastreamento de assinaturas do Google Play

Assistência de desenvolvedor necessária

Você precisará da ajuda de sua equipe de desenvolvimento para configurar esta integração. Por favor, compartilhe este guia com eles.

Visão geral da integração

As Notificações do desenvolvedor em tempo real (RTDN) são um serviço de servidor para servidor do Google Play que envia uma mensagem em tempo real sempre que o status de uma assinatura muda.

Ao conectar o Google Play RTDN ao Pushwoosh, você pode reagir a todo o ciclo de vida da assinatura, incluindo compras, renovações, cancelamentos, problemas de faturamento, expirações e reembolsos — sem construir sua própria infraestrutura de backend. Sempre que o status de uma assinatura muda na conta do Google Play de um usuário, o Google notifica o Pushwoosh, e o Pushwoosh dispara o evento PW_Subscription* correspondente no perfil do usuário.

Nota

Esta integração suporta assinaturas do Android (Google Play RTDN). Para rastrear assinaturas do iOS, consulte Rastreamento de assinaturas da App Store.

Tipo de integração

Fonte: As Notificações do desenvolvedor em tempo real são enviadas do Google Play para o Pushwoosh.

Eventos rastreados

O Pushwoosh mapeia cada notificação suportada do Google Play para um conjunto de eventos unificado PW_Subscription*, para que você possa acionar campanhas em qualquer estágio do ciclo de vida da assinatura.

Evento	Dispara quando
PW_SubscriptionStart	Um usuário compra a assinatura pela primeira vez.
PW_SubscriptionRenew	A assinatura é renovada automaticamente para um novo período de faturamento.
PW_SubscriptionCancel	Um usuário desativa a renovação automática. A assinatura permanece ativa até expirar.
PW_SubscriptionResume	Um usuário reinicia a assinatura antes que ela expire.
PW_SubscriptionBillingIssue	Um pagamento de renovação falha e a assinatura entra em seu período de carência.
PW_SubscriptionRecovered	Uma renovação que falhou anteriormente é concluída e a assinatura volta a ficar ativa.
PW_SubscriptionExpired	A assinatura expirou completamente e não está mais ativa.
PW_SubscriptionRefund	O Google Play revoga a assinatura (por exemplo, após um reembolso).

Cada evento carrega os mesmos atributos:

• productID: o identificador de produto do Google Play da assinatura.
• expiresAt: quando o período pago atual termina, como um timestamp Unix em segundos. Incluído quando o Google o fornece.

Como os eventos são mapeados para as Notificações do desenvolvedor em tempo real

Para desenvolvedores que verificam a integração, cada evento do Pushwoosh corresponde a estes valores de notificationType do RTDN:

Evento do Pushwoosh	notificationType do RTDN
PW_SubscriptionStart	SUBSCRIPTION_PURCHASED (4)
PW_SubscriptionRenew	SUBSCRIPTION_RENEWED (2)
PW_SubscriptionCancel	SUBSCRIPTION_CANCELED (3)
PW_SubscriptionResume	SUBSCRIPTION_RESTARTED (7)
PW_SubscriptionBillingIssue	SUBSCRIPTION_IN_GRACE_PERIOD (6)
PW_SubscriptionRecovered	SUBSCRIPTION_RECOVERED (1)
PW_SubscriptionExpired	SUBSCRIPTION_EXPIRED (13)
PW_SubscriptionRefund	SUBSCRIPTION_REVOKED (12)

Outros tipos de notificação, como em espera, alterações de preço, adiamentos e pausas, são reconhecidos, mas não publicam um evento.

Como funciona

Uma notificação do Google Play não carrega um identificador do Pushwoosh. Ela inclui apenas um token de compra e o packageName do aplicativo. Portanto, seu aplicativo marca cada compra com o identificador que o Pushwoosh precisa, e o Pushwoosh o lê de volta da compra sempre que uma notificação chega.

1. O status de uma assinatura muda na conta do Google Play de um usuário (uma compra, renovação, cancelamento, etc.).
2. O Google Play publica uma mensagem RTDN no tópico compartilhado do Pushwoosh.
3. O Pushwoosh lê o obfuscatedAccountId da compra, que seu aplicativo definiu como <AppCode>:<hwid> no momento da compra.
4. O Pushwoosh resolve o dispositivo cujo HWID corresponde, encontra o usuário vinculado a ele e publica o evento PW_Subscription* correspondente para esse usuário.

Importante

A correspondência entre uma compra do Google Play e um usuário do Pushwoosh depende do obfuscatedAccountId. Se o seu aplicativo não definir esse valor no momento da compra, o Pushwoosh recebe a notificação, mas nenhum evento é publicado. Ele é definido na compra e não pode ser preenchido retroativamente para assinaturas existentes. Veja como definir o identificador da conta.

Casos de uso

Reconquistar assinantes em churn: Desativar a renovação automática não encerra o acesso imediatamente. A assinatura permanece ativa até o final do período pago, e essa é a sua janela para reconquistar o usuário. Em PW_SubscriptionCancel, inicie uma Customer Journey com um push de retenção, um e-mail sobre os recursos que eles perderiam ou uma mensagem in-app com um desconto de renovação antes que o acesso expire.

Integrar novos assinantes: Acione uma série de boas-vindas em PW_SubscriptionStart para ajudar os usuários a obter valor de seu plano desde o início e preparar o terreno para a renovação.

Resgatar pagamentos com falha: Quando PW_SubscriptionBillingIssue é acionado, um pagamento de renovação não foi concluído e a assinatura está em seu período de carência. Peça ao usuário para atualizar seu método de pagamento antes que perca o acesso e acompanhe com PW_SubscriptionRecovered para confirmar assim que for resolvido.

Reengajar usuários inativos: Inicie uma campanha de reativação em PW_SubscriptionExpired com uma oferta de retorno para assinantes que cancelaram completamente.

Configurando a integração

Antes de começar, certifique-se de que você tem um aplicativo Pushwoosh com FCM configurado (já necessário para push), um aplicativo do Google Play com uma assinatura e acesso de administrador ao Play Console.

Definir o identificador da conta na compra

O Pushwoosh identifica o usuário correto a partir do HWID do dispositivo, combinado com o seu Código do Aplicativo. O SDK do Pushwoosh para Android expõe um auxiliar, getSubscriptionAccountId(), que retorna esse valor já formatado como <AppCode>:<hwid>. Passe-o para BillingFlowParams.setObfuscatedAccountId() quando você iniciar o fluxo de faturamento do Google Play.

Kotlin

val billingParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    // Tag the purchase with the Pushwoosh account identifier "<AppCode>:<hwid>"
    .setObfuscatedAccountId(Pushwoosh.getInstance().subscriptionAccountId)
    .build()

billingClient.launchBillingFlow(activity, billingParams)

Java

BillingFlowParams billingParams = BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        // Tag the purchase with the Pushwoosh account identifier "<AppCode>:<hwid>"
        .setObfuscatedAccountId(Pushwoosh.getInstance().getSubscriptionAccountId())
        .build();

billingClient.launchBillingFlow(activity, billingParams);

Nota

Chame getSubscriptionAccountId() após a inicialização do SDK. Ele retorna uma string vazia se o Código do Aplicativo ou o HWID ainda não estiverem disponíveis. O Google limita o ID da conta ofuscado a 64 caracteres. O valor <AppCode>:<hwid> do Pushwoosh permanece dentro desse limite.

Cuidado

Se o seu aplicativo substituir o HWID do Pushwoosh por um valor personalizado, getSubscriptionAccountId() o reflete automaticamente. Não construa o identificador manualmente. Sempre use o auxiliar para que o valor corresponda ao HWID do dispositivo no Pushwoosh, ou o evento não poderá ser atribuído.

Apontar as Notificações do desenvolvedor em tempo real para o Pushwoosh

1. No Google Play Console, vá para Monetizar → Configuração da monetização.
2. Encontre Notificações do desenvolvedor em tempo real e defina o Nome do tópico para:

projects/pw-playstore-subscriptions/topics/play-rtdn

3. Clique em Salvar. A permissão de publicação já foi concedida ao serviço de notificação do Google, então não há mais nada a configurar aqui.

Conceder acesso à conta de serviço do Pushwoosh

1. No Google Play Console, vá para Usuários e permissões → Convidar novo usuário.
2. Insira o e-mail da conta de serviço do Pushwoosh:

play-api@pw-playstore-subscriptions.iam.gserviceaccount.com

3. Em Permissões do app, adicione seu aplicativo e conceda Visualizar dados financeiros, pedidos e respostas a pesquisas de cancelamento (além da permissão de informações do aplicativo somente leitura).
4. Clique em Salvar. Uma conta de serviço não precisa aceitar o convite. O acesso fica ativo imediatamente.

Confirmar os eventos no Pushwoosh

O Pushwoosh registra cada evento PW_Subscription* em seu projeto na primeira vez que ele ocorre, com os atributos productID e expiresAt. Após um teste, abra Público → Eventos para verificar se os eventos aparecem. Eles estarão então prontos para segmentação, estatísticas e Customer Journeys.

Construir sua campanha

Crie uma Customer Journey com uma entrada baseada em gatilho em qualquer evento PW_Subscription*, por exemplo PW_SubscriptionCancel para reconquista ou PW_SubscriptionStart para integração, e adicione as mensagens que deseja enviar.

Testando

Para verificar a integração de ponta a ponta:

1. No Google Play Console, abra a Configuração da monetização e clique em Enviar notificação de teste. Deve relatar sucesso, confirmando que o tópico está conectado corretamente.
2. Faça uma compra de assinatura com o identificador da conta definido como descrito acima (isso dispara PW_SubscriptionStart), depois cancele-a em Play Store → Assinaturas → Cancelar (isso dispara PW_SubscriptionCancel).
3. No Painel de Controle do Pushwoosh, abra o perfil do usuário и vá para o Histórico de eventos.
4. Confirme que os eventos aparecem em alguns instantes.