Rastreamento de conversões WooCommerce no OpenAI Ads

Como o rastreamento de compras do WooCommerce deve funcionar com o OpenAI Ads, incluindo IDs de pedido, valores de conversão, eventos no navegador e no servidor, consentimento e a configuração planejada do PixelBridge.

Última atualização: 8 de setembro de 2026. Escrito por PixelBridge team.

O rastreamento de compras do WooCommerce para o OpenAI Ads deve disparar um evento purchase depois que o pedido for confirmado, não quando o comprador abre o checkout ou adiciona um produto ao carrinho. O evento deve carregar um identificador de pedido, um valor de conversão e a moeda quando isso for permitido, e um ID de evento compartilhado se a mesma conversão também for enviada pela Conversions API. O consentimento de medição precisa ser concedido antes que qualquer evento do navegador ou do servidor saia do site. O PixelBridge foi pensado para fazer isso a partir do WordPress. O hook do plugin ainda não está disponível.

Para que serve esta integração

O WooCommerce já registra pedidos, totais, dados do cliente e status do pedido. A medição do OpenAI Ads precisa de um evento de conversão que represente essa compra, para que os relatórios de anúncios possam conectar um pedido pago ou confirmado à atividade da campanha.

PixelBridge é um plugin WordPress independente para essa camada de medição. Não é um produto oficial da OpenAI nem do WooCommerce, e não cria campanhas. O conector WooCommerce é uma das primeiras integrações planejadas. Até ser lançado, nada nesta página é um recurso funcional do plugin.

Para a configuração da loja em si, comece pela documentação oficial do WooCommerce. Para o contrato de medição publicitária, use a documentação do Measurement Pixel da OpenAI e a documentação da Conversions API. Nomes de eventos e campos obrigatórios podem mudar. Confirme-os na documentação oficial da OpenAI antes de tratar um payload como definitivo.

Como o rastreamento de compras deve funcionar

Um evento de compra útil é uma ação comercial concluída. No WooCommerce isso costuma significar que um pedido existe e chegou a um status que a sua loja trata como real, como processing ou completed, dependendo do método de pagamento.

A sequência prevista é:

  1. O comprador conclui o checkout.
  2. O WooCommerce cria um pedido e atribui um identificador.
  3. Se o consentimento de medição for concedido, um evento purchase no navegador pode disparar no estado de pedido recebido ou de agradecimento.
  4. Se a Conversions API estiver ativa, o WordPress pode enviar um evento de servidor correspondente depois que o pedido for confirmado em PHP.
  5. Os dois payloads compartilham um ID de evento para que a medição do OpenAI Ads possa tratá-los como uma conversão.

Não dispare purchase em:

  • Visualizações de página de produto
  • Adicionar ao carrinho
  • Carregamento da página de checkout
  • Pagamentos que falharam ou foram cancelados
  • Pedidos rascunho criados no admin que nunca foram feitos por um cliente

Uma visualização de página em uma URL de produto ou carrinho ainda é um evento page_viewed se você mede visualizações de página. Não é uma compra. Veja eventos de conversão para a diferença entre esses tipos de evento.

Identificadores de pedido

Todo evento de compra precisa de um identificador de pedido estável. O WooCommerce já tem um: o ID do pedido e, muitas vezes, um número de pedido separado se você usa um plugin de numeração personalizada.

O identificador é útil para três tarefas:

  • Depuração: você pode casar um evento de medição com um pedido WooCommerce.
  • Deduplicação: eventos do navegador e do servidor podem apontar para o mesmo pedido.
  • Operações posteriores: se o tratamento de reembolso for adicionado, o pedido original é a chave de junção.

Use o identificador que não muda depois do checkout. Se a loja mostra um número de pedido formatado aos clientes, decida se a medição usa o ID interno ou o número visível ao cliente e mantenha essa escolha consistente nos eventos do navegador e do servidor.

