Relo Pixel — How it works + how to configure

End-to-end guide covering how the Relo Web Pixel captures data, how conversion attribution happens, and how to onboard a pixel client from the admin portal.

1. What the pixel is

The Relo Pixel is a ~50KB JavaScript snippet that runs on any website. It captures page views, form interactions, purchases, leads, engagement, scroll depth, clicks, and ~50 other signals. Events ship to p.relo.mx/e, get enriched with geo/device info, and flow to ClickHouse for real-time analytics + attribution.

MMP vs Pixel vs Hybrid. Relo supports three tracking modes:

MMP AppsFlyer / Branch postbacks from mobile apps (e.g. Samsung).
PIXEL Browser-based pixel for web sites (e.g. Quote, Optimal).
HYBRID Accept both — useful if a client has mobile + web.

A client's tracking_type is the main switch; campaigns can override per-campaign.

2. The install snippet

Every pixel client gets this snippet. Replace N with the client_id shown in Admin → Client Config → Data Pipeline → Web Pixel.

<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: N });
relo('page');
</script>

Place anywhere in the page — typically the <head>. It loads async, runs only if consent bit 0 (analytics) is set, and gracefully no-ops on browsers that block it.

3. Init options — all configurable

Option	Default	Description
`client_id`	—	Required. The Relo client you registered in portal.
`consent`	`0xFF`	Consent bitmask. Bits: 0x01 analytics, 0x02 personalization, 0x04 DSP export, 0x08 cross-client, 0x10 session replay.
`domain`	auto	Cookie domain for cross-subdomain identity (`.yourdomain.com`).
`auto_lead_on_submit`	`false`	If true, every `<form>` submit also fires `lead_submit` with your defaults. Useful when you can't edit submit-handler code.
`lead_defaults`	`{}`	Defaults for the auto-lead bridge. Keys: `product`, `stage`, `lead_value`, `currency`, `form_id`, `lead_source`.

4. Events — what's auto, what you fire

Automatic (no code on your side)

Event	When
`page_view`	Every page load + SPA route change
`fp_ready`	Device fingerprint computed
`form_start`	First interaction with any form
`form_submit`	HTML form submit event
`form_abandon`	Left page with form_start but no submit
`scroll`	25/50/75/90/100% scroll depth
`click`	Every click with coords (for heatmaps)
`engagement`	Pagehide with active/hidden seconds + scroll_max
`checkout_open`	Detects Stripe/MercadoPago/Conekta/OpenPay/PayU/PayPal/Kushki/Culqi
`net_quality`	Connection type/RTT (navigator.connection + ping fallback)
+ ~40 more	web_vitals, rage_click, dead_click, outbound_click, video_*, …

Fire manually from your code

// E-commerce purchase
relo('event', 'purchase', {
  order_id: 'O-123',
  product_id: 'SKU',
  revenue: 299.99,
  currency: 'USD'
});

// Lead-gen / form-based conversions
relo('lead', {
  email: 'user@example.com',      // hashed SHA-256 client-side
  phone: '+525555551234',         // hashed SHA-256 client-side
  product: 'Auto Insurance',      // shown in portal
  form_id: 'quote-home-v2',
  stage: 'raw',                   // raw / qualified / sold
  lead_value: 50,
  currency: 'USD',
  extra: { zip: '33139', vehicle_year: 2023 }
});

// SaaS signup / custom event
relo('event', 'signup', { plan: 'pro' });
relo('event', 'video_complete', { video_id: 'vid123' });

// Identify without firing a conversion (background)
relo('identify', { email, phone, name });

// Runtime consent update (e.g. from cookie banner)
relo('consent', { analytics: true, dsp: false });
relo('consent', 0xFF);

PII is hashed client-side. Email and phone get SHA-256'd in the browser before they leave. Admin/partners only see a 12-char prefix of the hash (enough for dedup, not enough for dictionary attack). Raw PII is never stored.

5. Attribution: how clicks map to partners

A partner URL looks like https://t.relo.mx/c/CODE. Clicking it:

The click wrapper Worker at t.relo.mx generates a click_id (ULID).
Looks up CODE in KV → {url, partner_id, client_id, campaign_id}.
Sets cookie _relo_cid=<click_id> on .relo.mx, 30-day TTL.
Stores click metadata in Redis (30-day TTL) keyed by click_id.
302 redirects to the landing URL with &relo_click_id=<click_id>.

Now on the landing site, the pixel reads the _relo_cid cookie and sends it with every event. The Go ingest service does a Redis lookup by click_id and attributes the event to partner_id + campaign_id.

Works across subdomains because the cookie is on .relo.mx. So quote.miami, app.quote.miami, and anything else on a relo-controlled subdomain sees the same cookie.

6. Admin — Onboarding a pixel client

6.1 Create the client

From portal.relo.mx/clients/new, run the Setup Wizard. In step 2, pick PIXEL as the tracking type. The wizard creates client_pixel_config with sensible defaults.

