Meta Pixel no VTEX IO: Como Implementar o Facebook Pixel Corretamente

O Meta Pixel (antigo Facebook Pixel) é a base do rastreamento de campanhas no Meta Ads — remarketing, lookalike audiences e otimização de conversão dependem dele. Em lojas VTEX IO, a implementação incorreta é o cenário mais comum: pixel instalado, mas com eventos faltando, compras não rastreadas e dados de ROAS que não batem com o back-office.

Este guia cobre a implementação completa — Pixel client-side via GTM + Conversions API server-side — com deduplicação correta e rastreamento de compra via Order Hook da VTEX.

O que é o Meta Pixel e por que ele importa no e-commerce

O Meta Pixel é um script JavaScript que rastreia o comportamento dos visitantes no seu site e envia esses dados para o Meta Ads Manager. Com ele você consegue:

• Criar públicos de remarketing (visitantes de produto, abandonadores de carrinho)
• Otimizar campanhas com base em conversões reais (purchase, add to cart)
• Criar lookalike audiences a partir dos seus compradores
• Medir o ROAS real das campanhas de Meta Ads

Sem um Pixel implementado corretamente, suas campanhas de Meta Ads são otimizadas às cegas.

Três formas de instalar o Meta Pixel no VTEX IO

A arquitetura recomendada é a camada dupla: Pixel client-side via GTM para eventos de funil + Conversions API via Order Hook para o evento de compra no servidor.

Eventos obrigatórios no Meta Pixel para e-commerce

O Meta Ads usa eventos padrão para otimizar campanhas. Para e-commerce, os obrigatórios são:

Implementação via GTM no VTEX IO

1. Instalar o GTM no VTEX IO

Se o GTM ainda não estiver configurado, instale o Pixel App do Google Tag Manager:

vtex install gtm.store-gtm@0.x

Configure o ID do container (GTM-XXXXXXX) nas configurações do app no admin VTEX.

2. Tag do Meta Pixel no GTM

No GTM, crie uma tag de HTML personalizado com o código base do Pixel:

<!-- Meta Pixel Code -->
<script>
  !function(f,b,e,v,n,t,s){
    if(f.fbq)return;n=f.fbq=function(){n.callMethod?
    n.callMethod.apply(n,arguments):n.queue.push(arguments)};
    if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
    n.queue=[];t=b.createElement(e);t.async=!0;
    t.src=v;s=b.getElementsByTagName(e)[0];
    s.parentNode.insertBefore(t,s)
  }(window, document,'script','https://connect.facebook.net/en_US/fbevents.js');
  
  fbq('init', '{{Pixel ID}}');
  fbq('track', 'PageView');
</script>

Trigger: All Pages.

Crie uma variável de constante chamada Pixel ID com o ID do seu pixel do Meta.

3. Tag de ViewContent (página de produto)

<script>
  fbq('track', 'ViewContent', {
    content_ids: ['{{dlv - product id}}'],
    content_name: '{{dlv - product name}}',
    content_type: 'product',
    value: {{dlv - product price}},
    currency: 'BRL'
  });
</script>

Trigger: evento customizado productView no dataLayer (populado pelo Pixel App de analytics do VTEX IO).

4. Tag de AddToCart

<script>
  fbq('track', 'AddToCart', {
    content_ids: ['{{dlv - product id}}'],
    content_name: '{{dlv - product name}}',
    content_type: 'product',
    value: {{dlv - product price}},
    currency: 'BRL'
  });
</script>

Trigger: evento addToCart no dataLayer.

5. Tag de InitiateCheckout

<script>
  fbq('track', 'InitiateCheckout', {
    num_items: {{dlv - cart quantity}},
    value: {{dlv - cart total}},
    currency: 'BRL'
  });
</script>

Trigger: evento checkout no dataLayer ou URL do checkout VTEX.

Conversions API (CAPI): rastreamento server-side

A Conversions API do Meta é o equivalente ao Measurement Protocol do GA4 — envia eventos diretamente do servidor para o Meta, sem passar pelo browser. É fundamental para o evento de compra.

Por que CAPI é obrigatório para Purchase

• Adblockers bloqueiam o script do Pixel no browser
• iOS 14.5+ limita rastreamento client-side de forma significativa
• O cliente pode fechar o browser antes do script de confirmação executar
• Resultado: até 30% das compras não são registradas só com client-side

Com CAPI via Order Hook, o evento de Purchase é enviado pelo servidor VTEX imediatamente após a confirmação do pedido — independente do browser do cliente.

Implementação CAPI via Order Hook VTEX

// vtex.io/service-node/handlers/orderHook.ts
import axios from "axios";

const META_PIXEL_ID = process.env.META_PIXEL_ID!;
const META_ACCESS_TOKEN = process.env.META_ACCESS_TOKEN!;
const CAPI_URL = `https://graph.facebook.com/v19.0/${META_PIXEL_ID}/events`;

interface VTEXOrder {
  orderId: string;
  value: number;
  items: Array<{ id: string; name: string; price: number; quantity: number }>;
  clientProfileData: { email: string; phone: string };
}

