Rastreamento server-side no WooCommerce: um guia de configuração

O rastreamento server-side no WooCommerce envia cada pedido pago, a partir dos dados de pedido da sua loja, ao Meta, ao TikTok e a outras plataformas de anúncios, em vez de depender apenas de um pixel no navegador do comprador. A compra é informada mesmo quando um bloqueador de anúncios barra o pixel ou o comprador nunca chega à página de agradecimento.

Este guia explica por que as lojas WooCommerce perdem conversões, os dados de pedido que o WooCommerce oferece e as duas formas de conectar o ROASaurus: o plugin do WordPress ou webhooks. Depois, associação, consentimento, configuração e testes. Para a ideia geral, leia o que é rastreamento server-side.

Por que as lojas WooCommerce perdem conversões?

Um pixel do navegador informa uma compra apenas quando o script do pixel carrega, o comprador chega à página de agradecimento e o navegador envia o evento. Cada etapa pode falhar. O pedido em si continua no seu banco de dados, porque o WooCommerce o salva no servidor.

Compras que faltam causam dois tipos de dano. A plataforma de anúncios otimiza com menos conversões, e os seus relatórios mostram um retorno menor do que o que você realmente obtém. Veja o segundo efeito em números, para uma loja de exemplo com ROAS de equilíbrio de 2.2:

O que o WooCommerce oferece: pedidos, webhooks e a REST API

Quais status de pedido contam como pagos?

O WooCommerce descreve processing como pagamento recebido, com o pedido aguardando o envio. O ROASaurus envia pedidos com o status processing ou completed e ignora pedidos com os status pending payment, on hold, failed, cancelled e refunded. Duas formas de pagamento pedem atenção:

• Pagamento na entrega. O WooCommerce coloca esses pedidos em processing até o pagamento ser coletado, então o ROASaurus os envia quando são feitos. Pedidos com um produto para download são a exceção: eles ficam em on hold. Veja rastreamento de pedidos com pagamento na entrega para entender o que isso significa para devoluções e recusas.
• Transferência bancária. O WooCommerce coloca esses pedidos em on hold enquanto você verifica o pagamento. O ROASaurus os envia quando você os muda para processing.

Webhooks

Um webhook é uma mensagem que o WooCommerce envia a outro sistema quando algo muda. Você o cria em WooCommerce › Settings › Advanced › Webhooks. Para um tópico de pedido, o payload é o mesmo objeto de pedido que a REST API devolve. Cada envio traz um cabeçalho X-WC-Webhook-Signature: um hash HMAC-SHA256 em base64 do payload, feito com o segredo que você escolhe. O ROASaurus confere essa assinatura antes de aceitar um pedido.

Dois detalhes importam na prática. O WooCommerce entrega os webhooks em segundo plano, por padrão com o WP-Cron, então um envio pode atrasar quando essa fila anda lenta. E o WooCommerce desativa um webhook depois de mais de cinco falhas de entrega seguidas.

REST API

A REST API permite que o ROASaurus peça os pedidos por conta própria. Com uma chave de API somente leitura, o ROASaurus pede a cada 5 minutos os pedidos processing e completed alterados desde a última verificação, com 30 minutos de sobreposição. Os pedidos que ele já tem são ignorados. Isso captura qualquer pedido que um webhook tenha perdido.

Plugin ou webhooks: duas formas de conectar

As duas conexões enviam todos os pedidos pagos. A diferença está em quão bem cada pedido é ligado ao clique no anúncio que trouxe o comprador.

Você pode usar os dois ao mesmo tempo. O plugin salva o ID de visitante no pedido como metadado do pedido, e o payload do webhook o leva junto. O ROASaurus guarda cada pedido uma só vez, pelo ID do pedido do WooCommerce, então o plugin e o webhook nunca criam duas compras. O plugin também declara compatibilidade com o High-Performance Order Storage do WooCommerce.

Como um pedido do WooCommerce é associado ao clique no anúncio?

