Documentação · Trakvo

Quickstart

Você está a poucos minutos de ter eventos chegando no Meta CAPI, TikTok Events API e Google Ads. O Trakvo roda server-side — não depende de cookies de terceiros nem é bloqueado por AdBlock.

Em 3 passos

1. Cole o snippet no <head> do seu site (ou instale o app pra Shopify).
2. Conecte seus pixels no painel via OAuth (Meta, TikTok, Google).
3. Dispare eventos via POST /v1/events ou deixe o snippet detectar automaticamente.

Snippet universal

Cole antes de </head>. Funciona em qualquer loja ou landing page custom:

<!-- Trakvo -->
<script src="https://cdn.trakvo.co/t.js" data-site="SEU_SITE_ID" async></script>

Onde encontrar SEU_SITE_ID? No painel em Configurações → Site ID. É um identificador único de 12 caracteres tipo trv_a7f4....

Conceitos básicos

Três conceitos pra entender antes de mergulhar:

Event ID compartilhado

Cada evento tem um event_id único. O snippet client-side e o disparo server-side usam o mesmo ID. A plataforma de destino deduplica no recebimento — sem dupla contagem.

First-party data

O Trakvo coleta dados no seu domínio (first-party), não no domínio do Trakvo. Isso evita bloqueios de iOS, AdBlock e Safari ITP.

Hash de PII

Email, telefone e identificadores pessoais são hasheados via SHA-256 antes da transmissão. O dado em claro nunca sai do banco do Trakvo. LGPD e GDPR compliant.

Match Quality

Match Quality é o score (0-10) que o Meta atribui à qualidade dos eventos que você envia. Quanto mais campos PII enriquecidos, melhor o matching da IA e menor seu CPA.

O Trakvo enriquece automaticamente:

fbp e fbc (Facebook click cookies)
email e phone (hash SHA-256)
external_id (ID interno do cliente, hash)
fn / ln / city / state / zip / country (quando disponíveis)
ip e user_agent (capturados server-side)

Clientes do Pro em diante têm Match Quality 9.4+ garantido. Se o score cair, o painel alerta e nosso time investiga.

Integrações — Shopify

Instalação em 1 clique. Eventos padrão (PageView, ViewContent, AddToCart, InitiateCheckout, Purchase) detectados automaticamente.

Como instalar

Abra apps.shopify.com/trakvo.
Clique em Instalar e autorize.
No painel do Trakvo, conecte os pixels Meta/TikTok/Google.
Pronto — eventos começam a fluir em < 2 minutos.

Integrações — WooCommerce

Plugin oficial via repositório do WordPress. Configuração via wizard guiado.

# Via WP-CLI
wp plugin install trakvo --activate

Ou baixe o ZIP em downloads.trakvo.co/wp-plugin e instale via interface admin do WordPress.

Integrações — Hotmart e Kiwify

Integração via webhook nativo. O Trakvo expõe um endpoint pronto que recebe os webhooks da Hotmart/Kiwify e mapeia automaticamente pra eventos CAPI.

Configurar webhook

Copie sua URL única em Configurações → Integrações → Hotmart.
Cole no painel da Hotmart em Configurações → Webhooks → Adicionar.
Selecione eventos: Purchase Approved, Refunded, Chargeback.

Integrações — Cartpanda e Cakto

Mesmo padrão: URL de webhook única gerada no painel. Cole no checkout e os eventos de conversão chegam mapeados pro CAPI.

Integrações — Site custom

Pra loja própria ou landing page custom, use o snippet universal + chamadas explícitas via JavaScript.

// Disparar evento Purchase manualmente
window.trakvo("Purchase", {
  value: 99.90,
  currency: "BRL",
  order_id: "ORD-12345",
  email: "[email protected]"  // hasheado automaticamente
});

Integrações — Server-to-server

Pra quem já tem backend próprio (Node, Ruby, Python, Go, .NET), dispare eventos direto via REST API. Não precisa do snippet client-side.

curl -X POST https://{your-region}.api.trakvo.co/events \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Purchase",
    "value": 99.90,
    "currency": "BRL",
    "user": { "email_sha256": "..." }
  }'

API — Autenticação

Todas as requisições à API exigem header Authorization: Bearer SEU_TOKEN. Gere tokens em Configurações → API → Tokens.

Boas práticas

Tokens são por ambiente: gere separados pra produção, staging e dev.
Nunca exponha tokens em código client-side ou em commits Git.
Rotação: rotacione tokens a cada 90 dias por política interna.

API — POST /v1/events

POST/v1/events

Dispara um evento de conversão pra ser distribuído aos pixels conectados.

Body

Campo	Tipo	Obrigatório	Descrição
`event`	string	sim	Nome do evento (ex: `Purchase`, `Lead`)
`event_id`	string	não	ID único pra dedupe (gerado automaticamente se omitido)
`value`	number	cond.	Valor monetário (obrigatório em Purchase)
`currency`	string	cond.	ISO 4217 (BRL, USD, EUR)
`user`	object	sim	Identidade do usuário (email, phone, ip, etc.)
`destinations`	array	não	Quais pixels disparar (default: todos)

Resposta

{
  "event_id": "evt_a7f4b2c9...",
  "status": "queued",
  "latency_ms": 142,
  "match_quality": 9.4,
  "destinations": [
    { "id": "meta", "status": "sent", "http": 200 },
    { "id": "tiktok", "status": "sent", "http": 200 }
  ]
}

