Web SDK Setup Guide

Basic Setup
Advanced Setup
- Intro
- Reporting Custom Events

Basic Setup

Use the basic setup of the Web SDK in order to:

Implement Track & Trigger
Implement Web Push Notifications

Add the Web SDK initialization script to your website

The following code snippet must be added to your website on every page load, either by adding it into the relevant site template files/code or using a website tag manager (such as Google Tag Manager code snippet) This code will load and initialize the SDK.

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

Note:

Remember to replace <YOUR_TENANT_ID> and <YOUR_TENANT_TOKEN> ,with the actual details that you receive from Optimove’s Integration Team.

For example:

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

Tracking Page Visits

In order to track page visits, call the setPageVisit() function on every page of the website to ensure that accurate user counts and session time metrics are collected.For customers, If a user is identified you can add the SDK_ID to the setPageVisit() function, see examples below

// 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 usage for Visitor:

// general shared function to captures page visits
function updateSDKPageVisit (PageURL, PageTitle, PageCategory) {
// SDK function
optimoveSDK.API.setPageVisit(PageURL, PageTitle, PageCategory);
}
// variables indicating the page info
var PageURL = 'https://www.myshop.com/clothes/unisex/shirts?item=123456';
var PageTitle = 'Some Shirt Name';
var PageCategory = 'Clothes Unisex Shirts';

// calling the shared function with the relavant variables
updateSDKPageVisit (PageURL, PageTitle, PageCategory);

Example usage for Customer:


// PageURL: The page URL (string, required)
// PageTitle: The page title (string, required)
// PageCategory: The page category (string, optional)
// The SDK_ID refers to the unique/primary customer ID used by your website to identify registered customers/users.

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 to the same page.

The Optimove SDK setPageVisit() function does not support callback functions.

"customURL", and "pageTitle" are mandatory parameters.

Make sure to send the full URL, e.g. 'https://www.example.com'

Call this function with the SDK_ID upon every page load/visit when you recognize the logged in user

Targeting visitors by email

Whenever the website captures a visitor’s email address, such as when a visitor submits a newsletter, you can call a custom event that includes the ‘email’ parameter. After using a custom event including an email parameter, the visitor may be targeted by an email execution channel

Example usage: Targeting visitors after submitting a newsletter

var parameters = {
      email: '[email protected]',
      first_name: 'John',
      optin: true,
      brand: 'example',
}
// passing the variables to the SDK function
optimoveSDK.API.reportEvent(‘newsletter_reg’,parameters)

Note:

The "email" is a required variable and must be a "string" format.

Make sure the email is valid

Tracking New Registrations

Whenever a single user action requires a new registration (e.g., registration, newsletter signup), you should use the registration event.

Example usage 1: Registration without callback function:


// example variables
var SDK_ID = 'JohnDoe';

var parameters = {
      email: '[email protected]',
      first_name: 'John',
      optin: true,
      brand: 'example',
      source: 'footer'    
}


// passing the variables to the SDK function
optimoveSDK.API.reportEvent('registration',parameters,null,SDK_ID)

Example usage 2: Registration with callback function to report additional custom event/s:


// example variables
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}); 
	};

// passing the variables to the SDK function
optimoveSDK.API.reportEvent('registration',parameters,callback,SDK_ID)

Notes:

You should include the email parameter if you want to target the user via email.

Tracking login for existing users

In all cases, where you detect a user login call the login event

Example usage 1: login without callback function:

// example variables
var SDK_ID = 'JohnDoe';

var parameters = {
      brand: 'example',    
}

// passing the variables to the SDK function
optimoveSDK.API.reportEvent('login',parameters,null,SDK_ID)

Example usage 2: login with callback function:

// example variables
var SDK_ID = 'JohnDoe';

var parameters = {
      brand: 'example',    
}

var callback = function() { 
	optimoveSDK.API.reportEvent('player_balance', {balance: 5}); 
	};

// passing the variables to the SDK function
optimoveSDK.API.reportEvent('login',parameters,callback,SDK_ID)

Notes:

Event names and parameters must first be configured within the Optimove instance using the Events Configuration Screen

Event and parameter names are case sensitive.

Events and parameters use lowercase and snakecase as a naming convention. Separate each word with one underscore character () and no spaces. (e.g., checkout_completed)

The parameter types available for use in event-reporting functions are: > String – A series of alphanumeric characters of up to 255 characters in length, using any encoding >Number – Any numeric value, whether an integer or a value containing a decimal point >Boolean – Is either "true" or "false" values, not a string

All monetary values must be reported in the same currency defined in your Optimove instance (e.g., if your instance is based on US dollars, all monetary event values must be reported in dollars). Optimove will not perform currency conversions.

If your Optimove instance supports multiple languages, all event parameters must use a single default language. This is required in order to maintain a unified set of events.

The callback function must be sent as null when it is not in use

In order to ensure the correct order of arrival, utilize the Optimove SDK callback functions.

Signing out users

Use the following API to sign a user out:

optimoveSDK.API.signOutUser();

Reading the visitor identifier

Use the following API to read the consistent visitor id which doesn't change with user signing in our out:

optimoveSDK.API.getInitialVisitorID();

Advanced Setup

Intro

The Advanced Setup includes everything in the Basic Setup as well as reporting custom events.

Following your Basic Setup SDK deployment, Optimove's Product Integration Manager will setup a call to help you create and implement the custom events.

Note: The Basic Setup is a pre-requisite to the Advanced one.

Reporting Custom Events

Your website reports a predefined event to Optimove by using JavaScript to call reportEvent() in this format:

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

In case a user is identified you can add the SDK_ID to the reportEvent() function in this format:

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

Example usage 1: reportEvent() without callback function for unidentified users

// an function for adding a product to a specific wish list
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);
}

// calling the add to wish list function with the relavant data
addToWishList('my wish list 1', 123456, 'product name', 1.99);

Example usage 2: reportEvent() without callback function for identified users

// an function for adding a product to a specific wish list
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);
}

// calling the add to wish list function with the relavant data
addToWishList('my wish list 1', 123456, 'product name', 1.99);

Example usage 3: reportEvent() with callback function for unidentified users

// a function for adding a product to a specific wish list 
//and updating the current size of the wish list 
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); 
} 

// calling the add to wish list function with the relavant data 
addToWishList('my wish list 1', 123456, 'product name', 1.99);

Example usage 4: reportEvent() with callback function for identified users

// a function for adding a product to a specific wish list 
//and updating the current size of the wish list 
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); 
} 

// calling the add to wish list function with the relavant data 
addToWishList('my wish list 1', 123456, 'product name', 1.99);

Note:

Event names and parameters must first be configured within the Optimove instance using the Events Configuration Screen

Event and parameter names are case sensitive.

Events and parameters use lowercase and snakecase as a naming convention. Separate each word with one underscore character () and no spaces. (e.g., checkout_completed)

The parameter types available for use in event-reporting functions are:
String – A series of alphanumeric characters of up to 255 characters in length, using any encoding
Number – Any numeric value, whether an integer or a value containing a decimal point
Boolean – Is either "true" or "false" values, not a string

All monetary values must be reported in the same currency defined in your Optimove instance (e.g., if your instance is based on US dollars, all monetary event values must be reported in dollars). Optimove will not perform currency conversions.

If your Optimove instance supports multiple languages, all event parameters must use a single default language. This is required in order to maintain a unified set of events.