Rastreamento de conversões

Como disparar um postback quando um usuário converte no seu site - obrigatório para campanhas CPA atribuírem e cobrarem corretamente.

Para campanhas CPA, só sabemos que um usuário converteu quando you nos avisa. O mecanismo é um postback: quando o usuário faz o que você quer que ele faça no seu site, seu servidor dispara uma requisição rápida para o nosso, e registramos a conversão contra o clique original. Sem essa fiação, sua campanha CPA vai servir cliques mas nunca cobrar - porque não temos como saber que algum deles virou cliente.

Esta página percorre a fiação. Cerca de 15 minutos de trabalho de desenvolvimento, sem SDK.

O fluxo

1. Um usuário clica no seu anúncio no site de um publisher.
2. Nosso servidor de anúncios adiciona ?efaid=<click_id> à sua URL de destino e redireciona o usuário para lá. O ID do clique é uma string hexadecimal de 24 caracteres, única para este clique.
3. Sua landing page captura o valor de efaid (parâmetro de URL) e o armazena - geralmente em um cookie de sessão que sobrevive entre carregamentos de página.
4. Quando o usuário conclui o que conta como conversão (cadastro, compra, instalação), seu servidor dispara um postback para https://ads.efind.com/serve/postback.php?efaid=<click_id>.
5. Procuramos o clique, registramos a conversão e cobramos você pela taxa de lance vigente no momento do clique.

Passo 1: capture o efaid na sua landing page

A URL no navegador do usuário quando ele chega ao seu site terá esta aparência:

https://example.com/landing?efaid=ee40d35706798218cce42929

Pegue o parâmetro efaid e armazene-o. Cookies são a escolha mais comum porque sobrevivem a funis de múltiplas etapas. Exemplo em JavaScript:

const url = new URL(window.location); const efaid = url.searchParams.get('efaid'); if (efaid) { document.cookie = `efaid=${efaid}; path=/; max-age=${30*24*60*60}; SameSite=Lax`; }

Ou em PHP, se você controla a landing page no servidor:

<?php if (!empty($_GET['efaid']) && preg_match('/^[a-f0-9]{24}$/', $_GET['efaid'])) { setcookie('efaid', $_GET['efaid'], time() + 30*24*60*60, '/', '', true, true); }

Passo 2: dispare o postback na conversão

No instante em que a conversão acontecer no servidor, dispare um único GET para a nossa URL de postback com o efaid:

PHP

$efaid = $_COOKIE['efaid'] ?? ''; if ($efaid !== '') { $url = 'https://ads.efind.com/serve/postback.php?efaid=' . urlencode($efaid); // Fire and forget - don't block the user's request on this. @file_get_contents($url, false, stream_context_create([ 'http' => ['timeout' => 2, 'ignore_errors' => true] ])); }

Node.js

const efaid = req.cookies.efaid; if (efaid) { fetch(`https://ads.efind.com/serve/postback.php?efaid=${encodeURIComponent(efaid)}`) .catch(() => {}); // fire-and-forget }

Python

import requests efaid = request.COOKIES.get('efaid') if efaid: try: requests.get(f'https://ads.efind.com/serve/postback.php?efaid={efaid}', timeout=2) except requests.RequestException: pass

cURL (para testes ou stacks baseados em shell)

curl -s "https://ads.efind.com/serve/postback.php?efaid=$EFAID"

Alternativa: baseada em pixel (sem acesso ao servidor)

Se você não puder disparar um postback server-side - comum em landing pages SaaS ou páginas simples de agradecimento - pode usar um pixel de imagem 1×1. Coloque isto no HTML da sua página de confirmação de conversão (página de "obrigado" do Shopify, confirmação de pedido do Wix etc.):

<img src="https://ads.efind.com/serve/pixel.php?efaid=YOUR_EFAID_HERE" width="1" height="1" alt="" style="display:none">

Você precisará substituir o YOUR_EFAID_HERE pelo valor armazenado - a maioria das plataformas de e-commerce tem uma forma de injetar HTML personalizado com metadados do pedido. Pixels são um pouco menos confiáveis que postbacks de servidor (bloqueadores de anúncios, navegadores bloqueando requisições de terceiros), mas são mais fáceis de configurar.

Formato da resposta

postback.php retorna JSON. pixel.php retorna a imagem, mas adiciona informações de depuração nos cabeçalhos - útil para verificar a integração com as ferramentas de desenvolvedor do navegador.

Formato do JSON

{ "ok": true, "recorded": true, "reason": null } ← conversion logged ✓ { "ok": true, "recorded": false, "reason": "already_recorded" } ← duplicate fire (no harm) { "ok": true, "recorded": false, "reason": "not_found" } ← efaid doesn't match a click { "ok": true, "recorded": false, "reason": "bad_click_id" } ← malformed efaid { "ok": true, "recorded": false, "reason": "window_expired" } ← click was over 30 days old

O status HTTP é sempre 200, independentemente do resultado. O sinal de funcionou-ou-não está em recorded. Sua integração deve tratar recorded: true como sucesso e qualquer outro estado como "disparou mas não pegou" - o que geralmente é aceitável (a maioria dos motivos de "não" é operacionalmente normal).

Testando sua integração

1. Configure uma campanha de teste no painel (qualquer lance - você não será cobrado por conversões de teste em campanhas em rascunho).
2. A partir do site de um publisher ou diretamente pela URL do nosso servidor de anúncios, clique em um anúncio e anote o efaid anexado à sua URL de destino.
3. Acione seu fluxo de conversão de uma forma que dispare o postback.
4. Verifique a página de detalhes da campanha no seu painel - a estatística de Conversões deve subir em até um minuto.
5. Dispare o mesmo postback de novo com o mesmo efaid - a estatística NÃO deve subir uma segunda vez (idempotente).

Comportamentos importantes

• Idempotent. Disparar o mesmo postback duas vezes (retentativas de rede, erros de desenvolvimento) é seguro - só o primeiro conta.
• O lance é congelado no momento do clique. Se você mudar seu lance depois de um clique mas antes do postback de conversão, usamos o lance vigente no momento do clique. Isso mantém a economia dos publishers estável.
• Janela de 30 dias. Postbacks de cliques com mais de 30 dias são ignorados silenciosamente. Se você tem um funil de conversão excepcionalmente longo, fale com a gente - podemos ampliar a janela por anunciante.
• Cliques de bots não recebem efaid. Nossa camada de deduplicação filtra spam de atualização óbvio e bots de clique ingênuos no momento do clique; esses redirecionamentos não incluem um efaid, então não há nada para fazer postback. Isso protege seu investimento.