API — GET /v1/events/:id

GET/v1/events/:id

Consulta o status de entrega de um evento específico. Útil pra debug.

API — Rate limits

Plano	Requisições/s	Burst
Starter	50	100
Pro	500	1.000
Business	Customizável	Customizável

Quando excedido, a API responde 429 Too Many Requests com header Retry-After.

API — Códigos de erro

Status	Significado	Ação
`200`	Aceito e enfileirado	—
`400`	Payload inválido	Verifique campos obrigatórios
`401`	Token inválido	Gerar novo token
`429`	Rate limit	Aguardar `Retry-After`
`500`	Erro interno	Retentar com backoff exponencial

SDK — JavaScript

# Instalar via npm
npm install @trakvo/js

import { Trakvo } from "@trakvo/js";

const trakvo = new Trakvo({ token: process.env.TRAKVO_TOKEN });

await trakvo.track("Purchase", {
  value: 99.90,
  currency: "BRL",
  user: { email: "[email protected]" }
});

SDK — PHP

# Instalar via composer
composer require trakvo/php

use Trakvo\Client;

$trakvo = new Client($_ENV['TRAKVO_TOKEN']);

$trakvo->track('Purchase', [
  'value'     => 99.90,
  'currency'  => 'BRL',
  'user'      => ['email' => '[email protected]'],
]);

Webhooks — Configurar

Configure URLs de webhook em Configurações → Webhooks. O Trakvo notifica seu servidor quando:

Evento foi entregue com sucesso.
Evento falhou após esgotar retries.
Match Quality cai abaixo do threshold configurado.
Pixel desconecta (token OAuth expirou).

Webhooks — Validar HMAC

Toda requisição de webhook inclui header X-Trakvo-Signature. Valide com HMAC-SHA256 + sua webhook secret.

const crypto = require("crypto");

function validate(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(expected, signature);
}

Webhooks — Retry policy

Se seu endpoint responder algo diferente de 2xx, o Trakvo tenta de novo com backoff exponencial:

Tentativa 1: imediata
Tentativa 2: 1 segundo
Tentativa 3: 5 segundos
Tentativa 4: 15 segundos
Tentativa 5: 60 segundos

Após 5 tentativas sem sucesso, o evento vai pra dead-letter queue — inspecionável no painel em Webhooks → Falhas.

Recursos — Event Catalog

Eventos padrão suportados nativamente (mapeados automaticamente pra cada plataforma):

Evento	Meta	TikTok	Google
`PageView`	PageView	Pageview	page_view
`ViewContent`	ViewContent	ViewContent	view_item
`AddToCart`	AddToCart	AddToCart	add_to_cart
`InitiateCheckout`	InitiateCheckout	InitiateCheckout	begin_checkout
`AddPaymentInfo`	AddPaymentInfo	AddPaymentInfo	add_payment_info
`Purchase`	Purchase	CompletePayment	purchase
`Lead`	Lead	SubmitForm	generate_lead
`Subscribe`	Subscribe	Subscribe	—

Recursos — LGPD e consent

Cada evento aceita um campo consent com a flag de consentimento do usuário. O Trakvo respeita end-to-end:

trakvo.track("Purchase", {
  value: 99.90,
  consent: {
    marketing: true,
    analytics: true,
    timestamp: "2026-05-24T15:00:00Z"
  }
});

Recursos — Pixel Warmup

Pixel novo não otimiza bem — falta histórico de eventos pra IA das plataformas aprender. O Pixel Warmup envia eventos reais de outros pixels do mesmo cliente, com jitter temporal, pra dar histórico inicial ao pixel novo.

Disponível no plano Pro (até 500 eventos/dia) e Business (volume custom).

Importante: só eventos reais são reaproveitados — nunca eventos sintéticos. Match Quality preservado. Volume controlado pra evitar detecção como anomalia.

Changelog

Histórico público de releases. RSS disponível em changelog.trakvo.co/rss.

v0.5 — Em desenvolvimento

App nativo Shopify (instalação 1 clique)
Pixel Warmup avançado com scheduling
SDK PHP v2 com suporte a batch

v0.4 — Beta privado

CAPI server-side pra Meta, TikTok, Google
Dashboard de eventos em tempo real (SSE)
Webhooks com HMAC + idempotency

Ficou com dúvida?

Fale com a gente →

Segurança e compliance →

Tudo pra integrarem menos de uma hora

Quickstart

Em 3 passos

Snippet universal

Conceitos básicos

Event ID compartilhado

First-party data

Hash de PII

Match Quality

Integrações — Shopify

Como instalar

Integrações — WooCommerce

Integrações — Hotmart e Kiwify

Configurar webhook

Integrações — Cartpanda e Cakto

Integrações — Site custom

Integrações — Server-to-server

API — Autenticação

Boas práticas

API — POST /v1/events

Body

Resposta

API — GET /v1/events/:id

API — Rate limits

API — Códigos de erro

SDK — JavaScript

SDK — PHP

Webhooks — Configurar

Webhooks — Validar HMAC

Webhooks — Retry policy

Recursos — Event Catalog

Recursos — LGPD e consent

Recursos — Pixel Warmup

Changelog

v0.5 — Em desenvolvimento

v0.4 — Beta privado

Tudo pra integrar
em menos de uma hora