Snapchat Conversions API (CAPI): implementação server-side e envio na conversão real

Por que Snapchat precisa de server-side#

O público do Snapchat é majoritariamente mobile e jovem, e a plataforma vive num ambiente onde restrições de rastreamento de app e bloqueio de cookies chegaram cedo e forte. O Snap Pixel no navegador e o SDK no app capturam parte das conversões, mas uma parcela relevante escapa — especialmente em iOS, onde o consentimento de rastreamento reduz o sinal disponível ao cliente. A Conversions API (CAPI) do Snapchat envia o evento direto do seu servidor para o Snap, contornando o dispositivo como via de transmissão e restaurando conversões que o Pixel sozinho perderia.

Além da cobertura, a CAPI dá o controle que a casa considera inegociável: o evento de conversão sai do servidor no momento em que a conversão é real. O Snapchat recebe PURCHASE quando o pagamento foi aprovado, não quando o usuário tocou em "comprar".

Eventos padrão do Snapchat#

O Snapchat trabalha com eventos padronizados que a otimização de campanha reconhece:

• PURCHASE — a compra concluída, com valor e moeda.
• ADD_CART — item adicionado ao carrinho.
• PAGE_VIEW — visualização de página.
• SIGN_UP — cadastro concluído.
• PURCHASE, START_CHECKOUT, ADD_BILLING, SUBSCRIBE — etapas de funil de compra.
• LEAD, COMPLETE_TUTORIAL, AD_CLICK, CUSTOM_EVENT_1..5 — sinais complementares.

Cada evento compõe um envelope com campos de topo e um bloco de identificação de usuário. Os campos estruturais principais:

• event_name — um dos nomes padronizados.
• event_time — timestamp em milissegundos.
• action_source — a origem: WEB, MOBILE_APP ou OFFLINE.
• event_conversion_type — em modelos anteriores, WEB/MOBILE_APP/OFFLINE; alinhe ao formato da versão que você usa.
• pixel_id (web) ou snap_app_id (app) — o ativo que recebe o evento.
• event_id — a chave de deduplicação com o Pixel.
• user_data — as match keys.
• custom_data — valor, moeda, content_ids, num_items, order_id.

Match keys: o que identifica o usuário#

O user_data reúne os sinais de identidade. PII vai hasheada em SHA-256 após normalização; sinais de clique/contexto vão em claro.

Hasheados:

• em — email normalizado e SHA-256.
• ph — telefone em formato internacional, só dígitos, hasheado.
• madid — mobile advertising ID (IDFA/GAID) hasheado, para eventos de app.
• external_id — seu ID interno de cliente hasheado; sinal estável que ajuda muito.

Em claro:

• sc_click_id — o Snapchat Click ID, capturado do parâmetro ScCid da URL quando o usuário chega por um anúncio, e o cookie _scid que o Pixel grava. É o sinal de correspondência mais forte no web. Persista-o em cookie first-party no primeiro toque.
• client_ip_address — o IP do cliente.
• client_user_agent — o user-agent do navegador do cliente.

Como sempre, a normalização antes do hash tem que ser idêntica no Pixel e no servidor, ou a deduplicação por identidade falha. Centralize numa única função de borda.

Deduplicação com o Snap Pixel#

Rodando Pixel e CAPI em paralelo — a arquitetura híbrida recomendada para cobertura máxima —, a deduplicação evita a contagem dupla. O Snapchat deduplica pela combinação de event_id com o evento. Regras:

• Gere o event_id no servidor quando o pedido é criado; use o ID do pedido ou um ULID atrelado.
• Repasse esse mesmo event_id ao Pixel no navegador para que os dois envios de PURCHASE carreguem o valor idêntico.
• Mantenha o mesmo event_name nas duas pontas.

Recebendo dois PURCHASE com o mesmo event_id, o Snap mantém apenas um. Sem isso, cada compra dobra e a taxa de conversão fica irreal.

O padrão da casa: evento na conversão confirmada#

O Pixel dispara PURCHASE na tela de sucesso, o que inclui pagamentos que ainda vão falhar. Server-side, você inverte: o evento sai do webhook do gateway de pagamento.

1. O usuário finaliza; o pedido nasce pendente e você já capturou sc_click_id, email e external_id no checkout.
2. O gateway aprova e chama seu webhook.
3. O handler valida a assinatura, confirma o pagamento e monta o PURCHASE com o valor real cobrado.
4. A chamada à CAPI sai com o event_id do pedido e as match keys.

O Snapchat passa a otimizar para compradores reais. Uma plataforma que só recebe o evento na conversão confirmada aprende a encontrar quem gera receita, não quem abandona o pagamento — que é exatamente a promessa de mensurar a conversão real.

Conversões offline e app#

O Snapchat aceita action_source igual a OFFLINE para reportar vendas do mundo físico casando email/telefone do cliente com o público que viu o anúncio. Para apps, o MOBILE_APP com madid e o snap_app_id liga a conversão dentro do aplicativo à campanha. O mecanismo de identidade e hash é o mesmo; muda a origem declarada e o ativo que recebe.

Entrega confiável#

Chamar a CAPI dentro do fluxo de conversão exige robustez. O padrão da casa é o outbox:

• Outbox transacional. O webhook grava o evento numa fila persistente na mesma transação do pedido; um worker consome com retry e backoff. Se o Snap estiver indisponível, o evento não se perde nem trava a resposta ao gateway.
• Idempotência. O event_id estável garante que reprocessamentos deduplicam; marque o item como enviado com atualização atômica.
• Batch. A CAPI aceita múltiplos eventos por chamada; agrupe respeitando o teto.
• Erro honesto. Payload malformado é bug a corrigir; erro transitório é retry. Nunca engula; logue com trace_id e alerte na alta de falhas.

