# Rastreamento de assinaturas da App Store

<Aside type="caution" icon="setting" title="Necessária a assistência de um desenvolvedor">
Você precisará da ajuda da sua equipe de desenvolvimento para configurar esta integração. Por favor, compartilhe este guia com eles.
</Aside>

## Visão geral da integração

[App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications) é o serviço de servidor para servidor da Apple que envia uma mensagem em tempo real para o seu backend sempre que o status de uma assinatura muda.

Ao conectar as Notificações do Servidor da App Store 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 da App Store de um usuário, a Apple 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 iOS** (Notificações do Servidor da App Store V2). Para rastrear assinaturas do Android, consulte [Rastreamento de assinaturas do Google Play](/pt/product/integrations/google-play-subscription-tracking/).
</Aside>

### Tipo de integração

**Fonte:** As Notificações do Servidor da App Store são enviadas da Apple para o Pushwoosh.

### Eventos rastreados

O Pushwoosh mapeia cada notificação suportada da App Store 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 por 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 reativa a renovação automática ou se reinscreve antes que a assinatura expire. |
| `PW_SubscriptionBillingIssue` | Um pagamento de renovação falha e a assinatura entra no período de nova tentativa de faturamento da Apple. |
| `PW_SubscriptionRecovered` | Uma renovação que falhou anteriormente é concluída e a assinatura fica ativa novamente. |
| `PW_SubscriptionExpired` | A assinatura expirou completamente e não está mais ativa. |
| `PW_SubscriptionRefund` | A Apple reembolsa a compra ou revoga o acesso. |

Cada evento carrega os mesmos atributos:

- **productID:** o identificador de produto da App Store da assinatura.
- **expiresAt:** quando o período pago atual termina, como um timestamp Unix em segundos. Incluído quando a Apple o fornece.

<details>

<summary>Como os eventos são mapeados para as Notificações do Servidor da App Store</summary>

Para desenvolvedores que verificam a integração, cada evento do Pushwoosh corresponde a estes valores de `notificationType` (e `subtype`) da App Store:

| Evento do Pushwoosh | `notificationType` / `subtype` |
| --------------- | ------------------------------ |
| `PW_SubscriptionStart` | `SUBSCRIBED` / `INITIAL_BUY` |
| `PW_SubscriptionRenew` | `DID_RENEW` |
| `PW_SubscriptionCancel` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_DISABLED` |
| `PW_SubscriptionResume` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_ENABLED`, `SUBSCRIBED` / `RESUBSCRIBE` |
| `PW_SubscriptionBillingIssue` | `DID_FAIL_TO_RENEW` |
| `PW_SubscriptionRecovered` | `DID_RENEW` / `BILLING_RECOVERY` |
| `PW_SubscriptionExpired` | `EXPIRED` |
| `PW_SubscriptionRefund` | `REFUND`, `REVOKE` |

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

</details>


### Como funciona