function hashSHA256(value: string): string {
  const crypto = require("crypto");
  return crypto.createHash("sha256").update(value.trim().toLowerCase()).digest("hex");
}

async function sendPurchaseEventToMeta(order: VTEXOrder) {
  const eventId = `vtex_${order.orderId}`;
  const orderValueInBRL = order.value / 100; // VTEX usa centavos

  const payload = {
    data: [
      {
        event_name: "Purchase",
        event_time: Math.floor(Date.now() / 1000),
        event_id: eventId, // para deduplicação com o client-side
        action_source: "website",
        user_data: {
          em: hashSHA256(order.clientProfileData.email),
          ph: hashSHA256(order.clientProfileData.phone.replace(/\D/g, "")),
        },
        custom_data: {
          currency: "BRL",
          value: orderValueInBRL,
          order_id: order.orderId,
          content_type: "product",
          contents: order.items.map((item) => ({
            id: item.id,
            quantity: item.quantity,
            item_price: item.price / 100,
          })),
        },
      },
    ],
    test_event_code: process.env.META_TEST_EVENT_CODE, // remover em produção
  };

  await axios.post(CAPI_URL, payload, {
    params: { access_token: META_ACCESS_TOKEN },
  });
}

Deduplicação: evitar evento Purchase duplo

O maior risco ao usar CAPI é disparar o Purchase duas vezes — uma via Pixel client-side e outra via CAPI. O Meta usa o campo event_id para deduplicar.

Client-side (GTM):

<script>
  // Na tag de Purchase client-side, inclua o mesmo event_id
  fbq('track', 'Purchase', {
    value: {{dlv - purchase revenue}},
    currency: 'BRL',
    content_ids: {{dlv - purchase item ids}},
    content_type: 'product',
    order_id: '{{dlv - transaction id}}'
  }, {
    eventID: 'vtex_{{dlv - transaction id}}' // mesmo formato do server-side
  });
</script>

O Meta compara os campos event_id + event_name + janela de 48h. Se forem iguais, conta como um único evento.

Validação no Meta Events Manager

Após a implementação, valide os eventos no Meta Events Manager (business.facebook.com → Events Manager):

1. Test Events: use o Test Event Code no CAPI para ver eventos em tempo real
2. Event Match Quality: score de qualidade dos dados (mire em 7+/10)
3. Deduplication: verifique se o "Deduplicated Events" está próximo de zero
4. Purchase comparison: compare Purchase no Events Manager com pedidos no VTEX Admin

Checklist de validação

• PageView disparando em todas as páginas
• ViewContent disparando em PDPs com content_ids correto
• AddToCart disparando com valor correto
• InitiateCheckout disparando na entrada do checkout
• Purchase client-side com eventID igual ao server-side
• Purchase CAPI chegando via Order Hook (verificar nos Test Events)
• Nenhum evento duplicado no Events Manager
• Event Match Quality acima de 6/10

Erros comuns na implementação do Meta Pixel no VTEX

Erro 1: Pixel instalado duas vezes

Lojas que têm o Pixel App nativo do VTEX e o GTM com a tag do Pixel disparam o PageView e os eventos de funil em duplicata. Desative um dos dois — recomendo manter apenas o GTM para controle total.

Erro 2: Valor de Purchase em centavos

O VTEX armazena valores em centavos (1990 = R$ 19,90). A CAPI espera o valor em reais (19.90). Dividir por 100 é obrigatório.

Erro 3: event_id diferente entre client e server

Se o eventID do Pixel client-side não bater exatamente com o event_id enviado pela CAPI, ambos os eventos são contabilizados — dobrando as conversões reportadas.

Erro 4: Dados PII sem hash

O campo em (email) e ph (telefone) obrigatoriamente precisam ser enviados com hash SHA-256. Enviar em texto puro viola as políticas do Meta e pode resultar em suspensão da conta.

Erro 5: Ignorar iOS 14.5+

Após iOS 14.5, eventos client-side de usuários iOS são limitados pelo ATT (App Tracking Transparency). A CAPI é a única forma de recuperar esses dados. Verificações de cobertura devem comparar o total de pedidos no VTEX com o total de Purchase events no Meta.

Arquitetura completa de rastreamento avançado para VTEX

A implementação ideal combina três camadas:

Browser do usuário
  └── Pixel App VTEX IO (dataLayer)
        └── GTM client-side
              ├── Meta Pixel (ViewContent, AddToCart, InitiateCheckout)
              ├── GA4 (funil completo)
              └── Google Ads (conversão de checkout)

Servidor VTEX (Order Hook)
  └── Measurement Protocol → GA4 (Purchase server-side)
  └── CAPI → Meta Pixel (Purchase server-side)

Esta arquitetura garante:

• 100% dos pedidos rastreados no GA4 e no Meta
• Dados de ROAS consistentes com o back-office
• Públicos de remarketing completos (incluindo compradores iOS)
• Uma única fonte de verdade: o Order Hook

Implementei essa arquitetura em projetos como Motorola, Samsung e Dexco. Se você precisa de rastreamento avançado na sua loja VTEX, fale comigo.