Integrações
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.
No dashboard do Paywallo, vai em Configurações > Integrações > Superwall e copia a URL do webhook e o secret gerado.
No dashboard do Superwall, vai em Settings > Webhooks e adiciona a URL no formato https://paywallo.com.br/api/webhook/superwall/{sua-chave-app}.
Ainda na tela de webhook do Superwall, adiciona um custom header de autenticação:
x-paywallo-secreto secret gerado pelo PaywalloO 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.
Salva o webhook no Superwall. Os eventos vão começar a aparecer no Paywallo em tempo real.
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.
initial_purchaserenewalcancellationuncancellationexpirationbilling_issuenon_renewing_purchaseExemplo de configuração
Audiences
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 orgânico recebe só pw_is_paid = false, então dá pra segmentar orgânico sem ambiguidade.
pw_ad_networkRede de origem já normalizada: facebook, ig, fb, apps.facebook.com e afins viram meta. Filtre por meta, tiktok, google ou apple_search_adsmetapw_is_paidtrue pra tráfego pago, false pra orgânicotruepw_match_typeConfianç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çodeterministicpw_utm_sourceOrigem do UTMfacebookpw_utm_mediumMídia do UTMcpcpw_utm_campaignNome da campanhablack_fridaypw_utm_contentCriativo / anúnciovideo_apw_utm_termTermo ou palavra-chaveapp_dietapw_fbclidClick ID do MetaIwAR...pw_gclidClick ID do GoogleCj0K...pw_ttclidClick ID do TikTokE5F...pw_tiktok_campaign_idID da campanha no TikTok17...pw_tiktok_adgroup_idID do adgroup no TikTok17...pw_tiktok_ad_idID do anúncio no TikTok17...pw_referrerReferrer da landing pagegoogle.compw_install_referrer_sourceOrigem do install referrer (Android)google-playpw_attributed_atQuando a atribuição foi capturada (ISO)2026-07-08T...Criar uma audience no Superwall
No Superwall, abre a campanha em Campaigns e vai na aba Audiences > Add Audience.
Em Add Filter, digita pw na busca e escolhe o atributo, por exemplo pw_ad_network.
Escolhe o operador is e o valor (ex: meta). Dá pra empilhar filtros: pw_ad_network is meta & pw_utm_campaign is black_friday.
Aponta essa audience pro paywall ou variante que você quer mostrar pra esse público e salva. 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.
Essa página foi útil?
Desenvolvido e mantido por Virex