1. O status de uma assinatura muda na conta da App Store de um usuário (uma compra, renovação, cancelamento, etc.).
2. A Apple envia uma Notificação do Servidor da App Store (V2) para a sua URL de notificação do Pushwoosh.
3. O Pushwoosh decodifica a carga assinada e lê o `appAccountToken` da transação.
4. O Pushwoosh procura o dispositivo cujo HWID corresponde a esse token, 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 transação da App Store e um usuário do Pushwoosh depende do `appAccountToken`. Se o seu aplicativo não definir este token no momento da compra, o Pushwoosh recebe a notificação, mas **nenhum evento é publicado**. Veja [como definir `appAccountToken`](#set-appaccounttoken-to-the-devices-pushwoosh-hwid).
</Aside>

### Casos de uso

**Recupere 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.

**Integre 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.

**Resgate pagamentos com falha:** Quando `PW_SubscriptionBillingIssue` é acionado, um pagamento de renovação não foi concluído e a assinatura está na janela de nova tentativa da Apple. Peça ao usuário para atualizar seu método de pagamento antes que perca o acesso e faça o acompanhamento com `PW_SubscriptionRecovered` para confirmar assim que for resolvido.

**Reengaje usuários inativos:** Inicie uma campanha de reativação em `PW_SubscriptionExpired` com uma oferta para clientes que retornam para assinantes que cancelaram completamente.


## Configurando a integração

### Defina o `appAccountToken` para o HWID do Pushwoosh do dispositivo

O Pushwoosh identifica o usuário correto a partir do **HWID** do dispositivo, então seu aplicativo deve anexar o HWID do Pushwoosh do dispositivo como o `appAccountToken` quando a assinatura é comprada através do StoreKit.

Por padrão, o SDK do Pushwoosh para iOS usa o `identifierForVendor` (IDFV) do dispositivo como o HWID. O IDFV já é um `UUID`, exatamente o formato que a Apple exige para o `appAccountToken`. O Pushwoosh então resolve o usuário atualmente vinculado a esse dispositivo automaticamente, então isso funciona independentemente de você atribuir ou não seus próprios IDs de Usuário com `setUserId`.

<Tabs>
<TabItem label="StoreKit 2">
```swift
// Anexe o HWID do Pushwoosh do dispositivo (o IDFV padrão) como o appAccountToken
var options: Set<Product.PurchaseOption> = []
if let hwid = UIDevice.current.identifierForVendor {
    options.insert(.appAccountToken(hwid))
}

let result = try await product.purchase(options: options)
```
</TabItem>
<TabItem label="StoreKit 1">
```swift
// applicationUsername deve ser uma string UUID para preencher o appAccountToken
let payment = SKMutablePayment(product: product)
payment.applicationUsername = UIDevice.current.identifierForVendor?.uuidString
SKPaymentQueue.default().add(payment)
```
</TabItem>
</Tabs>

<Aside type="caution">
Se o seu aplicativo substitui o HWID do Pushwoosh (por exemplo, através do módulo de HWID persistente [`PushwooshKeychain`](/pt/developer/pushwoosh-sdk/ios-sdk/ios-keychain/) ou um valor personalizado), defina o `appAccountToken` para esse mesmo HWID. O token deve corresponder ao HWID do dispositivo no Pushwoosh, ou o evento não poderá ser atribuído.
</Aside>

### Encontre o seu Código de Aplicação Pushwoosh

Abra sua aplicação no Painel de Controle do Pushwoosh. Seu **Código de Aplicação** (formato `XXXXX-XXXXX`) é exibido abaixo do nome do projeto na barra lateral.

Você precisará do Código de Aplicação para construir a URL de notificação.

### Adicione a URL de notificação no App Store Connect

1. No [App Store Connect](https://appstoreconnect.apple.com/), vá para **Apps → seu app → Informações do App** (em *Geral*) e role até **Notificações do Servidor da App Store**.
2. Selecione as notificações da **Versão 2**.
3. Defina tanto a **URL do Servidor de Produção** quanto a **URL do Servidor de Sandbox** para:

```
https://appstore-notifications.pushwoosh.com/appstore/YOUR_APPLICATION_CODE/
```

4. Substitua `YOUR_APPLICATION_CODE` pelo Código de Aplicação do passo anterior. Mantenha a barra final.

<Aside type="note">
Se sua conta estiver hospedada no **data center dos EUA**, use `https://appstore-notifications.pushwoosh.us/appstore/YOUR_APPLICATION_CODE/` em vez disso. Se você não tiver certeza de qual data center sua conta usa, entre em contato com seu Gerente de Sucesso do Cliente ou com o [Suporte da Pushwoosh](https://www.pushwoosh.com/contact-us/).
</Aside>

### Confirme 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 no sandbox, abra **Público → Eventos** para verificar se os eventos aparecem. Eles estarão então prontos para segmentação, estatísticas, e Customer Journeys.

### Construa 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 recuperação ou `PW_SubscriptionStart` para integração, e adicione as mensagens que você deseja enviar.

## Testando

As Notificações do Servidor da App Store podem ser acionadas no ambiente **Sandbox** da Apple. Para verificar a integração:

1. Faça uma compra de assinatura no sandbox com o `appAccountToken` definido como descrito acima. Isso aciona o `PW_SubscriptionStart`.
2. Desative a renovação automática na tela de gerenciamento de assinaturas do dispositivo. Isso aciona o `PW_SubscriptionCancel`.
3. No Painel de Controle do Pushwoosh, abra o perfil do usuário e 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.