Não gere um ID aleatório novo na página de agradecimento se um evento de servidor também for enviar o ID do pedido. Os dois lados deixariam de parecer a mesma conversão.

Valores de conversão

Uma conversão de compra é bem mais útil quando inclui um valor e uma moeda. Fontes típicas no WooCommerce são o total do pedido e a moeda da loja.

Planeje o valor com cuidado:

  • Decida se o valor inclui imposto, frete e taxas.
  • Use a mesma regra nos eventos do navegador e do servidor.
  • Envie a moeda da loja, não um fallback hardcoded, a menos que o próprio pedido esteja em outra moeda.
  • Não envie um valor para um pedido não pago ou que falhou.

Valor não é a mesma coisa que receita nos relatórios da loja. Os totais do WooCommerce podem incluir descontos, reembolsos posteriores ou ajustes de várias moedas. A medição do OpenAI Ads só vê o que você envia. Mantenha o mapeamento simples e documente-o para a equipe.

Se o consentimento ou a política de privacidade não permitir enviar o valor, omita-o em vez de chutar. Um evento de compra sem valor ainda é uma conversão. Um valor inventado é pior do que nenhum valor.

Eventos no navegador

O evento no navegador é a chamada purchase no cliente depois que o pixel carregou. No WooCommerce, o lugar natural é a página de pedido recebido, depois que o WooCommerce renderizou um pedido bem-sucedido.

Um evento de navegador planejado deve esperar:

  1. O OpenAI Ads Pixel inicializar com o Pixel ID.
  2. O consentimento de medição, se o site exigir.
  3. Prova de que esta página pertence a um pedido real, não a um template genérico de agradecimento sem objeto de pedido.

Páginas de agradecimento são fáceis de errar. Alguns temas carregam o mesmo template para pagamentos que falharam. Alguns plugins de checkout substituem o endpoint nativo de pedido recebido. Alguns caches servem uma página de agradecimento sem contexto de pedido. A integração deve ler o objeto de pedido do WooCommerce, não assumir que qualquer visita a /checkout/order-received/ é uma compra.

Eventos no navegador podem ser bloqueados por extensões, navegadores restritos, regras de Content Security Policy ou um banner de consentimento que nunca concede a medição. Por isso um evento de servidor faz parte do desenho. É um complemento, não um jeito de ignorar o consentimento. Veja o guia OpenAI Ads Pixel para WordPress para como o pixel em si deve carregar.

Eventos no servidor

A Conversions API envia a mesma conversão a partir do WordPress depois que o pedido é confirmado em PHP. Isso é útil quando a página de agradecimento nunca carrega, o comprador fecha a aba ou o pixel no navegador é bloqueado.

Um evento de servidor WooCommerce planejado deve disparar a partir de um hook do ciclo de vida do pedido, não de um callback genérico de wp_footer. O hook deve representar um pedido confirmado. Métodos de pagamento diferem: alguns marcam o pedido como processing imediatamente, outros esperam um webhook. A integração deve seguir o status que significa "esta compra é real" para aquele gateway.

Eventos de servidor ainda precisam de:

  • O Pixel ID
  • O nome do evento (purchase)
  • O identificador do pedido
  • Valor e moeda quando permitido
  • O ID de evento compartilhado
  • Dados de atribuição como oppref quando disponíveis
  • A mesma regra de consentimento do evento no navegador

A conexão da Conversions API no plugin faz parte do conjunto de recursos Pro planejado e ainda não está disponível publicamente. Leia Conversions API e a documentação oficial da Conversions API para o contrato atual dos campos.

Deduplicação

Se você envia um evento no navegador e um evento no servidor para um pedido WooCommerce, a medição do OpenAI Ads precisa de um jeito de ver que são a mesma ação. Isso é um ID de evento compartilhado.

O modelo planejado é:

  1. O WordPress gera ou armazena um ID de evento para o pedido.
  2. O evento no navegador inclui esse ID.
  3. O evento no servidor inclui o mesmo ID.
  4. Os dois eventos usam o mesmo Pixel ID e o mesmo nome de evento.

