Entrar Começar grátis
/
📦 Containers

Disparar Eventos Customizados via JavaScript

API window.tcData.executeEvent — dispare eventos manualmente em sites com código próprio

Atualizado em 20 de mai. de 2026 Leitura de 3 min

Esta página descreve como disparar eventos do Track Combo a partir do código do seu site — útil quando você usa uma estrutura própria (sem integração nativa) e precisa controlar manualmente quando cada evento é enviado.

A documentação foi escrita para ser consumida tanto por desenvolvedores quanto por IAs assistentes que geram o código para você. Para gerar o código de um evento específico, cole esta página inteira no seu prompt e descreva qual evento quer disparar e em que contexto (ex.: "ao clicar no botão de checkout").

Pré-requisitos

  • Tag Web instalada em todas as páginas do site, dentro do <head>
  • Container ativo no Track Combo

A tag expõe a API em window.tcData. Para verificar, abra o Console do navegador (F12) e rode:

console.log(window.tcData);

Se retornar um objeto, a tag está carregada.

API: window.tcData.executeEvent()

Função pública para disparar um evento. Aceita um único objeto.

window.tcData.executeEvent({
  event: 'initiate_checkout',      // obrigatório — nome canônico
  event_id: 'opcional',            // opcional — gerado automaticamente se omitido
  user_data: { email: '...' },     // opcional
  tracking: { utm_source: '...' }, // opcional (a tag já preenche sozinha)
  value: 197.00,                   // demais campos viram custom_data
  currency: 'BRL',
  items: [/* ... */]
});

Campos reservados do objeto

Campo Tipo Obrigatório Descrição
event string Sim Nome canônico do evento (ver tabela "Eventos canônicos")
event_id string Não ID único para deduplicação entre Web e CAPI. Gerado automaticamente se omitido
user_data object Não Dados do usuário (email, telefone etc)
tracking object Não Dados de tráfego (UTMs, fbc, fbp). A tag já preenche; só sobrescreva se necessário
custom_event boolean Não Se true, não renomeia o evento para o nome específico de cada pixel. Use apenas para eventos não-canônicos

Qualquer outro campo passado no objeto é enviado automaticamente em custom_data (value, currency, items, transaction_id, search_term etc).

Eventos e parâmetros aceitos

A lista canônica de eventos (purchase, lead, add_to_cart, initiate_checkout…) e todos os parâmetros disponíveis (user_data, tracking, custom_data, items[]) está na referência dedicada:

→ Eventos e Parâmetros — Referência

Use sempre os nomes canônicos em snake_case (purchase, não Purchase). A tag converte automaticamente para o nome de cada plataforma (Facebook, GA4, TikTok, Pinterest, Taboola).

Helper: aguardar a tag carregar

A tag carrega de forma assíncrona. Para evitar erro tcData is undefined, use sempre este helper:

function dispararEvento(params) {
  if (window.tcData && typeof window.tcData.executeEvent === 'function') {
    window.tcData.executeEvent(params);
  } else {
    setTimeout(function() { dispararEvento(params); }, 100);
  }
}

Use dispararEvento(...) no lugar de window.tcData.executeEvent(...) em todos os exemplos abaixo.

Receitas por evento

Copie e cole. Substitua os valores entre <...> pelos dados reais.

view_item

dispararEvento({
  event: 'view_item',
  value: 197.00,
  currency: 'BRL',
  items: [
    { item_id: 'SKU-123', item_name: 'Curso X', item_category: 'cursos', price: 197.00 }
  ]
});

view_item_list

dispararEvento({
  event: 'view_item_list',
  items: [
    { item_id: 'SKU-1', item_name: 'Produto A', price: 100 },
    { item_id: 'SKU-2', item_name: 'Produto B', price: 200 }
  ]
});

dispararEvento({
  event: 'search',
  search_term: 'tênis branco'
});

add_to_cart

dispararEvento({
  event: 'add_to_cart',
  value: 197.00,
  currency: 'BRL',
  items: [
    { item_id: 'SKU-123', item_name: 'Curso X', price: 197.00, quantity: 1 }
  ]
});

initiate_checkout

dispararEvento({
  event: 'initiate_checkout',
  value: 197.00,
  currency: 'BRL',
  user_data: {
    email: 'cliente@exemplo.com'
  },
  items: [
    { item_id: 'SKU-123', item_name: 'Curso X', price: 197.00, quantity: 1 }
  ]
});

add_payment_info

