Tracking SDK (`ip.js`)

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 2 years in a first-party cookie (iv) to identify returning users.
Session Management: Maintains short-lived session IDs (30 minutes) in a 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 allows you to push tracking commands before the SDK has fully loaded, ensuring no events are missed.

`_iaq` Configuration

The _iaq (Analytics Queue) 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

Command	Example	Description
`client`	`['client', 'your-instance-id']`	Required. Sets the client identifier.
`delivery`	`['delivery', 12345]`	Required. Specifies the Property's Delivery ID.
`track`	`['track', 'consume']`	Tracks an event. Supported events are `consume` (page view), `convert` (group assignment), and `identify` (record identifiers). A URL can be passed as a second parameter to consume events.
`user`	`['user', 'mas_id', '029853031']`	Stores user-specific identifiers like an obfuscated email or cookie ID. Multiple values can be stored under the same identifier.
`goal`	`['goal', 'newsletter-signup']`	Sets the conversion/goal name. Requires a call to `track` to record.
`userinfo`	`['userinfo', { segment: 'premium', tier: 'gold' }]`	Assign additional data to the user.

Basic Example

This example shows how to configure the client, track a page view, 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

Commands can be 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 the Delivery is configured to use the redirect service. This is useful when you're unable to embed the tracking script on the destination page. The redirect service will record these parameters and forward the user onto 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.

No configuration is required—if the _madid cookie exists, it will be automatically included in all tracking events.

First-Party Cookies:

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

iv (Visitor ID): 2-year persistent identifier for returning user recognition
is (Session ID): 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.

Tracking SDK (ip.js)