Documentación · Trakvo

Quickstart

Estás a pocos minutos de tener eventos llegando a Meta CAPI, TikTok Events API y Google Ads. Trakvo corre server-side — no depende de cookies de terceros ni es bloqueado por AdBlock.

En 3 pasos

1. Pega el snippet en el <head> de tu sitio (o instala la app para Shopify).
2. Conecta tus pixels en el panel vía OAuth (Meta, TikTok, Google).
3. Dispara eventos vía POST /v1/events o deja que el snippet los detecte automáticamente.

Snippet universal

Pega antes de </head>. Funciona en cualquier tienda o landing page custom:

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

¿Dónde encontrar TU_SITE_ID? En el panel en Configuración → Site ID. Es un identificador único de 12 caracteres tipo trv_a7f4....

Conceptos básicos

Tres conceptos para entender antes de sumergirse:

Event ID compartido

Cada evento tiene un event_id único. El snippet client-side y el disparo server-side usan el mismo ID. La plataforma de destino deduplica al recibir — sin doble conteo.

First-party data

Trakvo recolecta datos en tu dominio (first-party), no en el dominio de Trakvo. Eso evita bloqueos de iOS, AdBlock y Safari ITP.

Hash de PII

Email, teléfono e identificadores personales se hashean vía SHA-256 antes de la transmisión. El dato en claro nunca sale de la base de Trakvo. LGPD y GDPR compliant.

Match Quality

Match Quality es el score (0-10) que Meta asigna a la calidad de los eventos que envías. Cuantos más campos PII enriquecidos, mejor el matching de la IA y menor tu CPA.

Trakvo enriquece automáticamente:

fbp y fbc (Facebook click cookies)
email y phone (hash SHA-256)
external_id (ID interno del cliente, hash)
fn / ln / city / state / zip / country (cuando están disponibles)
ip y user_agent (capturados server-side)

Clientes de Pro en adelante tienen Match Quality 9.4+ garantizado. Si el score baja, el panel alerta y nuestro equipo investiga.

Integraciones — Shopify

Instalación en 1 clic. Eventos estándar (PageView, ViewContent, AddToCart, InitiateCheckout, Purchase) detectados automáticamente.

Cómo instalar

Abre apps.shopify.com/trakvo.
Haz clic en Instalar y autoriza.
En el panel de Trakvo, conecta los pixels Meta/TikTok/Google.
Listo — los eventos empiezan a fluir en < 2 minutos.

Integraciones — WooCommerce

Plugin oficial vía repositorio de WordPress. Configuración mediante wizard guiado.

# Vía WP-CLI
wp plugin install trakvo --activate

O descarga el ZIP en downloads.trakvo.co/wp-plugin e instala vía la interfaz admin de WordPress.

Integraciones — Hotmart y Kiwify

Integración vía webhook nativo. Trakvo expone un endpoint listo que recibe los webhooks de Hotmart/Kiwify y los mapea automáticamente a eventos CAPI.

Configurar webhook

Copia tu URL única en Configuración → Integraciones → Hotmart.
Pégala en el panel de Hotmart en Configuración → Webhooks → Agregar.
Selecciona eventos: Purchase Approved, Refunded, Chargeback.

Integraciones — Cartpanda y Cakto

Mismo patrón: URL de webhook única generada en el panel. Pégala en el checkout y los eventos de conversión llegan mapeados al CAPI.

Integraciones — Sitio custom

Para tienda propia o landing page custom, usa el snippet universal + llamadas explícitas vía JavaScript.

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

Integraciones — Server-to-server

Para quienes ya tienen backend propio (Node, Ruby, Python, Go, .NET), dispara eventos directamente vía REST API. No necesitas el snippet client-side.

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

API — Autenticación

Todas las requests a la API exigen el header Authorization: Bearer TU_TOKEN. Genera tokens en Configuración → API → Tokens.

Buenas prácticas

Tokens por entorno: genera tokens separados para producción, staging y dev.
Nunca expongas tokens en código client-side ni en commits Git.
Rotación: rota tokens cada 90 días por política interna.

API — POST /v1/events

POST/v1/events

Dispara un evento de conversión para que se distribuya a los pixels conectados.

Body

