Rastreamento de assinaturas da App Store

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.

Visão geral da integração

App Store Server Notifications é 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* correspondente no perfil do usuário.

Nota

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.

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.

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

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.

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.

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.

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

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.

StoreKit 2

// 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)

StoreKit 1

// 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)

Cuidado

Se o seu aplicativo substitui o HWID do Pushwoosh (por exemplo, através do módulo de HWID persistente PushwooshKeychain 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.

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

Nota

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.

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 com uma entrada baseada em gatilho 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.
4. Confirme que os eventos aparecem em alguns instantes.