Runbook para dar de alta el Web Pixel de Relo en un cliente nuevo: wizard, snippet, verificación, evento de prueba y troubleshooting.

Pixel Setup — alta del pixel para un cliente nuevo

Runbook paso a paso para configurar el Relo Web Pixel en un cliente nuevo. Síguelo de principio a fin la primera vez; después usa la referencia rápida.

Audiencia y tiempos

Admins de Relo. Tiempo estimado: ~15 minutos por cliente (sin contar el deploy del snippet en el sitio del cliente, que lo hace su equipo). Para el catálogo completo de eventos y la API relo(), ve a Pixel (referencia).

Flujo end-to-end

Diagrama interactivo

Cargando diagrama…

Paso 1 — Crear el cliente (tracking type: pixel)

Abre el wizard de onboarding

Ve a Clients → New client (https://portal.relo.mx/v2/clients/new).

Paso 1 (Identity): elige el tracking type

Llena nombre, slug, moneda y timezone, y selecciona PIXEL como tracking type. Usa HYBRID solo si el cliente también tiene app móvil con AppsFlyer/MMP.

Paso 2 (Segments): configura el card "Pixel setup"

Aparece solo para clientes pixel/hybrid:

Allowed domains — dominios donde correrá el pixel, uno por línea (ej. quote.miami, www.quote.miami). Déjalo vacío para permitir todos.
Tracked events — qué eventos cuentan como conversión para este cliente. Default si no marcas nada: page_view, purchase, lead_submit.

Completa partners, comisiones y revisión

El paso 4 (Attribution field) se omite automáticamente para clientes solo-pixel — la atribución pixel es por click_id, no por campaign matching. En el paso 6 (Review) haz clic en Create everything: un solo POST /api/clients/onboard crea todo en una transacción atómica (cliente, segmentos, partners, comisiones, campañas y client_pixel_config).

Pantalla de éxito: snippet + verify

Para clientes pixel, la pantalla final muestra el install snippet con el client_id ya embebido y el botón Verify installation. No cierres esta pantalla hasta terminar el paso 3 de esta guía.

¿El cliente ya existe y solo falta el pixel? Edita su config en Client Settings (/v2/c/:slug/settings): el card Attribution & tracking tiene Allowed domains, Tracked events (botón Save pixel config) y el Install snippet listo para copiar. Si el cliente aún no es pixel, cambia su tracking type en Edit basics (/v2/c/:slug/setup-edit).

Paso 2 — Instalar el snippet en el sitio del cliente

Manda esto al equipo del cliente. El client_id numérico ya viene en el snippet que genera el portal (pantalla de éxito del wizard o Client Settings) — no lo escribas a mano, cópialo del portal.

<script>
(function(r,e,l,o){
  r.relo=r.relo||function(){(r.relo.q=r.relo.q||[]).push(arguments)};
  o=e.createElement('script');o.async=1;o.src=l;e.head.appendChild(o);
})(window,document,'https://p.relo.mx/r.js');
relo('init', {client_id: CLIENT_ID});
relo('page');
</script>

Dónde: en el <head> de todas las páginas del sitio. Carga async y nunca rompe la página host (todo va en try/catch).
Google Tag Manager: Custom HTML tag con el mismo código, trigger All Pages. En Client Settings el bloque del snippet incluye la variante GTM.
SPA (React/Next/etc.): el init va una sola vez en el HTML shell; llama relo('page') en cada cambio de ruta (el navegador no recarga). Ejemplos por framework en la guía de Integration.
Qué hace solo: al cargar dispara page_view y ~50 señales automáticas (scroll, clics, form_start/form_submit, engagement, fingerprint, web vitals…). Catálogo completo en Pixel (referencia).

Paso 3 — Verificar la instalación

En cuanto el snippet esté en producción (o staging con tráfico real):

Verify installation (wizard)

En la pantalla de éxito del wizard, haz clic en Verify installation. Llama GET /api/clients/:id/pixel/activity y responde:

✓ Pixel live — N event(s) in the last hour → listo.
No events yet → genera tráfico (visita el sitio) y reintenta en 1-2 minutos.
Couldn't check right now → backbone inalcanzable (checked: false); reintenta en unos minutos, no es un problema del snippet.

DevTools del navegador

En el sitio del cliente, abre DevTools:

Network: request a p.relo.mx/r.js con status 200 y requests a p.relo.mx/e con status 204.
Console: escribe relo — debe ser una función, no undefined.
Application → Cookies: deben existir _relo_did (device, 365d) y _relo_sid (sesión, ~30 min) en el dominio del cliente.

Live events en el portal

Abre Pixel Analytics (/v2/c/:slug/pixel-analytics) → tab Live events (solo admin). Es un stream en vivo: cada page_view debe aparecer en segundos. Es la forma más rápida de confirmar que los eventos llegan a ClickHouse.

Endpoint de soporte (admin): GET /api/clients/:id/ingest-status devuelve backbone_status, events_flowing y last_event_at del cliente.

Paso 4 — Enviar un evento de prueba

Con el sitio verificado, dispara una conversión de prueba para validar el pipeline completo (evento → atribución → comisión):

// Conversión genérica
relo('event', 'test_event', { source: 'setup-verification' });

// Lead-gen (clientes pay-per-lead): dispara lead_submit
relo('lead', {
  email: 'test@relo.mx',        // se hashea SHA-256 en el browser
  product: 'Test Product',
  form_id: 'setup-test',
  stage: 'raw',
  lead_value: 1,
  currency: 'MXN'
});

// E-commerce
relo('event', 'purchase', {
  order_id: 'TEST-001',
  revenue: 1,
  currency: 'MXN'
});

# Fallback GET del endpoint /e (devuelve un GIF 1x1 y reenvía el evento)
curl -s -o /dev/null -w "%{http_code}\n" \
  "https://p.relo.mx/e?t=page_view&cid=CLIENT_ID&did=setup-test&url=https://example.com/"
# Esperado: 200

Después confirma en Live events que aparece test_event / lead_submit / purchase. Para probar atribución a partner, entra al sitio con un tracking link real (https://t.relo.mx/c/CODE) antes de disparar el evento — así el click_id viaja y el evento se atribuye al partner y campaña correctos.

Timezone

Todos los dashboards, comisiones y pagos se computan en America/Mexico_City. Los eventos se guardan con timestamp UTC (ms) y se convierten al consultar. Importa al verificar "eventos de hoy": un evento de las 11 PM UTC ya cae en otro día de calendario en Ciudad de México. Las vigencias de lead rates (effective_from) también se comparan contra la fecha del evento en America/Mexico_City.

Paso 5 — Si no aparece nada (troubleshooting)

Síntoma	Causa probable	Fix
`relo` es `undefined` en consola	Snippet no pegado, o bloqueado por ad blocker / CSP	Revisa que el `<script>` esté en el HTML servido (View Source). Prueba en incógnito sin extensiones. Whitelist `p.relo.mx` en la CSP (`script-src` y `connect-src`).
`r.js` carga pero no hay requests a `/e`	Consent bit 0 (`0x01` analytics) apagado, o el browser manda GPC (fuerza analytics+DSP off)	El default es `0xFF` (todo on). Si el sitio pasa `consent` en el init o tiene un banner que llama `relo('consent', ...)`, verifica que el bit de analytics quede en 1.
Requests a `/e` con 204 pero "No events yet" en verify	`client_id` equivocado en el init, o estás viendo otro cliente	Confirma el id numérico contra el snippet de Client Settings. El verify consulta por `client_id`, no por dominio.
Eventos llegan pero sin partner atribuido	El visitante no llegó por un tracking link	Entra con `https://t.relo.mx/c/CODE`: el wrapper pone cookie `_relo_cid` en `.relo.mx` y agrega `&relo_click_id=` al redirect; el pixel adopta ese click_id y lo manda en cada evento. Sin click, el evento se guarda pero no se atribuye.
`lead_submit` llega pero no genera comisión	Falta rate o vínculo partner↔campaña	Se necesita fila en `partner_lead_rates` (evento `lead_submit`, stage que aplique) y una fila en `partner_campaigns`. Detalles en Alta de partner lead-gen.
Verify responde "Couldn't check right now"	Backbone inalcanzable (`checked: false`)	Es degradación graceful del endpoint, no del pixel. Revisa `GET /api/clients/:id/ingest-status` (`backbone_status`) y System Health.
Eventos de ayer no cuadran en el dashboard	Timezone	Todo se agrupa en America/Mexico_City, no en la TZ de tu browser.
Visitas de prueba propias no aparecen	Tu browser tiene DNT/GPC activo o ad blocker	El pixel respeta `navigator.globalPrivacyControl` (apaga analytics+DSP) y `doNotTrack` (apaga DSP). Prueba con otro browser/perfil.

Opcional A — Puente auto-lead (zero-code)

Para sitios que solo pueden pegar el snippet pero no pueden tocar el handler del form: activa el puente en el init y cada submit de <form> disparará también lead_submit.

relo('init', {
  client_id: CLIENT_ID,
  auto_lead_on_submit: true,
  lead_defaults: {
    product: 'Auto Insurance',
    stage: 'raw',
    lead_value: 1,
    currency: 'MXN'
  }
});

Overrides por formulario con atributos HTML:

<form id="home-quote" data-relo-product="Home Insurance" data-relo-value="75">...</form>
<form data-relo-skip>...</form>  <!-- este form no genera lead -->

Atributos soportados: data-relo-product, data-relo-stage, data-relo-value, data-relo-currency, data-relo-source, data-relo-skip.

Opcional B — Lead push server-side (HMAC)

Para clientes que quieren mandar leads con PII completa desde su backend (ej. después de guardar el lead en su propia DB), existe un endpoint server-to-server firmado con HMAC:

Genera el secreto

POST /api/clients/:id/pixel-config/regenerate-secret (admin) → responde { "hmac_secret": "..." }. Se guarda en client_pixel_config.hmac_secret (solo lo lee el service role). Rotar el secreto invalida el anterior.

Firma y manda el lead

POST https://relo-api.quomx.workers.dev/api/pixel/lead-submission?client_id=N con header X-Relo-Signature: hex(HMAC-SHA256(rawBody, hmac_secret)):

const crypto = require('crypto');
const body = JSON.stringify({
  client_lead_id: 'Q-12345',   // requerido: UUID propio del cliente (dedup)
  first_name: 'Juan', last_name: 'Perez',
  email: 'juan@example.com', phone: '+525555551234',
  product: 'Auto Insurance', stage: 'raw',
  lead_value: 50, currency: 'MXN',
  relo_click_id: '01J...',     // si lo tienes, mejora la atribución
  event_time: '2026-07-30T18:00:00Z'
});
const sig = crypto.createHmac('sha256', HMAC_SECRET).update(body).digest('hex');
await fetch('https://relo-api.quomx.workers.dev/api/pixel/lead-submission?client_id=CLIENT_ID', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Relo-Signature': sig },
  body
});

Dedup y lectura

Dedup en (client_id, client_lead_id) — el primer write gana, reenviar el mismo client_lead_id no duplica. Los registros se leen en GET /api/clients/:id/lead-submissions (admin + client_user, con CSV export).

A diferencia del pixel en el browser (donde el PII se hashea SHA-256 client-side), este endpoint sí recibe PII en texto plano — es server-to-server y va firmado. Úsalo solo cuando el cliente realmente necesite PII completa en Relo.

Opcional C — Session replay (rrweb)

Grabación de sesiones DOM para depurar abandono de formularios. Apagado por default. Tres gates deben ser verdaderos:

replay_enabled = true en la config del cliente.
Consent bit 4 (0x10) del usuario.
random() * 100 < replay_sample_rate (0-100).

Hoy no hay toggle en la UI: se activa vía API — POST /api/clients/:id/pipeline/pixel-config con { "replay_enabled": true, "replay_sample_rate": 10, "consent_replay": true } (admin). Los chunks van a R2 con TTL de 90 días y se reproducen en Pixel Analytics → Replays (/v2/c/:slug/pixel-analytics, solo admin). Defaults de privacidad: todos los inputs enmascarados, sin canvas ni mousemove.

Referencia rápida

Rutas del portal (admin)

Ruta	Qué ves
`/v2/clients/new`	Wizard de onboarding (crear cliente pixel)
`/v2/c/:slug/settings`	Client Settings: allowed domains, tracked events, install snippet, privacy snapshot
`/v2/c/:slug/pixel-analytics`	Dashboard pixel: Overview, Forms, Funnel, Heatmap, Replays, Live events (*solo admin)
`/v2/c/:slug/leads`	Conversions/Leads del cliente con filtros + CSV
`/v2/c/:slug/partners`	Partners del cliente (onboard, tracking links)
`/v2/c/:slug/planner`	Lead Rate Planner (tarifas por lead del mes siguiente)
`/v2/c/:slug/setup-edit`	Editar basics (incl. tracking type)

Endpoints admin (API worker, `relo-api.quomx.workers.dev`)

Endpoint	Uso
`POST /api/clients/onboard`	Crear cliente completo en una transacción
`GET /api/clients/:id/pixel/activity`	Verify-install: `has_activity`, `events_last_hour`, `last_seen_at`
`GET /api/clients/:id/ingest-status`	`backbone_status`, `events_flowing`, `last_event_at`
`GET` / `POST /api/clients/:id/pipeline/pixel-config`	Leer/actualizar config pixel (domains, eventos, jurisdicción/consent, replay)
`GET` / `PUT /api/clients/:id/pixel-config`	Config pixel legacy (mismo store; incluye `hmac_secret`)
`POST /api/clients/:id/pixel-config/regenerate-secret`	Rotar el HMAC secret para lead push S2S
`POST /api/pixel/lead-submission?client_id=N`	Lead push server-side firmado con HMAC (no requiere JWT)

Endpoints del pixel (públicos)

Endpoint	Uso
`GET https://p.relo.mx/r.js`	El script del pixel (cache 5 min en edge)
`POST https://p.relo.mx/e`	Receiver de eventos (sendBeacon/XHR; responde 204)
`GET https://p.relo.mx/e?t=...&cid=N`	Fallback img-pixel (GIF 1x1)
`GET https://p.relo.mx/ping`	RTT measurement (204)

Guías relacionadas

Pixel (referencia) — catálogo de eventos, API relo(), consent bitmask, lead API.
Alta de partner lead-gen — rates por lead, tracking link y primera comisión.
Lead Rate Planner — tarifas por partner × evento × etapa, vigentes el mes siguiente.
Integration — Stripe webhook + variantes de instalación del pixel (GTM, SPA, Shopify).
Go-live S2S con red externa — cuando la conversión llega por postback de una red (Mitgo/Admitad), no por el pixel.

Pixel Setup

On this page