Api

Events Reference

Complete reference for all Idlen Pixel events and parameters

Events Reference

Complete documentation of all events, parameters, and data types supported by the Idlen Pixel.

Event Types

The Idlen Pixel supports three main event types:

Event Type	Description	Use Case
`PageView`	Page or screen view	Track navigation and engagement
`Conversion`	Goal completion	Track signups, purchases, trials
`Custom`	Custom event	Track any user interaction

PageView Event

Track when a user views a page or screen.

Syntax

idlen('track', 'PageView');

Automatic Data

The following data is automatically captured:

Field	Type	Description
`url`	string	Current page URL path
`referrer`	string	Previous page URL
`timestamp`	number	Event timestamp (Unix ms)
`visitor_id`	string	Anonymous visitor identifier

Example

// Basic page view
idlen('track', 'PageView');

// The pixel automatically captures:
// {
//   url: '/pricing',
//   referrer: '/features',
//   timestamp: 1706400000000,
//   visitor_id: 'abc123-def456'
// }

Conversion Event

Track when a user completes a desired action.

Syntax

idlen('track', 'Conversion', {
  eventName?: string,
  value?: number
});

Parameters

Parameter	Type	Required	Description
`eventName`	string	No	Conversion category name
`value`	number	No	Monetary value (e.g., purchase amount)

Standard Event Names

Use these standard names for better analytics:

Event Name	Description	Example Value
`signup`	User registration	-
`trial_start`	Free trial activation	Monthly price
`purchase`	Completed purchase	Order total
`subscription`	Subscription started	Monthly/annual price
`lead`	Lead form submission	-
`download`	App/file download	-
`demo_request`	Demo requested	-
`contact`	Contact form	-

Examples

// Basic conversion
idlen('track', 'Conversion');

// Named conversion
idlen('track', 'Conversion', {
  eventName: 'signup'
});

// Conversion with value
idlen('track', 'Conversion', {
  eventName: 'purchase',
  value: 99.99
});

// Trial with potential value
idlen('track', 'Conversion', {
  eventName: 'trial_start',
  value: 29  // Monthly plan price
});

Custom Events

Track any custom user interaction.

Syntax

idlen('track', 'CustomEventName', {
  // Any custom properties
});

Examples

// Feature usage
idlen('track', 'FeatureUsed', {
  feature: 'export',
  format: 'csv'
});

// Video engagement
idlen('track', 'VideoWatched', {
  videoId: 'intro-video',
  duration: 120,
  completed: true
});

// Search performed
idlen('track', 'Search', {
  query: 'pricing',
  results: 5
});

// CTA clicked
idlen('track', 'CTAClicked', {
  location: 'hero',
  variant: 'primary'
});

Initialization Options

Configure the pixel behavior at initialization.

Syntax

idlen('init', 'ADVERTISER_ID', {
  debug?: boolean,
  autoTrack?: boolean,
  trackHash?: boolean,
  excludeRoutes?: string[]
});

Options

Option	Type	Default	Description
`debug`	boolean	`false`	Enable console logging
`autoTrack`	boolean	`true`	Auto-track URL changes
`trackHash`	boolean	`false`	Track hash changes
`excludeRoutes`	string	`[]`	Routes to exclude from tracking

Examples

// Production setup
idlen('init', 'YOUR_ADVERTISER_ID');

// Development with debugging
idlen('init', 'YOUR_ADVERTISER_ID', {
  debug: true
});

// SPA with manual tracking
idlen('init', 'YOUR_ADVERTISER_ID', {
  autoTrack: false
});

// Hash-based routing
idlen('init', 'YOUR_ADVERTISER_ID', {
  trackHash: true
});

// Exclude admin routes
idlen('init', 'YOUR_ADVERTISER_ID', {
  excludeRoutes: ['/admin/*', '/internal/*']
});

Data Schema

Event Payload

All events send the following payload to the server:

interface EventPayload {
  // Required
  aid: string;      // Advertiser ID
  vid: string;      // Visitor ID
  et: string;       // Event type (pageview, conversion, custom)
  ts: number;       // Timestamp (Unix ms)
  url: string;      // Page URL

  // Optional
  ref?: string;     // Referrer URL
  en?: string;      // Event name (for conversions)
  ev?: number;      // Event value (for conversions)
  ed?: object;      // Event data (for custom events)
}

Server Response

The tracking endpoint returns a 1x1 transparent GIF image for maximum compatibility with ad blockers and tracking prevention.

Privacy & Data Collection

What We Collect

Data	Stored	Hashed	Purpose
Page URL	Yes	No	Analytics
Referrer	Yes	No	Attribution
User Agent	Yes	No	Device stats
IP Address	No	Yes	Geo (country only)
Visitor ID	Yes	No	Session tracking

What We Don't Collect

Personal information (name, email)
Third-party cookies
Cross-site tracking data
Fingerprinting data

Privacy-First: The Idlen Pixel is designed to be GDPR and CCPA compliant by default. No consent banner is required for basic analytics.

Rate Limits

Limit	Value	Description
Events per second	10	Per visitor
Payload size	4KB	Maximum event data
Custom properties	20	Per event

Events exceeding these limits are silently dropped.

Error Handling

The pixel handles errors gracefully without affecting your application:

// Safe to call even if pixel not loaded
if (window.idlen) {
  idlen('track', 'Conversion', { eventName: 'signup' });
}

// Or use optional chaining
window.idlen?.('track', 'PageView');

Failed events are:

Logged to console (in debug mode)
Silently discarded (in production)
Never retried (to prevent duplicate events)

API Reference

Complete API reference for the Idlen Pixel SDK

Data Collection & Privacy

What data the Idlen Pixel collects and how we protect user privacy