Campo	Tipo	Obligatorio	Descripción
`event`	string	sí	Nombre del evento (ej: `Purchase`, `Lead`)
`event_id`	string	no	ID único para dedupe (generado automáticamente si se omite)
`value`	number	cond.	Valor monetario (obligatorio en Purchase)
`currency`	string	cond.	ISO 4217 (BRL, USD, EUR)
`user`	object	sí	Identidad del usuario (email, phone, ip, etc.)
`destinations`	array	no	Qué pixels disparar (default: todos)

Respuesta

{
  "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 el estado de entrega de un evento específico. Útil para debug.

API — Rate limits

Plan	Requests/s	Burst
Starter	50	100
Pro	500	1.000
Business	Personalizable	Personalizable

Cuando se excede, la API responde 429 Too Many Requests con header Retry-After.

API — Códigos de error

Status	Significado	Acción
`200`	Aceptado y encolado	—
`400`	Payload inválido	Verifica los campos obligatorios
`401`	Token inválido	Generar nuevo token
`429`	Rate limit	Esperar `Retry-After`
`500`	Error interno	Reintentar con backoff exponencial

SDK — JavaScript

# Instalar vía 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 vía 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

Configura URLs de webhook en Configuración → Webhooks. Trakvo notifica a tu servidor cuando:

El evento fue entregado con éxito.
El evento falló tras agotar los retries.
Match Quality cae por debajo del threshold configurado.
Un pixel se desconecta (token OAuth expirado).

Webhooks — Validar HMAC

Toda request de webhook incluye el header X-Trakvo-Signature. Valida con HMAC-SHA256 + tu 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

Si tu endpoint responde algo distinto de 2xx, Trakvo reintenta con backoff exponencial:

Intento 1: inmediato
Intento 2: 1 segundo
Intento 3: 5 segundos
Intento 4: 15 segundos
Intento 5: 60 segundos

Tras 5 intentos sin éxito, el evento va a la dead-letter queue — inspeccionable en el panel en Webhooks → Fallos.

Recursos — Event Catalog

Eventos estándar soportados nativamente (mapeados automáticamente a 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 y consent

Cada evento acepta un campo consent con la flag de consentimiento del usuario. Trakvo lo respeta end-to-end:

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

Recursos — Pixel Warmup

Un pixel nuevo no optimiza bien — falta histórico de eventos para que la IA de las plataformas aprenda. El Pixel Warmup envía eventos reales de otros pixels del mismo cliente, con jitter temporal, para darle un histórico inicial al pixel nuevo.

Disponible en el plan Pro (hasta 500 eventos/día) y Business (volumen custom).

Importante: solo se reutilizan eventos reales — nunca eventos sintéticos. Match Quality preservado. Volumen controlado para evitar detección como anomalía.

Changelog

Historial público de releases. RSS disponible en changelog.trakvo.co/rss.

v0.5 — En desarrollo

App nativa de Shopify (instalación 1 clic)
Pixel Warmup avanzado con scheduling
SDK PHP v2 con soporte para batch

v0.4 — Beta privada

CAPI server-side para Meta, TikTok, Google
Dashboard de eventos en tiempo real (SSE)
Webhooks con HMAC + idempotency

¿Te quedó alguna duda?

Habla con nosotros →

Seguridad y compliance →

Todo para integraren menos de una hora

Quickstart

En 3 pasos

Snippet universal

Conceptos básicos

Event ID compartido

First-party data

Hash de PII

Match Quality

Integraciones — Shopify

Cómo instalar

Integraciones — WooCommerce

Integraciones — Hotmart y Kiwify

Configurar webhook

Integraciones — Cartpanda y Cakto

Integraciones — Sitio custom

Integraciones — Server-to-server

API — Autenticación

Buenas prácticas

API — POST /v1/events

Body

Respuesta

API — GET /v1/events/:id

API — Rate limits

API — Códigos de error

SDK — JavaScript

SDK — PHP

Webhooks — Configurar

Webhooks — Validar HMAC

Webhooks — Retry policy

Recursos — Event Catalog

Recursos — LGPD y consent

Recursos — Pixel Warmup

Changelog

v0.5 — En desarrollo

v0.4 — Beta privada

Todo para integrar
en menos de una hora