Uma plataforma de anúncios só consegue creditar uma compra a um anúncio quando consegue ligar os dois. O ROASaurus faz isso ligando o pedido ao visitante que clicou no anúncio, e esse visitante carrega os IDs de clique (como fbclid e ttclid) e os parâmetros UTM da chegada. Ele tenta estes métodos em ordem e para no primeiro que funciona:

1. O ID de visitante salvo no pedido. Só com o plugin. Essa é uma ligação exata.
2. A compra do navegador na página de agradecimento, que traz o mesmo ID de pedido. Só com o plugin.
3. Um e-mail em hash que o visitante informou antes no seu site, por exemplo em um formulário de popup do Klaviyo, Attentive ou Wisepops, ou por meio de uma chamada Identify.
4. O mesmo endereço IP e navegador, vistos de 3 horas antes até 15 minutos depois do pedido, mas só quando exatamente um visitante se encaixa. Em redes compartilhadas, como escritórios e operadoras de celular, vários visitantes costumam dividir um mesmo endereço IP, e nesse caso o ROASaurus não faz suposições.

O ROASaurus espera um pouco antes de enviar cada compra, para que o evento da página de agradecimento possa chegar primeiro. Se o pedido ainda não foi associado, ele tenta de novo na hora do envio. A página Orders mostra o resultado por pedido na coluna Matched by. Pedidos ligados pelo ID de visitante do plugin mostram cart, o mesmo rótulo que os pedidos do Shopify recebem.

Esses identificadores de clique aumentam a taxa de correspondência do Meta para o evento. Event Match Quality explica como o Meta os pontua.

Consentimento no WooCommerce

Cada loja no ROASaurus tem a configuração Respect visitor consent, que vem ativada por padrão. No WooCommerce, o script do ROASaurus lê a escolha do visitante na WP Consent API, que plugins de consentimento como Complianz e CookieYes preenchem. Ele também lê os banners Cookiebot, OneTrust, IAB TCF e o Google consent mode. Enquanto o visitante não aceitar os cookies de marketing, o script não define ID de visitante e não carrega pixels do navegador.

Quando um visitante recusa, o script não define ID de visitante, não guarda IDs de clique e não dispara pixels do navegador, e o plugin não guarda cookies de rastreamento no pedido. O pedido pago ainda é enviado do servidor às suas plataformas de anúncios conectadas, com dados do cliente em hash vindos do pedido e com o endereço IP e o navegador do pedido. Se a sua orientação jurídica diz que os eventos de compra também precisam de consentimento prévio, fale com o ROASaurus antes de ativar as compras server-side. A página de ajuda sobre consentimento traz os detalhes, e o artigo sobre Consent Mode v2 e GDPR traz o contexto jurídico.

Como configurar o rastreamento server-side no WooCommerce

Estes são os passos para o caminho com o plugin:

1. Adicione a loja

   No ROASaurus, vá a Add a store, escolha WooCommerce e informe o domínio que os seus clientes visitam.

2. Crie uma chave de API

   Abra Store settings e, em Orders API, clique em Create API key. Copie a chave na hora: ela é mostrada uma única vez, ao lado da chave da sua loja. O endpoint é o endereço que vem antes de /api/v1/orders nessa página.

3. Instale o plugin

   Baixe o plugin e envie o zip no WordPress em Plugins › Add New Plugin › Upload Plugin. Depois, ative-o.

4. Informe as chaves

   Em WooCommerce › ROASaurus, informe o endpoint, a chave da loja e a chave de API, e salve.

5. Conecte as suas plataformas de anúncios

   Em Tracking & platforms, use Connect with Facebook ou Add pixel para o Meta, o TikTok e os outros. Marque a opção de carregar também o pixel do navegador, para que a compra da página de agradecimento seja deduplicada com o evento do servidor.

6. Configure o consentimento e teste

   Bloqueie o script na sua ferramenta de consentimento até o visitante aceitar os cookies de marketing e faça um pedido de teste.

Sem o plugin, adicione a tag de script de Tracking & platforms a todas as páginas e depois crie o webhook. A aba Connection da sua loja mostra a URL do seu webhook. Mantenha-a privada: qualquer pessoa com a URL pode enviar pedidos para a sua loja.

