# Superwall

Importe eventos de paywall e assinatura do Superwall e use os dados de atribuição do Paywallo pra decidir qual paywall cada usuário vê: por origem, campanha e pago vs orgânico.

## Configurar o webhook

> **Pré-requisito:** Ative a integração no dashboard (Configurações → Integrações → Superwall) para gerar a URL do webhook e o secret.

1. No dashboard do Paywallo, vá em Configurações > Integrações > Superwall e copie a URL do webhook e o secret gerado.

2. No dashboard do Superwall, vá em Settings > Webhooks e adicione a URL no formato https://paywallo.com.br/api/webhook/superwall/{sua-chave-app}.

3. Ainda na tela de webhook do Superwall, adicione um custom header de autenticação:

| Header | Valor |
| --- | --- |
| `x-paywallo-secret` | o secret gerado pelo Paywallo |

O valor do header é o secret que você copiou do Paywallo. O Paywallo valida esse header em toda requisição. Webhooks sem o header correto são rejeitados com `401`.

4. Salve o webhook no Superwall. Os eventos vão começar a aparecer no Paywallo assim que houver uma compra, trial ou cancelamento real (ou em sandbox).

> **Como confirmar que chegou:** O botão Testar Conexão, dentro de Configurações → Integrações → Superwall, confirma só que a integração está ativa e o secret está salvo no Paywallo — ele não dispara nem recebe um evento real. Pra confirmar que o Superwall está de fato enviando, gere uma compra sandbox e confira se ela aparece em Transações em até um minuto. Se não aparecer, revise a URL e o custom header antes de repetir o teste.

## Eventos obrigatórios

Marque todos esses eventos no Superwall ao configurar o webhook. Eles são necessários pra atribuição e analytics funcionarem corretamente. Faltar um não trava os outros: só o que aquele evento cobre para de atualizar. Sem `cancellation`, um reembolso continua contando como venda. Sem `expiration`, a assinatura fica marcada como ativa mesmo depois de vencida.

 `initial_purchase`

 `renewal`

 `cancellation`

 `uncancellation`

 `expiration`

 `billing_issue`

 `non_renewing_purchase`

## Exemplo de configuração

![Configuração do webhook no Superwall](/docs/superwall-webhook-config.png)

## Segmentar paywalls por origem

O Paywallo envia os dados de atribuição pro Superwall como user attributes (prefixo `pw_`) automaticamente. Com eles você cria audiences no Superwall pra mostrar um paywall, preço ou oferta diferente dependendo de onde o usuário veio: Meta, TikTok, uma campanha específica ou tráfego orgânico.

> **Chame syncSuperwallAttributes antes do register:** O Superwall avalia as audiences no momento do register, e a variante que o usuário receber ali fica presa a ele até o assignment ser resetado. Como parte da atribuição só resolve alguns segundos depois do primeiro open, chame await syncSuperwallAttributes({ timeoutMs: 1500 }) imediatamente antes de registerPlacement. Sem isso, quem veio de anúncio pode ser avaliado como orgânico e ficar assim.

A função vem do próprio SDK (`@virex-tech/paywallo-sdk`), pergunta ao servidor se o install casou com algum clique e empurra os `pw_*` pro Superwall — tudo dentro do timeout que você passar. Ela nunca lança e nunca segura o paywall além desse tempo, então é seguro chamar em todo `registerPlacement`.

## Atributos disponíveis

Todos os atributos abaixo ficam disponíveis como filtro na tela de audience do Superwall. Os que não têm valor pro usuário simplesmente não aparecem. Usuário sem nenhuma atribuição capturada recebe `pw_is_paid = false`, então dá pra segmentar orgânico sem ambiguidade.

| Atributo | O que é | Exemplo |
| --- | --- | --- |
| `pw_ad_network` | Rede de origem já normalizada: facebook, ig, fb, apps.facebook.com e afins viram meta. Filtre por meta, tiktok, google ou apple_search_ads | `meta` |
| `pw_is_paid` | true pra tráfego pago, false pra orgânico | `true` |
| `pw_match_type` | Confiança da atribuição: deterministic (clique identificado) ou probabilistic (inferido por IP e device — o normal no iOS). Use pra exigir certeza antes de mudar preço | `deterministic` |
| `pw_utm_source` | Origem do UTM | `facebook` |
| `pw_utm_medium` | Mídia do UTM | `cpc` |
| `pw_utm_campaign` | Nome da campanha | `black_friday` |
| `pw_utm_content` | Criativo / anúncio | `video_a` |
| `pw_utm_term` | Termo ou palavra-chave | `app_dieta` |
| `pw_fbclid` | Click ID do Meta | `IwAR...` |
| `pw_gclid` | Click ID do Google | `Cj0K...` |
| `pw_ttclid` | Click ID do TikTok | `E5F...` |
| `pw_tiktok_campaign_id` | ID da campanha no TikTok | `17...` |
| `pw_tiktok_adgroup_id` | ID do adgroup no TikTok | `17...` |
| `pw_tiktok_ad_id` | ID do anúncio no TikTok | `17...` |
| `pw_referrer` | Referrer da landing page | `google.com` |
| `pw_install_referrer_source` | Origem do install referrer (Android) | `google-play` |
| `pw_attributed_at` | Quando a atribuição foi capturada (ISO) | `2026-07-08T...` |

## Criar uma audience no Superwall

1. No Superwall, abra a campanha em Campaigns e vá na aba Audiences > Add Audience.

2. Em Add Filter, digite pw na busca e escolha o atributo, por exemplo pw_ad_network.

3. Escolha o operador is e o valor (ex.: meta). Dá pra empilhar filtros: pw_ad_network is meta & pw_utm_campaign is black_friday.

4. Aponte essa audience pro paywall ou variante que você quer mostrar pra esse público e salve. Pronto: quem vem do Meta vê um paywall, o orgânico vê outro.

> **Exemplo:** Uma audience com "pw_ad_network is meta" mostra um paywall mais agressivo pra quem veio de anúncio pago do Meta, enquanto o orgânico (pw_is_paid is false) cai num paywall com trial mais longo.

## Rastreamento automático de compras

> **Não chame track de compra manualmente:** Compras realizadas via Superwall são rastreadas automaticamente pelo bridge do SDK Paywallo. Não é necessário (nem correto) chamar qualquer método de track de compra no seu código. Fazer isso duplicaria os eventos e distorceria os números de receita no dashboard.

O bridge intercepta os eventos de compra do Superwall e os envia ao Paywallo junto com o contexto de atribuição já disponível na sessão. Basta ter o SDK inicializado antes do primeiro `Superwall.register()`. O restante é automático.

## Verificação de compras e Sandbox

Uma transação só conta como **Comprador** e entra na receita do dashboard quando está com status `verified`. Em produção, a verificação vem do webhook da loja (Apple ou Google) confirmando a compra. Sem webhook configurado, a venda fica pendente e não aparece nos contadores de Compradores.

> **Sandbox: verificação automática:** Compras feitas em ambiente Sandbox são verificadas automaticamente pelo Paywallo, sem depender do webhook da loja. O usuário já aparece como Comprador imediatamente, o que facilita testar o funil completo durante o desenvolvimento.

> **Comportamento esperado no simulador iOS:** No simulador iOS com "Erase All Content and Settings", o StoreKit reinicia e toda compra passa a retornar transaction_id: '0'. Além disso, o IDFV muda a cada reset. Por isso os contadores de usuário e compra podem parecer estranhos no Sandbox. Não é bug do Paywallo. Em device real e em produção isso não ocorre.