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 13 de mai. de 2026 Leitura de 4 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 canônicos

Use sempre estes nomes em minúsculo (snake_case). A tag faz a conversão automática para o nome de cada plataforma (Facebook, GA4, TikTok, Pinterest, Taboola).

Evento Quando disparar Campos recomendados
page_view Carregamento de página. Disparado automaticamente — não dispare manualmente —
view_item_list Visualização de listagem de produtos / categoria items
view_item Visualização de página de produto items, value, currency
search Usuário fez uma busca interna search_term
add_to_cart Produto adicionado ao carrinho items, value, currency
initiate_checkout Início do processo de checkout items, value, currency
add_payment_info Dados de pagamento preenchidos items, value, currency, payment_type
add_shipping_info Endereço/frete preenchido items, value, currency
purchase Compra finalizada (página de obrigado) transaction_id, items, value, currency, user_data
lead Cadastro / captura de lead / formulário enviado user_data

Importante: não use nomes como Purchase, InitiateCheckout ou ViewContent — esses são nomes do Facebook. O Track Combo converte os nomes canônicos para os nomes corretos de cada plataforma automaticamente.

Parâmetros aceitos

user_data

Identifica o usuário. Quanto mais campos enviar, melhor a qualidade do match no Facebook CAPI e nas demais APIs server-side. Email e telefone são hasheados em SHA-256 no servidor — envie em texto puro.

Campo Tipo Exemplo Descrição
email string cliente@exemplo.com Email do usuário
phone string 5511999999999 Telefone com DDI+DDD+número, apenas dígitos
first_name string João Primeiro nome
last_name string Silva Sobrenome
city string São Paulo Cidade
state string SP UF (2 letras)
country string BR País (ISO-2)
user_id string 12345 ID interno do cliente no seu sistema (external_id no Facebook)

tracking

Normalmente a tag preenche sozinha lendo cookies e URL. Só passe esses campos se quiser sobrescrever.

Campo Tipo
utm_source string
utm_medium string
utm_campaign string
utm_term string
utm_content string
fbc string
fbp string
tc_code string

custom_data (campos no nível raiz do objeto)

Campo Tipo Descrição
value number Valor monetário do evento. Deve ser número, não string
currency string Moeda em ISO-4217. Default: BRL quando value é informado
items array Produtos envolvidos. Ver schema "items[]" abaixo
content_ids array IDs dos produtos. Gerado automaticamente a partir de items[].item_id
quantity number Quantidade total. Gerada automaticamente a partir de items[].quantity
transaction_id string ID único da venda. Obrigatório no purchase
order_id string Alias de transaction_id
search_term string Termo buscado. Use no search
payment_type string credit_card, pix, boleto etc

items[]

Campo Tipo Descrição
item_id string SKU/ID do produto. Obrigatório — itens sem ID são descartados
item_name string Nome do produto
item_category string Categoria
price number Preço unitário
quantity number Quantidade

Aliases aceitos (a tag normaliza automaticamente): id → item_id, name → item_name, category → item_category.

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