Guides

Web SDK Integration

Suggest Edits

The Optimove Web SDK enables you to track user behavior on your website and trigger personalized campaigns through Optimove’s Track & Trigger system. By integrating the Web SDK, you can monitor page visits, user registrations, logins, and custom events, allowing you to deliver targeted experiences like web push notifications or email campaigns. This guide covers both basic and advanced setups, including how to manage user communication preferences with the Preference Center.

Basic Setup

The basic setup enables you to implement Track & Trigger and Web Push Notifications using the Optimove Web SDK.

Prerequisites

Before you begin, ensure you have:

  • An Optimove account with access to Track & Trigger.
  • A tenant ID and tenant token provided by Optimove’s Integration Team.
  • A website where you can add JavaScript code (either directly or via a tag manager like Google Tag Manager).

ℹ️

Note: Replace <YOUR_TENANT_ID> and <YOUR_TENANT_TOKEN> in examples with your actual tenant ID and token.

Add Web SDK Initialization Script

Add the following script to every page of your website to load and initialize the Web SDK. You can include it in your site template files or use a tag manager.

<script async src="https://sdk.optimove.net/v2/websdk/?tenant_id=<YOUR_TENANT_ID>&tenant_token=<YOUR_TENANT_TOKEN>"></script>

Example

<script async src="https://sdk.optimove.net/v2/websdk/?tenant_id=000&tenant_token=99999wwwwwwwAAAAABBB"></script>

Tracking Page Visits

Track page visits by calling the setPageVisit() function on every page load to collect accurate user counts and session time metrics. For identified users, include the SDK_ID.

// PageURL: The page URL (string, required)
// PageTitle: The page title (string, required)
// PageCategory: The page category (string, optional)
optimoveSDK.API.setPageVisit(PageURL, PageTitle, PageCategory);

Example: Visitor

function updateSDKPageVisit(PageURL, PageTitle, PageCategory) {
    optimoveSDK.API.setPageVisit(PageURL, PageTitle, PageCategory);
}

var PageURL = 'https://www.myshop.com/clothes/unisex/shirts?item=123456';
var PageTitle = 'Some Shirt Name';
var PageCategory = 'Clothes Unisex Shirts';

updateSDKPageVisit(PageURL, PageTitle, PageCategory);

Example: Customer

var PageURL = 'https://www.myshop.com/clothes/unisex/shirts?item=123456';
var PageTitle = 'Some Shirt Name';
var PageCategory = 'Clothes Unisex Shirts';
var SDK_ID = '12345';

optimoveSDK.API.setPageVisit(PageURL, PageTitle, PageCategory, SDK_ID);

ℹ️