6.2 Install the pixel on the site

Copy the install snippet from Admin → Client Config → Data Pipeline → Web Pixel → Install Snippet. Paste in the client's site <head>. Within minutes, events flow into Admin → /c/SLUG/audit → Live Events.

6.3 Configure privacy / consent

Same Data Pipeline tab has a Privacy & Consent section:

Jurisdiction dropdown — MX / LATAM / EU / UK / US-CA / US-state / custom. Selecting a preset auto-sets the 5 consent bits.
Consent bits — analytics (bit 0), personalization (bit 1), DSP export (bit 2), cross-client (bit 3), session replay (bit 4).
Respect GPC / DNT toggles — when on, browser signals force certain bits off.
Privacy + cookie policy URLs — shown next to the install snippet for your compliance.

6.4 Onboard a partner (the one-form flow)

From Admin → /c/SLUG/partners, click + Onboard partner. Fill:

Partner — pick existing or create new (company name, contact email).
Campaign — pick existing pixel campaign or create new.
Short code — 3-20 alphanumeric chars. Becomes t.relo.mx/c/CODE.
Landing URL — where partners send traffic. We append &relo_click_id on redirect.

One POST creates: partners row, partner_clients row, campaigns row with tracking_type='pixel', partner_campaigns row, KV click-wrapper entry. You get the tracking URL to give to the partner. Done.

6.5 Enable session replay (optional)

Data Pipeline → Web Pixel → Session Replay section:

Enable replay — master switch.
Consent bit 4 — must be set in users' consent too.
Sample rate — 0-100% of eligible sessions.

Replays appear in Admin → /c/SLUG/audit → Replays subtab. rrweb-player loads lazily.

7. Conversion events — what we track by default

The admin Conversions page and partner LeadsTab both aggregate the following by default:

lead_submit — lead-gen (Quote)
purchase — ecommerce
form_submit — generic forms
signup — SaaS onboarding
subscription — recurring billing start
checkout_open — intent signal

The UI picks a dominant label (Leads / Purchases / Signups / Conversions) based on which event_name tops the count. Filter by individual type via query param ?event_types=purchase,lead_submit.

8. Auto-lead bridge (zero-code conversions)

For sites that can only paste the pixel snippet but can't edit their form submit handler — turn on auto_lead_on_submit:

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

Every form submit now also fires lead_submit. Per-form overrides via HTML attributes:

<form id="home-quote" data-relo-product="Home Insurance" data-relo-value="75">
  ...
</form>

<form data-relo-skip>  <!-- opts this form out -->
  ...
</form>

9. Lead stage updates (CRM integration)

When your CRM qualifies a lead (raw → qualified → sold), POST to:

POST https://ingest.relo.mx/leads/stage
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "client_id": 5,
  "external_id": "Q-12345",        // the quote_id you set when firing relo('lead')
  "new_stage": "qualified",
  "note": "Manual review passed",
  "by": "john@quote.com"
}

Writes an append-only lead_stage_update event. Admin UI + commission calc reads the latest stage per external_id.

10. Partner commissions for pixel

MMP partners get paid per segment (MX/VD/DA/…) via partner_segment_commissions. Pixel partners get paid per event via partner_lead_rates:

CREATE TABLE partner_lead_rates (
  partner_id, client_id,
  event_name,      // lead_submit / purchase / signup / *
  stage,           // raw / qualified / sold / NULL for any
  rate, is_percentage, currency,
  effective_from, effective_to,
  monthly_cap
);

Examples:

Quote partner: {event_name: 'lead_submit', stage: 'qualified', rate: 25} — pays $25 per qualified lead.
Ecommerce partner: {event_name: 'purchase', rate: 5, is_percentage: true} — 5% revenue share.
SaaS: {event_name: 'subscription', rate: 100} — $100 per paying subscription start.

11. Quick reference — admin URLs

Route	What you see
`/c/SLUG/dashboard`	Pixel dashboard (sessions/conversions/funnel) or MMP dashboard, auto-picked by tracking_type
`/c/SLUG/audit`	Pixel Audit: Live Events, Conversion Funnel, Attribution Health, Heatmap, Replays
`/c/SLUG/leads`	Conversions page (admin-wide) with filters + CSV export
`/c/SLUG/partners`	Partners list; "Onboard partner" button for pixel clients
`/c/SLUG/config?tab=data-pipeline`	Pixel install snippet, privacy, replay toggles
`/client/SLUG`	Client-user portal (read-only view of their own data)

12. Partner-facing — what partners see

At portal.relo.mx/p/SLUG, partners see tabs that adapt to each campaign's tracking_type:

Dashboard — MMP KPIs or Pixel KPIs (sessions/conversions/funnel)
Analytics — MMP (hours/days/sources) or Pixel (referrers/landing pages/engagement/UTMs)
Orders / Conversions — transaction rows or lead rows, auto-labeled
Assets — MMP tracking IDs or pixel short URLs with per-link stats
Payments / Settings — same as MMP