Sem esse ID compartilhado, uma página de agradecimento bem-sucedida mais um hook de servidor bem-sucedido pode parecer duas compras. Com ele, um evento no navegador bloqueado ainda pode deixar uma conversão válida no servidor.

Não reutilize um ID de evento em pedidos diferentes. Não crie um ID novo a cada atualização da página de agradecimento. O pedido é a unidade de conversão.

Consentimento

O rastreamento de compras ainda é medição publicitária. Se a sua configuração jurídica trata isso como opcional, a integração WooCommerce não deve carregar o pixel, disparar uma compra no navegador nem enviar um evento da Conversions API até a permissão necessária existir.

Consentimento não é uma configuração do WooCommerce. Costuma vir de um banner de cookies ou de um plugin de consentimento. O PixelBridge foi pensado para ler esse estado em vez de adicionar um segundo banner. Veja consentimento.

Algumas armadilhas específicas do WooCommerce:

  • O checkout pode concluir enquanto o banner ainda não foi respondido.
  • Algumas lojas concedem consentimento de estatísticas, mas não de marketing ou medição.
  • Eventos de servidor devem seguir a mesma permissão dos eventos no navegador. Um hook PHP não é uma brecha.

Esta página é orientação de implementação, não aconselhamento jurídico.

Reembolsos

O WooCommerce pode reembolsar um pedido no todo ou em parte. Eventos de reembolso ou ajuste do OpenAI Ads ainda não são suportados pelo PixelBridge.

Até existir suporte a reembolso:

  • Não envie um segundo purchase com valor negativo como gambiarra.
  • Não apague o evento original de compra dos seus próprios logs e assuma que os relatórios de anúncios vão acompanhar.
  • Trate a compra original como a conversão que foi enviada e espere um mapeamento de reembolso documentado.

Se eventos de reembolso forem adicionados depois, devem referenciar o identificador original do pedido e seguir as regras oficiais de medição do OpenAI Ads. Esse trabalho não foi lançado.

Configuração planejada

Quando a integração WooCommerce for lançada, o caminho previsto no WordPress é:

  1. Instale o PixelBridge quando o plugin estiver disponível. A listagem pública ainda não está no ar. Veja instalação.
  2. Informe o Pixel ID do OpenAI Ads.
  3. Ative o rastreamento de compras do WooCommerce nas configurações do plugin.
  4. Escolha o status de pedido que deve contar como compra para os seus métodos de pagamento.
  5. Decida se eventos no navegador, no servidor, ou os dois devem disparar.
  6. Confirme as regras de consentimento antes que qualquer evento seja permitido.
  7. Faça um pedido de teste em um site de staging e confira o diagnóstico.

Até isso ser lançado, não cole JavaScript de compra em um template de agradecimento do WooCommerce e assuma que combina com o plugin futuro. Um teste manual temporário é possível, mas não é a integração suportada.

Resolução de problemas

Se uma compra WooCommerce não aparecer na medição do OpenAI Ads, percorra o problema nesta ordem:

  1. Confirme que a integração realmente foi lançada. Se esta página ainda diz em breve, o hook não está no ar.
  2. Confirme que o Pixel ID corresponde à conta de anúncios.
  3. Confirme que o comprador chegou a um pedido confirmado, não a uma tela de checkout ou de pagamento que falhou.
  4. Conceda o consentimento de medição e tente de novo.
  5. Verifique se a página de agradecimento está em cache sem contexto de pedido.
  6. Verifique se um plugin de checkout personalizado substituiu o fluxo nativo de pedido recebido.
  7. Se eventos no navegador e no servidor estão planejados, confirme que eles compartilham um ID de evento.
  8. Inspecione o diagnóstico e o guia de resolução de problemas.

Um valor oppref ausente nem sempre significa que o rastreamento falhou. Pode significar que a visita não veio de um anúncio da OpenAI. Veja atribuição oppref.

Relacionado

Guias relacionados