Integrações
Meta Ads (Facebook)
Conecte o Paywallo ao Meta para enviar eventos de conversão server-side (via CAPI) e otimizar suas campanhas de aquisição.
Antes de começar
- Acesso Admin ou Full ao Business Manager. Acesso parcial não permite selecionar Ad Accounts durante a autorização OAuth.
- App já criado no Paywallo com Bundle ID configurado.
- SDK Paywallo instalado no app e já enviando eventos (o install precisa chegar antes da campanha começar a otimizar).
Criar o pixel (caso ainda não tenha)
Se você já tem um pixel (dataset) no Meta, pode ir direto para o Passo 1. Se ainda não tem, crie um agora: ele é o destino onde o Paywallo registra os eventos.
Acessa business.facebook.com/events_manager e clica em Conectar fontes de dados (Connect data sources).
Escolhe Web como tipo de fonte e avança.
Dá um nome ao dataset (o nome do seu app funciona bem) e confirma para criar.
Anota o Pixel ID, o número que aparece abaixo do nome do dataset. É ele que você vai selecionar no Paywallo no Passo 1.
Você não precisa instalar nenhum código de pixel em um site. O Paywallo envia os eventos direto pelo servidor (CAPI); o dataset serve apenas como destino.
Passo 1: Conectar com Meta (OAuth)
Recomendamos o fluxo OAuth via Login for Business. Ele não exige criar um System User nem gerar token manualmente: o próprio OAuth já concede o token de acesso.
No dashboard do Paywallo, vai em Integrações e abre o card Meta.
Clica no botão Conectar com Meta.
Você é redirecionado para o Meta (Login for Business). Autoriza as permissões solicitadas: ads_management e business_management.
De volta ao dashboard, seleciona o Pixel (Dataset) e as Ad Accounts que o Paywallo deve usar para enviar eventos. Clica em Salvar.
Depois de conectar, os eventos levam de 30 a 90 minutos para aparecer no Events Manager. Isso é esperado, não é falha de configuração.
Alternativa: gerar o token manualmente
Se você não usa o fluxo OAuth do Passo 1, o token precisa vir de um System User — nunca do seu usuário pessoal. O caminho tem algumas armadilhas que falham em silêncio, então siga exatamente nesta ordem.
Por que token de usuário pessoal é uma armadilha
Um token gerado a partir de um usuário pessoal herda o ciclo de vida dessa pessoa: expira periodicamente, e se ela sair da empresa, tiver o acesso ao Business Manager revogado ou desativar a própria conta do Facebook, o token morre junto — mesmo que ninguém tenha mexido na integração. Pior: a falha é silenciosa. O Meta não avisa o Paywallo, o pipeline de atribuição simplesmente para de enviar eventos via CAPI, sem erro visível no dashboard. Um System User não pertence a nenhuma pessoa — o token sobrevive a trocas de time e não expira pelo mesmo motivo. Use sempre System User em produção.
Acessa Business Settings → Usuários → Usuários do sistema. Não é na página do dataset: lá não existe opção de gerar token. Clica em Adicionarpra criar um (ex.: "Paywallo Integration") ou seleciona um que já exista.
Confere o papel do system user, logo abaixo do nome. Admin é o recomendado — com Employee a listagem de ativos pode vir incompleta na hora de conectar.
Com o system user selecionado, clica em Atribuir ativos e marca, todos com Acesso total: as Contas de anúncios que rodam as campanhas do app, os Pixels e os Conjuntos de dados.
O mesmo pixel aparece em duas listas separadas — uma chamada Pixels e outra Conjuntos de dados. Ele precisa estar nas duas. Marcar só uma é o erro mais comum aqui.
Acesso parcial no dataset não basta
Com Acesso parcial (Usar o conjunto de dados de eventos) o envio de eventos funciona, mas a escrita não. Ao salvar a integração, o Paywallo tenta adicionar paywallo.link à lista de permissões do dataset automaticamente — e com acesso parcial essa chamada é recusada sem nenhum erro na tela: o painel salva como sucesso e o domínio nunca entra. Você só descobre quando os eventos não otimizam. Ou usa Acesso total, ou autoriza o domínio na mão pelo Passo 2.
Clica em Gerar token. No primeiro passo, Selecionar app, escolhe o app do Business que vai emitir o token.
Só aparecem na lista os apps com caso de uso de anúncios habilitado. Se o app que você procura não estiver lá, é isso que falta — um admin do app precisa adicionar o caso de uso, ou você escolhe outro app da lista. Prefira o app do próprio produto a um app compartilhado entre vários: se ele quebrar, só a atribuição daquele produto para.
Em Definir expiração, escolhe Nunca.
O Meta marca “60 dias” como recomendado — não use
Token com validade morre em 60 dias e leva o CAPI junto. A falha é silenciosa: o Meta não avisa o Paywallo, o dashboard não mostra erro, os eventos simplesmente param de chegar no Events Manager. Nunca é a opção correta para um System User.
Em Atribuir permissões, marca ads_management, ads_read e business_management. Se algum dos três não aparecer, o app escolhido no passo 4 não tem caso de uso de anúncios — volta e seleciona outro.
Conclui e copia o token na hora. O Meta exibe uma única vez; depois de fechar a janela não tem como recuperar, só gerar outro.
Cola em Integrações → Meta no dashboard do Paywallo, junto com o Pixel ID e o Ad Account ID.
Não clique em “Anular tokens”
O botão fica ao lado de Gerar token e invalida de uma vez todos os tokens daquele system user, inclusive os que outras integrações estejam usando. Gerar um token novo não invalida os anteriores, então não existe motivo pra anular antes.
Pixel ID: Events Manager → Conjuntos de dados, é o número que aparece abaixo do nome. Ad Account ID: Ads Manager, formato act_XXXXXXXXX no canto superior esquerdo.
Eventos enviados
Com a conexão pronta, o Paywallo já envia esses eventos automaticamente via CAPI. Não precisa configurar nada no código do app.
paywallo_installpersonalizadoEnviado quando um install é atribuído a um clique de campanha. É um evento personalizado: você precisa aceitá-lo no Events Manager antes de usá-lo em campanhas.
PurchasepadrãoEnviado quando uma compra acontece, com valor e moeda. Reconhecido automaticamente pelo Meta.
StartTrialpadrãoEnviado quando um usuário inicia um período de trial. Reconhecido automaticamente pelo Meta.
ViewContentpadrãoEnviado quando o paywall é aberto pelo usuário. Reconhecido automaticamente pelo Meta.
CompleteRegistrationpadrãoEnviado quando o usuário completa o onboarding. Reconhecido automaticamente pelo Meta.
Renovações de assinatura não são enviadas ao Meta. Isso é intencional, para não inflar as conversões no painel de campanhas.
Passo 2: Aceitar o evento e autorizar o domínio
O paywallo_install é um evento personalizado, então o Meta exige que você o confirme no Events Manager antes de usá-lo como objetivo de conversão. Os outros eventos (Purchase, StartTrial, ViewContent, CompleteRegistration) são padrão do Meta e já são reconhecidos automaticamente, sem confirmação manual.
Esse passo exige controle total do ativo de negócio no Business Manager. Sem controle total, o botão de revisão não aparece: alguém com controle total precisa fazer a confirmação por você ou conceder esse acesso.
Acessa business.facebook.com/events_manager e, no menu lateral, abre Conjuntos de dados (Datasets). Seleciona o dataset configurado no Paywallo.
Na aba Configurações (Settings), no topo da página, rola até Restrições de dados (Data Restrictions).
Na seção Gerenciar bloqueio de eventos personalizados (Manage Custom Event Blocking), clica em Revisar (Review).
Na aba Ação necessária (Action Required), seleciona paywallo_install entre os eventos personalizados a confirmar e clica em Próximo (Next).
Escolhe Confirmar o evento personalizado (Confirm Custom Event), vai pra aba Revisão (Review) e clica em Concluído (Done).
Evento confirmado pode ser usado em campanha, conversão personalizada e público personalizado. Evento bloqueado, não: enquanto o paywallo_install não for confirmado, campanhas com objetivo de conversão nele ficam sem otimização.
Para confirmar que está funcionando, volta ao dataset no Events Manager e localiza a linha de paywallo_install. Estado deve mostrar Ativo, Integração deve mostrar API de Conversões, e o Total de eventos sobe a cada novo install atribuído.
Depois, autorize o domínio paywallo.link
O Paywallo envia os eventos com origem no domínio paywallo.link. O Meta só considera eventos vindos de domínios autorizados no dataset, então você precisa adicioná-lo à lista de permissões. Sem isso, os eventos podem ser descartados ou perder prioridade na otimização.
Esse passo só é possível depois que os primeiros eventos chegarem ao dataset (o mesmo prazo de 30 a 90 minutos do Passo 1). Se você acabou de conectar a integração e o domínio ainda não aparece, aguarde os primeiros eventos chegarem.
No Events Manager, com o dataset (pixel) selecionado, abre Configurações (Settings).
Encontra a seção Permissões de tráfego (Traffic Permissions) e abre a aba Sites (Websites).
O domínio paywallo.link aparece numa lista, populada a partir dos eventos já recebidos. Localiza ele e clica em Adicionar à lista de permissões (Add to allow list). Não existe campo para digitar o domínio.
Salva. A partir daí o Meta passa a aceitar os eventos que o Paywallo envia por CAPI.
Use exatamente paywallo.link, sem https:// nem caminho. É o domínio que o Paywallo declara como origem dos eventos, independente do link de tracking que você usa nos anúncios.
Passo 3: Criar a campanha
Com os passos anteriores concluídos, crie a campanha de aquisição.
No Ads Manager, clica em Create e seleciona o objetivo Vendas (Sales).
Em Conversion location, seleciona Website. O Paywallo envia todos os eventos via CAPI com action_source: website. Se você escolher "App" aqui sem o extinfo correto, o Meta retorna erros de parâmetro inválido.
Seleciona o dataset (pixel) configurado no Paywallo e escolhe o evento de conversão: paywallo_install para otimizar installs, ou Purchase para otimizar compras.
Em Placements, restringe para Mobile e seleciona apenas o sistema operacional do app (iOS ou Android). Desabilita Audience Network para evitar tráfego de baixa qualidade.
No nível do anúncio, em Website URL, cole o tracking link do Paywallo. É o link que você cria no Growth Hub para essa campanha, . Use esse link (e não a URL da App Store): ele captura o fbclid automaticamente e vincula o clique ao install no matching probabilístico.
Checklist antes de lançar
Antes de subir a campanha, confirme que cada item está pronto:
SDK do Paywallo instalado e já enviando eventos (o install aparece no painel).
Integração com o Meta conectada, com o Pixel e as Ad Accounts selecionados.
Evento paywallo_install aceito no Events Manager.
Domínio paywallo.link autorizado nas Permissões de tráfego do dataset.
Campanha com Conversion location Website e o tracking link no campo Website URL.
Solução de problemas
Não conecta / authentication failed
Confirme que sua conta tem papel Admin no Business Manager. Acesso parcial (analista, editor de anúncios) não concede as permissões ads_management e business_management necessárias para o OAuth completar.
Eventos não aparecem no Events Manager
Se depois de 2 horas nada aparecer, verifique se o Pixel ID configurado no Paywallo corresponde ao dataset correto e se o domínio paywallo.link está autorizado.
Eventos pararam de chegar de uma hora pra outra, sem erro no painel
Quase sempre é o token. Confira em Business Settings → Usuários do sistema se ele foi gerado com expiração Nunca e a partir de um System User — token de 60 dias ou de usuário pessoal morre em silêncio, o Meta não avisa o Paywallo. Se alguém clicou em Anular tokens, todos os tokens daquele system user foram invalidados de uma vez. Gere outro e cole novamente em Integrações → Meta.
"value field is missing" ao otimizar por valor com trials
É esperado. Eventos StartTrial não têm valor monetário associado, trials são gratuitos. O Meta exige o campo value para campanhas que otimizam por valor, então use Purchase como evento de conversão quando precisar otimizar por receita.
Essa página foi útil?
Desenvolvido e mantido por Virex