WooCommerce › Settings › Advanced › Webhooks › Add webhook

Status        Active
Topic         Order updated
Delivery URL  (your webhook URL from the Connection tab)
Secret        (a secret of your choice; paste the same one in ROASaurus)
API version   WP REST API Integration v3

Para o backup, crie uma chave em WooCommerce › Settings › Advanced › REST API com acesso de leitura. Cole a consumer key e o secret na aba Connection, salve e clique em Test connection. Fetch orders now busca os pedidos pagos recentes na hora. A página de integração com o WooCommerce lista todas as opções em um só lugar.

Como testar o rastreamento server-side do WooCommerce?

Teste primeiro o lado do navegador, depois faça um pedido e acompanhe-o até as plataformas de anúncios.

• Abra a sua loja com ?roasaurus=connected no endereço. Um alerta confirma que o script está rodando. Com ?roasaurus=debug, o script registra 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 de teste. O pagamento na entrega é o mais rápido, porque o pedido fica em processing na hora.
• Na aba Connection, Last order received mostra a hora do pedido mais recente.
• No Event log, em Server deliveries, cada plataforma conectada recebe uma linha com o status sent e a resposta da plataforma.

Para 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. Remova-o quando terminar, porque o código serve só para testes. Se o plugin não consegue entregar um pedido, ele adiciona uma nota ao pedido no WooCommerce que começa com "ROASaurus: order not sent", seguida do erro.

Erros a evitar

• Usar o tópico Order created. Pedidos pagos por redirecionamento são criados como pending payment. O ROASaurus ignora pedidos não pagos, e nenhuma segunda mensagem "created" chega quando o pagamento entra. Use Order updated.
• Um segredo que não confere. O ROASaurus rejeita um envio cuja assinatura não confere com o segredo que ele tem. Depois de mais de cinco falhas seguidas, o WooCommerce desativa o webhook. Corrija o segredo, coloque o webhook de volta em Active e adicione a chave da REST API, para que os pedidos do intervalo sejam buscados.
• Duas ferramentas enviando o mesmo pixel. Se outro plugin também envia o seu pixel do Meta ou do TikTok, ele usa os próprios IDs de evento e a plataforma conta cada venda duas vezes. Desligue-o para esse pixel. Veja como evitar a contagem em duplicidade e eventos de compra duplicados.
• Esperar eventos de adição ao carrinho. No WooCommerce, o script rastreia visualizações de página por conta própria. Visualizações de produto e adições ao carrinho são detectadas automaticamente só no Shopify. Um desenvolvedor pode enviá-las com uma chamada de rastreamento tlq.
• Esperar conversões do Google Ads. O ROASaurus envia conversões de compra do Google Ads só a partir do checkout do Shopify. A partir do WooCommerce, ele envia compras ao Meta, TikTok, Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn e às outras plataformas de anúncios que você conectar.
• Transferências bancárias tardias. O Meta aceita eventos de servidor até 7 dias depois da hora do evento. O plugin envia o pedido com a data em que ele foi criado, então o Meta rejeita uma transferência confirmada mais de 7 dias depois do checkout. Os pedidos que chegam por webhook ou pela REST API usam a data de pagamento. Observe também que a página de agradecimento dispara a compra do navegador no checkout, antes de a transferência ser paga. Se o pagamento for confirmado mais de 48 horas depois, o Meta e o TikTok não conseguem unir as cópias do navegador e do servidor, e uma transferência que nunca é paga mantém a sua compra do navegador.

Quando os pedidos começam a fluir, os relatórios de atribuição mostram de quais campanhas e anúncios eles vieram.

Fontes

1. WooCommerce: Webhooks Documentation
2. WooCommerce REST API Documentation - WP REST API v3
3. WooCommerce: Order Statuses Documentation
4. WooCommerce: Cash on Delivery Documentation
5. Meta for Developers: Server Event Parameters

No ROASaurus

• Integração com o WooCommerce
• Ajuda: WooCommerce e sites personalizados
• Rastreamento server-side

Continue lendo