Note:

  • Every page view is recorded, including repeated visits.
  • The setPageVisit() function does not support callbacks.
  • PageURL and PageTitle are required parameters.
  • Use the full URL for PageURL (e.g., https://www.example.com).
  • Include SDK_ID for logged-in users on every page load.
Diagram showing the workflow for tracking page visits using the setPageVisit() function.

Figure 1: Workflow for tracking page visits.

Targeting Visitors by Email

Capture a visitor’s email (e.g., during a newsletter signup) to enable email targeting by reporting a custom event with an email parameter.

Example: Newsletter Signup

var parameters = {
    email: '[email protected]',
    first_name: 'John',
    optin: true,
    brand: 'example'
};
optimoveSDK.API.reportEvent('newsletter_reg', parameters);

ℹ️

Note:

  • The email parameter is required and must be a string.
  • Ensure the email is valid.

Tracking New Registrations

Report new registrations (e.g., account creation, newsletter signup) using the registration event.

Example 1: Registration Without Callback

var SDK_ID = 'JohnDoe';
var parameters = {
    email: '[email protected]',
    first_name: 'John',
    optin: true,
    brand: 'example',
    source: 'footer'
};
optimoveSDK.API.reportEvent('registration', parameters, null, SDK_ID);

Example 2: Registration With Callback

var SDK_ID = 'JohnDoe';
var parameters = {
    email: '[email protected]',
    first_name: 'John',
    optin: true,
    brand: 'example',
    source: 'footer'
};
var callback = function() {
    optimoveSDK.API.reportEvent('items_in_cart', {'product_name': 'shirt', 'product_price': 7});
};
optimoveSDK.API.reportEvent('registration', parameters, callback, SDK_ID);

ℹ️

Note: Include the email parameter for email targeting.

Tracking Login for Existing Users

Report user logins using the login event.

Example 1: Login Without Callback

var SDK_ID = 'JohnDoe';
var parameters = {
    brand: 'example'
};
optimoveSDK.API.reportEvent('login', parameters, null, SDK_ID);

Example 2: Login With Callback

var SDK_ID = 'JohnDoe';
var parameters = {
    brand: 'example'
};
var callback = function() {
    optimoveSDK.API.reportEvent('player_balance', {balance: 5});
};
optimoveSDK.API.reportEvent('login', parameters, callback, SDK_ID);

ℹ️

Note:

  • Configure event names and parameters in the Events Configuration Screen.
  • Event and parameter names are case-sensitive and use snake_case (e.g., checkout_completed).
  • Parameter types: String (up to 255 characters), Number (integer or decimal), Boolean (true/false).
  • Use the currency defined in your Optimove instance for monetary values.
  • Use a single default language for event parameters if your instance supports multiple languages.
  • Set the callback to null when not in use.
  • Use SDK callback functions to ensure the correct order of events.

Signing Out Users

Sign a user out using the following API:

optimoveSDK.API.signOutUser();

Reading the Visitor Identifier

Retrieve a consistent visitor ID that persists across sign-ins and sign-outs:

optimoveSDK.API.getInitialVisitorID();

Advanced Setup

The Advanced Setup builds on the Basic Setup by adding custom event reporting and Preference Center integration. After completing the Basic Setup, Optimove’s Product Integration Manager will assist with setting up custom events.

ℹ️

Note: The Basic Setup is a prerequisite for the Advanced Setup.

Reporting Custom Events

Report predefined events to Optimove using the reportEvent() function. For identified users, include the SDK_ID.

optimoveSDK.API.reportEvent(<event_name>, <parameter JS object>);

With SDK_ID

optimoveSDK.API.reportEvent(<event_name>, <parameter JS object>, null, SDK_ID);

Example 1: Unidentified User Without Callback

function addToWishList(list_name, pid, pname, price) {
    var params = {};
    params['list_name'] = list_name;
    params['pid'] = pid;
    params['name'] = pname;
    params['price'] = price;
    optimoveSDK.API.reportEvent('add_to_wishlist', params);
}
addToWishList('my wish list 1', 123456, 'product name', 1.99);

Example 2: Identified User Without Callback

function addToWishList(list_name, pid, pname, price) {
    var params = {};
    params['list_name'] = list_name;
    params['pid'] = pid;
    params['name'] = pname;
    params['price'] = price;
    optimoveSDK.API.reportEvent('add_to_wishlist', params, null, SDK_ID);
}
addToWishList('my wish list 1', 123456, 'product name', 1.99);

Example 3: Unidentified User With Callback

function addToWishList(list_name, pid, pname, price) {
    var params = {};
    params['list_name'] = list_name;
    params['pid'] = pid;
    params['name'] = pname;
    params['price'] = price;
    var callback = function() {
        optimoveSDK.API.reportEvent('wishlist_size_change', {wishlist_size: 5});
    };
    optimoveSDK.API.reportEvent('add_to_wishlist', params, callback);
}
addToWishList('my wish list 1', 123456, 'product name', 1.99);

Example 4: Identified User With Callback

function addToWishList(list_name, pid, pname, price) {
    var params = {};
    params['list_name'] = list_name;
    params['pid'] = pid;
    params['name'] = pname;
    params['price'] = price;
    var callback = function() {
        optimoveSDK.API.reportEvent('wishlist_size_change', {wishlist_size: 5});
    };
    optimoveSDK.API.reportEvent('add_to_wishlist', params, callback, SDK_ID);
}
addToWishList('my wish list 1', 123456, 'product name', 1.99);

ℹ️

Note:

  • Configure event names and parameters in the Events Configuration Screen.
  • Event and parameter names are case-sensitive and use snake_case (e.g., checkout_completed).
  • Parameter types: String (up to 255 characters), Number (integer or decimal), Boolean (true/false).
  • Use the currency defined in your Optimove instance for monetary values.
  • Use a single default language for event parameters if your instance supports multiple languages.

For managing user communication preferences, see the Preference Center Integration Guide.

Use Case

Imagine you’re running an e-commerce website. You integrate the Web SDK to track page visits and user registrations. When a visitor signs up for a newsletter (newsletter_reg event), you capture their email and target them with a welcome email campaign. For logged-in users, you track their browsing behavior (e.g., viewing shirts) and report custom events (e.g., add_to_wishlist). These actions enable personalized campaigns through Optimove’s Track & Trigger system.

Troubleshooting

Common issues and solutions:

SDK Not Initializing

  • Verify the tenant ID and token in the initialization script.
  • Check for JavaScript errors in the console.

Events Not Reported

  • Ensure event names and parameters are configured in the Events Configuration Screen.
  • Confirm the reportEvent() function includes required parameters.

Invalid Parameter Values

  • Use correct parameter types (string, number, boolean).
  • Ensure monetary values match your Optimove instance’s currency.

Updated 1 day ago