Tracking SDK reference

The ip.js SDK is a lightweight, asynchronous JavaScript library that enables visitor tracking, session management, and event logging. It is the analytics core of the personalization system.

Core features

• Visitor identity management – Generates a unique visitor ID (UUID4) and persists it for two years in a first-party cookie (iv) to identify returning users.
• Session management – Maintains short-lived (30 minutes) session IDs in the cookie is to group user behavior within a single browsing session.
• Data collection – Captures visitor data such as referrer, canonical URLs, and UTM parameters.
• Command queue system – Uses a global window._iaq array as a command queue. This lets you push tracking commands before the SDK has fully loaded, ensuring no events are missed.

_iaq configuration

The analytics queue _iaq is the primary interface for configuring tracking and firing events. Each command is an array containing a method name followed by its parameters.

Available commands

Basic example

See the following example to understand how to configure the client, track a pageview, and add optional user information:

var _iaq = [
    // Required configuration
    ['client', 'your-client-id'],
    ['delivery', 12345],

    // Optional user data
    ['user', 'email', 'obfuscated_email@uuid'],
    ['userinfo', { segment: 'premium' }],

    // Initial page view track
    ['track', 'consume']
];

Dynamic event tracking

See the following example to understand how commands are pushed to the _iaq array at any time, even after the initial page load, to track dynamic events:

// Track a conversion goal
function onNewsletterSignup() {
    _iaq.push(['goal', 'newsletter-signup']);
    _iaq.push(['track', 'convert']);
}

// Add additonal identifiers and metadata to the user
function onUpgradeToPremium(internalUserId) {
    _iaq.push(['user', 'email', internalUserId);
    _iaq.push(['userinfo', { segment: 'standard' }]);
    _iaq.push(['track', 'identify']);
}

Automatic data collection

The tracking SDK automatically collects certain data from your page and URL without requiring any configuration.

Redirect tracking parameters

The SDK automatically parses and includes special tracking parameters from your page URLs. These parameters start with it and are set when you configure to use the redirect service. This is useful when you cannot embed the tracking script on the destination page. The redirect service will record these parameters and forward the user to the destination URL.

Cookie integration

The SDK automatically integrates with certain cookies to enhance tracking capabilities:

Optimizely integration

If your site uses Optimizely and has set the _madid cookie (Marketing Automation Device ID), the tracking SDK will automatically detect it and include the device ID in tracking data as epi_device_id. This enables cross-platform tracking between Content Recommendations and other Optimizely products.

You do not need to configure additionally if the _madid cookie exists, as it will be automatically included in all tracking events.

First-party cookies

The SDK creates and manages the following two first-party cookies automatically:

• iv (Visitor ID): A two-year persistent identifier for returning user recognition
• is (Session ID): A 30-minute session identifier for grouping behavior within a browsing session

These cookies are created automatically on first page load and maintained by the SDK.