Documentation

Quick Start

1. Get Your Site ID

2. Add the Tracking Snippet

Add this to your website's <head> tag:

<script src="https://www.trailpixel.com/tracker.js" data-site-id="YOUR_SITE_ID"></script>

Page views and clicks are now tracked automatically.

Track Custom Events

After the script loads, window.trailpixel (or window.tp) is available globally:

// Track a lead/signup
window.trailpixel.track('lead', {
  name: 'Lead Generated',
  properties: { source: 'newsletter_form' }
})

// Track a purchase
window.trailpixel.track('purchase', {
  name: 'Purchase Completed',
  properties: { amount: 49, currency: 'EUR', product: 'Pro Plan' }
})

// Track any custom event
window.trailpixel.track('custom', {
  name: 'Video Watched',
  category: 'engagement',
  properties: { duration: 120, videoId: 'abc123' }
})

Identify Users

Identify accepts an email, userId, or id. In cookieless mode it is SHA-256 hashed in the browser and raw profile data is not sent. With analytics consent, full identification is linked across sessions:

// After login/signup
window.trailpixel.identify({
  email: 'user@example.com',
  name: 'John Doe'
})

Cookieless & GDPR

TrailPixel initializes in a storage-free cookieless mode. It sends aggregate events without a persistent visitor or session ID, does not write cookies or localStorage, strips URL query strings and fragments, and does not store the request IP address.

The tracker always initializes; consent is not needed merely to load it
No persistent identifier is created before analytics consent
Before consent, identification is hashed in the browser and held only in memory
Your organization remains responsible for its legal basis, notice, event data, and CMP configuration

Connect your consent manager

// Call whenever the analytics consent choice changes.
// true: first-party visitor and 30-minute session cookies
// false: delete TrailPixel cookies and continue cookieless
window.trailpixel.setConsent(true)

// Or dispatch an event from your CMP's consent-change callback
window.dispatchEvent(new CustomEvent('trailpixel:consent', {
  detail: { analytics: true }
}))

// If consent is known before the script loads:
<script src="https://www.trailpixel.com/tracker.js"
  data-site-id="YOUR_SITE_ID"
  data-analytics-consent="true"></script>

Data-tp-name for Click Tracking

Use the data-tp-name attribute to give meaningful names to tracked clicks:

<button data-tp-name="Signup CTA Button">Get Started</button>
<a href="/pricing" data-tp-name="Nav Pricing Link">Pricing</a>

A/B Testing

Create an A/B test in the dashboard, then use the variant assignment:

// On your server, assign a variant
const variantId = Math.random() < 0.5 ? 'variant_a' : 'variant_b'

// Track which variant the visitor saw
window.trailpixel.track('custom', {
  name: 'Variant Seen',
  properties: { testId: 'YOUR_TEST_ID', variant: variantId }
})

// TrailPixel automatically correlates this with downstream funnel events

Server-Side Tracking

Send events directly from your backend using any HTTP client. This is useful for tracking server-side actions like form submissions, payment confirmations, or webhook events.

Track an Event

POST to https://www.trailpixel.com/api/track with the event payload:

// Node.js / fetch
fetch('https://www.trailpixel.com/api/track', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    siteId: 'YOUR_SITE_ID',
    visitorId: 'unique-visitor-id',
    sessionId: 'unique-session-id',
    type: 'page_view',
    name: 'Homepage',
    url: 'https://yoursite.com/',
    path: '/',
    referrer: 'https://google.com',
    utm: { utm_source: 'google', utm_medium: 'organic' },
    properties: { key: 'value' },
    timestamp: new Date().toISOString()
  })
})

Identify a User

POST to https://www.trailpixel.com/api/identify to link a visitor to a known user:

fetch('https://www.trailpixel.com/api/identify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    siteId: 'YOUR_SITE_ID',
    visitorId: 'unique-visitor-id',
    email: 'user@example.com',
    name: 'John Doe',
    plan: 'premium'  // any extra metadata
  })
})

Python Example

import requests

# Track an event
requests.post('https://www.trailpixel.com/api/track', json={
    'siteId': 'YOUR_SITE_ID',
    'visitorId': 'user-123',
    'type': 'purchase',
    'name': 'Purchase Completed',
    'properties': { 'amount': 49, 'currency': 'EUR' }
})

# Identify a user
requests.post('https://www.trailpixel.com/api/identify', json={
    'siteId': 'YOUR_SITE_ID',
    'visitorId': 'user-123',
    'email': 'user@example.com',
    'name': 'John Doe'
})

cURL Example

curl -X POST https://www.trailpixel.com/api/track \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "YOUR_SITE_ID",
    "visitorId": "user-123",
    "type": "page_view",
    "name": "Homepage",
    "url": "https://yoursite.com/"
  }'

Required fields: siteId, type, name

Optional fields: visitorId, sessionId, category, properties, url, path, referrer, utm, timestamp, abTestVariantId