# Rastreamento de assinaturas do Google Play

<Aside type="caution" icon="setting" title="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.
</Aside>

## Visão geral da integração

As [Notificações do desenvolvedor em tempo real (RTDN)](https://developer.android.com/google/play/billing/rtdn-reference) 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*`](#tracked-events) correspondente no perfil do usuário.

<Aside type="note">
Esta integração suporta **assinaturas do Android** (Google Play RTDN). Para rastrear assinaturas do iOS, consulte [Rastreamento de assinaturas da App Store](/pt/product/integrations/app-store-subscription-tracking/).
</Aside>

### 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.

<details>

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

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.

</details>

### 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.

<Aside type="caution" title="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](#set-the-account-identifier-at-purchase).
</Aside>

### 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](/pt/product/customer-journey/pushwoosh-journey-overview/) com um push de retenção, um [e-mail](/pt/product/messaging-channels/emails/) sobre os recursos que eles perderiam ou uma [mensagem in-app](/pt/product/messaging-channels/in-apps/) 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](/pt/developer/pushwoosh-sdk/android-sdk/firebase-integration/integrate-pushwoosh-android-sdk/) (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.

<Tabs>
<TabItem label="Kotlin">
```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)
```
</TabItem>
<TabItem label="Java">
```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);
```
</TabItem>
</Tabs>

<Aside type="note">
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.
</Aside>

<Aside type="caution">
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.
</Aside>

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

1. No [Google Play Console](https://play.google.com/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](/pt/product/customer-journey/pushwoosh-journey-overview/) com uma [entrada baseada em gatilho](/pt/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/) 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](/pt/product/audience-data-and-segmentation/user-explorer/#events-history-tab).
4. Confirme que os eventos aparecem em alguns instantes.