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
Command | Example | Description |
|---|---|---|
client | ['client', 'your-instance-id'] | (Required) Sets the client identifier. |
delivery | ['delivery', 12345] | (Required) Specifies a property's delivery ID. |
track | ['track', 'consume'] | Tracks an event. Supported events are consume (pageview), 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 or goal name. Requires a call to track to record. |
userinfo | ['userinfo', { segment: 'premium', tier: 'gold' }] | Assigns additional data to the user. |
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.