iOS, ATT e por que o server-side é decisivo no Snapchat#

O público do Snapchat é fortemente iOS, e o iOS é onde a App Tracking Transparency (ATT) mais corta o sinal disponível ao cliente. Quando o usuário nega o rastreamento, o identificador de anúncio (IDFA) fica indisponível e o sinal client-side encolhe. Isso torna a CAPI não um complemento, mas a espinha dorsal da mensuração no Snapchat.

Dois pontos práticos:

• Match por dados hasheados ganha peso. Sem IDFA, o email e o telefone hasheados, mais o sc_click_id, passam a carregar a correspondência. Capturar identidade de qualidade no checkout vira ainda mais importante do que em plataformas menos afetadas.
• SKAdNetwork para apps. Para conversões dentro de aplicativos iOS, o Snapchat também trabalha com o framework de atribuição privada da Apple; a CAPI web e a atribuição de app são trilhas distintas. Não misture: eventos de site vão com action_source igual a WEB; eventos de app seguem o fluxo de app com o snap_app_id.

A leitura correta é que o server-side no Snapchat recupera exatamente o sinal que a ATT tirou do cliente — por isso a diferença de conversões medidas antes e depois de implementar a CAPI costuma ser mais expressiva aqui do que em outras redes.

CAPI Gateway e formas de integração#

Nem toda equipe quer construir a integração da CAPI do zero. O Snapchat oferece caminhos de integração de esforço variável:

• Integração direta pela API. Seu backend chama o endpoint da CAPI. É o caminho de maior controle, ideal quando você já tem a arquitetura de outbox e quer disparar no webhook de pagamento.
• CAPI Gateway / conectores. Soluções que recebem seus eventos e os encaminham ao Snapchat com menos código de integração. Reduzem o trabalho inicial, mas verifique que ainda permitem disparar a conversão só no momento real — um conector que apenas espelha o pixel não entrega o controle que a casa exige.
• Integrações de plataforma de e-commerce. Plugins que ligam a loja ao Snapchat. Convenientes, mas frequentemente disparam na tela de sucesso; se for esse o caso, ajuste para o gatilho de pagamento confirmado.

A escolha do caminho não muda o princípio: o evento de conversão precisa nascer da confirmação real, e a deduplicação com o Pixel precisa estar correta.

Otimização por valor e qualidade#

Reportar PURCHASE sem valor deixa a otimização cega para receita. Preencha o custom_data com value, currency e content_ids para que o Snapchat otimize por ROAS, não só por contagem de conversões. Em contas com ticket variável, otimizar por valor muda completamente quais usuários a plataforma busca — deixa de perseguir a compra barata e passa a mirar a receita.

Validação e monitoramento#

• Ferramenta de teste de eventos. O Events Manager do Snapchat permite validar o formato dos eventos recebidos e ver quais campos de match foram reconhecidos, sem sujar os números de produção.
• Taxa de correspondência. Acompanhe a proporção de eventos casados. Baixa correspondência denuncia falta de sc_click_id, hashes inconsistentes ou IP do servidor em vez do IP do cliente.
• Reconciliação financeira. O total de PURCHASE reportado deve bater, dentro de margem, com os pedidos pagos do período. Divergência aponta dedupe quebrado ou evento fora do webhook.

Erros comuns na CAPI do Snapchat#

Alguns problemas silenciosos derrubam a qualidade da mensuração no Snapchat sem produzir erro visível no seu backend:

• Timestamp na unidade errada. O event_time do Snapchat é em milissegundos; enviar em segundos coloca o evento fora da janela e ele é descartado. É um dos erros mais frequentes na primeira integração.
• sc_click_id não persistido. Capturar só na conversão, quando o ScCid já saiu da URL, desperdiça o sinal de correspondência mais forte. Grave no primeiro toque.
• Normalização divergente entre Pixel e CAPI. Se o Pixel hasheia o email de um jeito e o servidor de outro, a deduplicação por identidade quebra e você conta a mesma compra duas vezes.
• IP do servidor em vez do IP do cliente. Em arquitetura com CDN ou proxy, ler o cabeçalho errado zera um sinal de match e derruba a taxa de correspondência.
• Evento fora do webhook. Disparar PURCHASE na tela de sucesso conta pagamentos que ainda vão falhar, inflando a receita reportada.

Tratar cada um desses pontos na revisão de implementação evita semanas de otimização degradada por um problema que não aparece nos logs, só na queda silenciosa da qualidade do match.

Checklist de implementação#

• Eventos padrão (PURCHASE, ADD_CART, SIGN_UP) com nomes corretos.
• sc_click_id capturado no primeiro toque e persistido em cookie first-party.
• Match keys (em, ph, external_id) hasheadas com normalização única.
• IP e user-agent do cliente, nunca do servidor.
• event_id estável compartilhado entre Pixel e CAPI.
• PURCHASE disparado no webhook de pagamento aprovado.
• Outbox com retry, idempotência e alerta.
• Conversões offline e de app reportadas quando aplicável.
• Taxa de correspondência e reconciliação financeira monitoradas.

Snapchat opera num terreno hostil ao rastreamento no cliente, o que torna o server-side não um luxo, mas a base. Com match keys completas, deduplicação certa e o evento disparado só na conversão real, a CAPI devolve a atribuição que o Pixel perde e ensina a campanha a mirar receita.