- O rastreamento de conversões no CCV Shop fica mais completo quando cada pedido pago é enviado a partir dos dados de pedido do CCV, no servidor, com um snippet na página de sucesso do pedido que associa o pedido ao clique no anúncio.
- Um clique em Create webhook faz o CCV Shop reportar cada pedido no instante em que ele é marcado como pago, e cada envio precisa levar o token privado da sua loja.
- Os pedidos do CCV Shop não incluem o endereço IP do comprador, então o snippet da página de sucesso do pedido importa mais no CCV Shop do que na maioria das plataformas.
- A verificação de 5 minutos só olha para os pedidos criados recentemente, então os pedidos pagos dias depois dependem do webhook: mantenha-o ativo.
- O Meta rejeita eventos de servidor mais de 7 dias depois da criação do pedido, então uma transferência bancária muito tardia não chega ao Meta.
Rastrear conversões no CCV Shop significa reportar cada pedido pago da sua loja online no CCV Shop a plataformas de anúncios como Meta e TikTok, para que elas atribuam o crédito aos anúncios certos e otimizem com base em vendas reais. A forma mais completa é enviar cada compra a partir dos dados de pedido do CCV, no servidor, e adicionar um snippet curto à página de sucesso do pedido que associa o pedido ao clique no anúncio.
O CCV Shop é uma plataforma de loja online hospedada da empresa holandesa CCV, que diz ter 17,000 lojas online. Este guia explica como o ROASaurus se conecta a ela, como os pedidos são associados aos cliques em anúncios, o que chega ao Meta e ao TikTok, a configuração, os testes e como funcionam os pagamentos tardios. Para a ideia geral, leia o que é rastreamento server-side.
Como o ROASaurus se conecta ao CCV Shop?
O ROASaurus usa três partes do CCV Shop, todas descritas na documentação da API do CCV:
| Parte do CCV Shop | Para que o ROASaurus a usa |
|---|---|
| REST API, com uma chave pública e uma chave secreta | Lê cada pedido pago e as linhas do pedido |
Webhook para o evento orders.updated.ispaid | O CCV reporta um pedido no instante em que o status de pagamento dele muda |
A página de sucesso do pedido, com Vertoshop.js | O snippet lê o ID do pedido ali e associa o pedido ao visitante |
Por que os pixels do navegador não enxergam as compras do CCV Shop?
Um pixel do navegador só reporta uma compra quando o navegador do comprador carrega a página de sucesso do pedido e o script do pixel é executado. Várias situações comuns impedem isso:
- O comprador paga por redirecionamento, por exemplo com iDEAL, e fecha a aba antes de a página de sucesso carregar.
- Um bloqueador de anúncios ou uma configuração de privacidade do navegador bloqueia o script do pixel.
- O visitante recusa os cookies de marketing, então o pixel não pode carregar.
- O pedido é pago depois, por transferência bancária ou na entrega, quando nenhum navegador está envolvido.
Em cada caso, o CCV Shop ainda marca o pedido como pago. O ROASaurus envia esse pedido a partir do servidor, então a compra é reportada seja o que for que tenha acontecido no navegador. O snippet da página de sucesso tem outra função: ele informa ao ROASaurus a qual visitante, e portanto a qual clique no anúncio, o pedido pertence.
O webhook de pedido pago e a verificação de 5 minutos
O que o Create webhook faz
Quando você pressiona Create webhook, o ROASaurus registra um webhook do CCV para o evento orders.updated.ispaid, que o CCV dispara quando a propriedade de pagamento de um pedido muda. O endereço é a URL de webhook da sua loja no ROASaurus, que contém a sua chave de loja e um token privado. O CCV não acrescenta ao webhook nada que identifique a loja, e a documentação dele recomenda pôr um identificador no endereço. A chave de loja cumpre esse papel.
O CCV dá a cada webhook a sua própria chave secreta de 32 caracteres. Quando o CCV devolve essa chave, o ROASaurus a salva e, a partir daí, todo envio precisa trazer um cabeçalho x-hash válido. Cada envio também precisa trazer o token da sua loja. Quando o ROASaurus recebe um envio, ele ignora os pedidos que não estão pagos, lê o pedido completo e as linhas dele pela API e só envia o pedido quando o CCV diz que está pago.
Chamadas de API assinadas
O CCV exige que toda chamada de API seja assinada. O ROASaurus envia três cabeçalhos: x-public com a sua chave pública, x-date com a hora atual e x-hash. O CCV rejeita um carimbo de data e hora que difere mais de 5 minutos do horário do servidor dele. A sua chave secreta nunca é enviada.
API call (ROASaurus → CCV) x-hash = HMAC-SHA512( public_key|METHOD|uri|body|timestamp , secret_key ) Webhook (CCV → ROASaurus) x-hash = HMAC-SHA512( address|payload , webhook_key )
A verificação de 5 minutos
A cada 5 minutos, o ROASaurus também pede ao CCV os pedidos pagos criados desde a última verificação, com 30 minutos de sobreposição, e registra os que ainda não tem. O CCV filtra os pedidos apenas pela data de criação. Assim, a verificação encontra os pedidos pagos logo depois de feitos, e um pedido pago dias depois chega ao ROASaurus apenas pelo webhook.
O CCV considera uma resposta 200, 201, 202 ou 204 como sucesso. Ele mantém um envio aberto e tenta de novo na próxima ocorrência após uma resposta 307, 408, 503 ou 504, e marca qualquer outra resposta como falha. Ele espera 2 segundos por uma conexão e 5 segundos pela resposta.
Como um pedido do CCV Shop é associado ao clique no anúncio?
Para dar crédito a um anúncio, a plataforma precisa dos identificadores de clique do visitante que fez o pedido, como o ID de clique do Meta (fbc) e o ID de clique do TikTok (ttclid). O script do ROASaurus os guarda para cada visitante quando ele chega por um anúncio. O ROASaurus não obtém esse ID de visitante do pedido do CCV, então associa os pedidos aos visitantes de outras formas:
| Método | No CCV Shop | Como funciona |
|---|---|---|
| 1. Snippet da página de sucesso do pedido | Sim | Ele lê o ID do pedido com Vertoshop.getOrder().getId(), mais o total do pedido e a moeda, e dispara uma compra do ROASaurus com o ID de evento order-58213 |
| 2. E-mail anterior | Sim | Um e-mail com hash que o visitante informou antes no seu site, em um formulário de popup ou por meio de uma chamada Identify |
| 3. Endereço IP e navegador | Não | Os pedidos do CCV Shop não incluem o endereço IP nem o navegador do comprador, então essa alternativa não tem nada para comparar |
O ROASaurus espera um pouco antes de enviar cada compra, para que o evento da página de sucesso possa chegar primeiro, e tenta a associação de novo na hora do envio. A página Orders mostra o resultado por pedido na coluna Matched by: thank_you, email ou not matched.
Um pedido que não é associado ainda vai para as suas plataformas de anúncios com os dados de cliente com hash do pedido. Ele não tem identificadores de clique e, como os pedidos do CCV não trazem endereço IP nem navegador, também não tem nenhum desses. Isso reduz a parcela de eventos que o Meta consegue associar a uma pessoa; Event Match Quality explica como o Meta avalia isso. Na atribuição do ROASaurus, um pedido não associado aparece como direto ou desconhecido.
O que chega ao Meta e ao TikTok a partir de um pedido do CCV?
| Dados do pedido do CCV | Enviado como |
|---|---|
id | O ID de evento order-58213 e o ID do pedido |
total_price, currency | Valor e moeda (EUR quando o CCV não informa a moeda) |
create_date | O horário do evento |
| E-mail, celular ou telefone, nome e sobrenome do cliente | Com hash SHA-256 |
| Cidade, CEP e código do país de cobrança | Com hash SHA-256 |
| ID do cliente | ID externo com hash |
| Linhas do pedido: número do produto, ID do produto, quantidade, preço e nome | Produtos com ID, quantidade e preço |
| Endereço IP e navegador | Não vêm nos pedidos do CCV: obtidos do evento da página de sucesso ou do visitante associado |
O Meta recebe um Purchase pela Conversions API, e o TikTok um CompletePayment pela Events API, ambos com o ID de evento order-58213. O TikTok agora mostra o CompletePayment como Purchase nos relatórios dele. Quando você marca a opção de carregar também o pixel do navegador, o snippet da página de sucesso dispara os mesmos eventos no navegador com o mesmo ID de evento, e o Meta e o TikTok ficam com uma única cópia. Os mesmos pedidos vão para Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn e as outras plataformas de anúncios quando você as conecta. As conversões de compra do Google Ads são enviadas apenas pelo checkout do Shopify, então o ROASaurus não as envia a partir do CCV Shop.
Como configurar o rastreamento de conversões no CCV Shop
- Adicione a loja no ROASaurus
Vá em Add a store, escolha CCV Shop e informe o endereço da sua loja. A aba Connection mostra então a sua tag de script e o snippet da página de sucesso.
- Encontre as suas chaves de API
No CCV Shop, vá em My webshop › Settings › General › API settings e clique em New API key. Se você não vir essa opção, instale primeiro o app de API na CCV App Store.
- Adicione o script a todas as páginas
Cole a tag de script no Header HTML da sua loja. A central de ajuda do CCV a coloca em Mijn webshop › Instellingen › Lay-out › Layout, no fim da página. Um bloco de código de app no cabeçalho também funciona.
- Adicione o snippet à página de sucesso
Vá em Mijn webshop › Instellingen › Algemeen › Teksten, abra o texto exibido depois que um pedido é feito, mude para Source e cole o snippet ali. O CCV Shop então o executa na página de confirmação do pedido.
- Conecte a API
Na aba Connection, informe a chave pública e a chave secreta. Preencha Shop URL somente quando a sua API roda em um domínio diferente do da loja. Salve, pressione Test connection e depois Create webhook.
- Conecte as suas plataformas de anúncios
Em Tracking & platforms, use Connect with Facebook ou Add pixel para o Meta, e Add pixel para o TikTok. Marque a opção de carregar também o pixel do navegador.
Consentimento
Fora do Shopify, o script do ROASaurus lê a escolha do visitante em ferramentas de consentimento comuns: Cookiebot, OneTrust, banners IAB TCF e Google consent mode. Com outro banner de cookies, chame tlq('consent', true) quando o visitante aceitar os cookies de marketing e tlq('consent', false) quando ele os recusar. Enquanto o visitante não aceitar, ele não tem ID de visitante nem IDs de clique, e nenhum pixel do navegador dispara. O pedido pago ainda é enviado do servidor com dados do cliente em hash vindos do pedido. A página de ajuda sobre consentimento explica os detalhes.
Como testar o rastreamento de conversões no CCV Shop?
- Abra a sua loja com
?roasaurus=connectedno endereço. Um alerta confirma que o script está rodando.?roasaurus=debugregistra no console do navegador o que ele envia. - No Event log, em Collected events, as visualizações de página devem mostrar um ID de visitante.
- Faça um pedido e pague-o, ou marque-o como pago. Em Collected events, o Event log deve mostrar um Purchase com o ID do pedido do CCV nos dados dele. Se ele estiver faltando, o snippet da página de sucesso não rodou.
- Na aba Connection, Last order received mostra o pedido e Last sync a última verificação de 5 minutos, com qualquer erro do CCV.
- Em Server deliveries no Event log, cada plataforma conectada recebe uma linha com o status sent e a resposta da plataforma.
PageView visitor 51c0e9a7Script em todas as páginasPurchase order-58213Snippet da página de sucesso do pedidowebhook orders.updated.ispaidAssinatura conferida, pedido pagoMeta Purchase sentMatched by thank_youTikTok CompletePayment sentMesmo ID de evento, deduplicadoPara ver o evento no Meta, cole o código de Events Manager › Test events no campo Test event code do seu pixel do Meta no ROASaurus e remova-o quando terminar.
Pagamentos tardios e outros limites
Transferências bancárias e pagamentos na entrega são pagos depois que o pedido é feito. Veja o que acontece com um pedido de exemplo por transferência bancária, a partir do dia em que é feito:
| Quando | O que acontece | Resultado |
|---|---|---|
| Dia 0, no checkout | O pedido é criado, não pago | Não enviado: a verificação de 5 minutos pede apenas pedidos pagos |
| Dia 0, cerca de 35 minutos depois | O horário de criação do pedido sai da janela de verificação | A partir de agora, só o webhook pode reportá-lo |
| Dia 3 | Você marca o pedido como pago | O webhook chega, o ROASaurus o envia. O horário do evento, Dia 0, tem 3 dias: o Meta o aceita |
| Dia 9, em vez disso | Você marca o pedido como pago | O webhook chega, o ROASaurus o envia. 9 dias é mais que 7: o Meta o rejeita |
- Pagamento na entrega. O ROASaurus envia esses pedidos quando o CCV os marca como pagos, geralmente depois da entrega. Veja o rastreamento de pagamento na entrega para saber quando contar esses pedidos.
- Compras no navegador antes do pagamento. O snippet da página de sucesso roda quando o pedido é feito, então os pixels do navegador reportam um pedido por transferência bancária antes de ele ser pago. Se o pagamento vem mais de 48 horas depois, o Meta e o TikTok não conseguem unir as cópias do navegador e do servidor.
- Sem alternativa por IP. Adicione o snippet da página de sucesso e capture e-mails mais cedo no seu site sempre que puder.
- Cancelamentos e reembolsos não são enviados. Depois que uma compra é enviada, ela permanece na plataforma de anúncios.
- Só visualizações de página, sem código. As visualizações de produto e os itens adicionados ao carrinho são detectados automaticamente apenas no Shopify. No CCV Shop, um desenvolvedor pode enviá-los com uma chamada de rastreamento
tlq.
A página de integração com o CCV Shop reúne os dados da conexão em um só lugar, e a página de ajuda para outras lojas online compara o CCV Shop com as outras plataformas às quais o ROASaurus se conecta, como o Lightspeed.
Fontes
- CCV Shop: API Documentatie
- CCV: Webshop API
- Meta for Developers: Server Event Parameters
- Meta for Developers: Handling Duplicate Pixel and Conversions API Events
- TikTok Ads Manager: About Event Deduplication
No ROASaurus
- Integração com o CCV Shop
- Ajuda: Wix, Lightspeed e outras lojas online
- Rastreamento server-side
- Integração com o Meta