dispararEvento({
  event: 'add_payment_info',
  value: 197.00,
  currency: 'BRL',
  payment_type: 'credit_card',
  items: [
    { item_id: 'SKU-123', item_name: 'Curso X', price: 197.00, quantity: 1 }
  ]
});

add_shipping_info

dispararEvento({
  event: 'add_shipping_info',
  value: 197.00,
  currency: 'BRL',
  items: [
    { item_id: 'SKU-123', item_name: 'Curso X', price: 197.00, quantity: 1 }
  ]
});

purchase

dispararEvento({
  event: 'purchase',
  transaction_id: 'PEDIDO-9876',
  value: 197.00,
  currency: 'BRL',
  user_data: {
    email: 'cliente@exemplo.com',
    phone: '5511999999999',
    first_name: 'João',
    last_name: 'Silva',
    city: 'São Paulo',
    state: 'SP',
    country: 'BR'
  },
  items: [
    { item_id: 'SKU-123', item_name: 'Curso X', price: 197.00, quantity: 1 }
  ]
});

lead

dispararEvento({
  event: 'lead',
  user_data: {
    email: 'lead@exemplo.com',
    phone: '5511999999999',
    first_name: 'Maria'
  }
});

Exemplos completos no HTML

Botão de checkout

<button id="btn-checkout">Finalizar compra</button>

<script>
document.getElementById('btn-checkout').addEventListener('click', function() {
  dispararEvento({
    event: 'initiate_checkout',
    value: 197.00,
    currency: 'BRL',
    items: [
      { item_id: 'SKU-123', item_name: 'Curso X', price: 197.00, quantity: 1 }
    ]
  });
});
</script>

Formulário de captura (lead)

<form id="form-lead">
  <input name="email" type="email" required>
  <input name="nome" type="text" required>
  <input name="telefone" type="tel">
  <button type="submit">Quero saber mais</button>
</form>

<script>
document.getElementById('form-lead').addEventListener('submit', function(e) {
  var data = new FormData(e.target);
  dispararEvento({
    event: 'lead',
    user_data: {
      email: data.get('email'),
      first_name: data.get('nome'),
      phone: data.get('telefone')
    }
  });
});
</script>

Página de obrigado (purchase)

Preencha os valores no servidor antes de renderizar a página. Exemplo com placeholders genéricos:

<script>
dispararEvento({
  event: 'purchase',
  transaction_id: '<ID_DA_VENDA>',
  value: <VALOR_TOTAL>,
  currency: 'BRL',
  user_data: {
    email: '<EMAIL_DO_CLIENTE>',
    phone: '<TELEFONE_DO_CLIENTE>',
    first_name: '<PRIMEIRO_NOME>',
    last_name: '<SOBRENOME>'
  },
  items: [
    { item_id: '<SKU>', item_name: '<NOME>', price: <PRECO>, quantity: <QTD> }
  ]
});
</script>

Validar o disparo

  1. Abra a página no navegador
  2. Pressione F12 e vá para a aba Console
  3. Rode window.tcData.events para ver o histórico de eventos disparados na sessão
  4. Adicione ?tc_debug=1 à URL para abrir o debug visual flutuante na página
  5. No painel do Track Combo, acesse Container → Eventos e confira se o evento chegou no servidor

Erros comuns

Cannot read properties of undefined (reading 'executeEvent') A tag ainda não carregou quando o código rodou. Use o helper dispararEvento() acima.

Evento aparece duplicado no Facebook / GA4 Você está disparando via JS e sua plataforma já dispara o mesmo evento via webhook. Mantenha apenas uma origem ou compartilhe o mesmo event_id entre Web e servidor.

Usei Purchase e nada aconteceu Os nomes canônicos são sempre em minúsculo e em snake_case. Use purchase, não Purchase. A tag converte para o nome correto de cada pixel.

Items não aparecem no evento Confirme que items é um array (não objeto) e que cada item tem item_id (ou o alias id). Itens sem ID são descartados.

Valor está zerado value deve ser número (197.00), não string ("R$ 197,00" ou "197,00"). Converta antes de passar:

var valor = Number(stringPreco.replace(/[^\d,]/g, '').replace(',', '.'));

Email/telefone aparecem hasheados nos logs Isso é esperado — o hash SHA-256 é aplicado no servidor antes do envio aos pixels. No payload original do executeEvent, envie em texto puro.

Ver também

javascripteventoscustomapiexecuteEventtcDatainitiate_checkoutpurchaseleaddesenvolvedor

Artigos relacionados