Insider Web SDK

22 Dec 2023
17 Minutes to read

Insider Web SDK

Updated on 22 Dec 2023
17 Minutes to read

Article Summary

Share feedback

Thanks for sharing your feedback!

Insider’s Web SDK offers a smooth integration process, and provides a robust and accurate data collection. The Insider script collects data about users’ behavior and actions, and products on your website to help you with unifying your user data across platforms, defining user actions, and building targeting rules and segmentation for your campaigns.

When it comes to data collection, Insider products use two data structures: Events and Attributes.
An event defines all the actions your users perform while interacting with your website, application, campaigns, and/or offline stores.
An attribute defines all the details about a user. It helps you understand their preferences such as personal information, last purchased and visited products, etc.

Suggested Readings: Understanding Events and Attributes, Data Collection, Data Ingestion

This guide aims to provide a complete outline of the following:

Scope
Integration Platforms
Integration

Scope

Once you complete integrating Insider’s Web SDK, you can immediately start getting data about your customers, purchase and revenue tracking, and customer identification. You can use dynamic content elements to personalize your users’ experience, create advanced segmentation with the help of attributes, and target your users with Email, SMS, WhatsApp, and Facebook Custom Audiences channels.

With Insider’s Web SDK, you can:

Set events and attributes, and update attributes,
Keep track of users’ visited products,
Detect the page types on the website, and the actions taken on these pages,
Track customer behavior,
Track purchase history along with the details of purchased products,
Share consent information for various channels with Insider,
Unify your user data across platforms,
Get accurate metrics such as conversions, conversion rates, revenue, etc.,
Set initialization rules to reinit the Insider API where needed and applicable.

Integration Platforms

You can configure your integration via one of the various methods of your choosing:

Source Code Integration: You can add Insider’s Web SDK into the source code of your website. This guide aims to walk you through the steps you should follow to add the Insider script into the <head></head> tags of your website, and test your integration.
Google Tag Manager (GTM): You can add Insider’s Web SDK as a custom HTML tag on your GTM account. You can also use GTM’s data layer variables to define the keys in Insider Queue.
Tealium Tag Manager: You can add Insider’s Web SDK as a tag on your Tealium Tag Manager account.
Adobe Launch: You can add Insider’s Web SDK as a tag on your Adobe Launch account.

Integration

Insider’s Web SDK consists of two steps: Insider Tag (ins.js) and Insider Queue.

Requirements

While integrating the Web SDK, make sure to follow these criteria:

To configure Insider Queue, Insider Tag (ins.js) is required to track user behavior and actions.
Make sure you add Insider’s tracking code (ins.js) to all pages on your website without any modification in the <head></head> tag. This script loads asynchronously by default, and does not block any other script on your website or the rendering of your webpages.
InsiderQueue array needs to be set once on each page. For example, if you set the empty array on the home page and push some values along with it, you do not need to set it again for the same page. If you want to push some values when the user moves to the product page, you need to set an empty array again. Each sample code in this integration displays an example where the empty InsiderQueue array has not been set before.
The empty InsiderQueue array is required to be created before the Insider Tag (ins.js).

The init method should be pushed after the pageview events as displayed in the code samples. The currency method should be pushed for all events and cases that include products.

1. Insider Tag (ins.js)

Insider Tag integration is required to track user behavior on your website, and understand their actions such as purchase and visit history including the items/content they visit, purchase or abandon.

Your title goes here

If you have already implemented the ins.js into your website, you can skip this step. If you have not, follow the reference guide to integrate it into your platform.

2. Insider Queue

Insider Queue array allows you to define page types of your website, push data about these pages and users, define events and attributes, and set initialization rules to reinit the ins.js.

Reiniting the script allows it to read any data that is pushed after the script's first initialization on the first page load. For example, if a user adds an item when they are on the category page, the init method should be triggered to enable the ins.js to read this data. Following this guide, you will call the push method after the Insider script's (ins.js) first initialization in several cases. That's why you will need to use the init method to make sure the ins.js will process the respective pushed data.

In this section, you can see the Queue Properties, and which properties to use to configure:

Customer Identification
User Attributes
Purchase Tracking
Event Tracking
Script Initialization

Queue Properties

InsiderQueue consists of an empty array, push method, type, and value properties.

To push any data with Insider Queue, you need to add a namespace and use the push method. To add the namespace for Insider Queue, you need to add InsiderQueue under the window, and set it as an empty array as follows:

window.InsiderQueue = window.InsiderQueue || [];

Then you need to call the push method with the type property right after this empty array as follows. The following example pushes Women > Tops > Shirts as the value of a category page.

Value property can be optional depending on the data you are pushing. You can see where it is required in the parameter tables in the respective push type.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'category',
    value: ['Women', 'Tops', 'Shirts']
});
window.InsiderQueue.push({
    type: 'init'
});

You will use this push method to define the page types, share data about these pages and users, define events and attributes, and reinit the ins.js.

If you want to push multiple type properties, you need to push them separately as follows. The following example sets InsiderQueue as an empty array under the window, then pushes Women > Tops > Shirts as the value of the category page, and an email address for the user, and reinits the ins.js to pass this data to Insider.

In the following example, you need to reinit the ins.js. The user type and Category Page View event require the ins.js to be reinited to read the data as it will already be inited once on the page load.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'category',
    value: ['Women', 'Tops', 'Shirts']
});
window.InsiderQueue.push({
    type: 'user',
    value: {
        email: 'sample@useinsider.com'
    }
});
window.InsiderQueue.push({
    type: 'init'
});

Customer Identification

With Customer Identification methods, you can set default and custom identifiers for your users, and push user-related information.

Set Default Identifiers

You can set the following 3 attributes as default identifiers for your users:

Key	Description	Data Type
email	Email address	String
phone_number	Phone number	String
uuid	Unique user ID	String

See below for a sample code to set a default identifier for a user.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'set_identifier',
    value: {
        email: 'sample@useinsider.com'
    }
});

Set Custom Identifiers

In addition to the default identifiers, you can also set custom identifiers. This identifier can be any information in any data type.

See below for a sample code to set a custom identifier for a user:

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'set_custom_identifier',
    value: {
        membership_status: 'loyal'
    }
});

In the example above, “membership_status” is the custom identifier with “loyal” as its value.

User Attributes

You can set values for the default attributes Insider allocates for your account in advance. Refer to Default Attributes Populated by Partners for all or web-sourced attributes, or see below to view the list of attributes.

Attribute	Description	Data Type	Sample Value	Required
gender	Gender of the user. The values can be F or M.	String	M	No
birthday	Birthday of the user	Datetime	1990-01-14	No
name	Name of the user	String	John	No
surname	Surname of the user	String	Doe	No
age	Age of the user	Number	33	No
email	Email address of the user	String	jdoe@useinsider.com	No
email_optin	Indicates if the user has opted in for emails	Boolean	true	No
phone_number	Phone number of the user in E.164 format	String	+120394879878	No
sms_optin	Indicates if the user has opted in for SMS	Boolean	true	No
language	Language of the user	String	en_US	No
city	City of the user	String	Jakarta	No
country	Country of the user	String	Indonesia	No
uuid	Unique user ID of the user	String	INS123	No
gdpr_optin	Indicates if the user has allowed for cookies	Boolean	true	Yes
whatsapp_optin	Indicates if the user has opted in for WhatsApp messages	Boolean	false	No

Once you set an identifier, and then a user attribute, the attribute will be logged to the respective identified user.

Your title goes here

Make sure to set a user attribute after setting an identifier to push the respective attribute to the respective identified user.

See below for a sample code to set user attributes for a user.

In the following example, you need to reinit the ins.js. The user type requires the ins.js to be reinited to read the data as it will already be inited once on the page load.

window.InsiderQueue = window.InsiderQueue || [];
InsiderQueue.push({
    type: 'user',
    value: {
        "gender": "M",
        "birthday": "1990-01-14",
        "name": "John",
        "surname": "Doe",
        "username": "jdoe",
        "age": 33,
        "email": "jdoe@useinsider.com",
        "email_optin": true,
        "phone_number": "+120394879878",
        "sms_optin": true,
        "language": "en_US",
        "city": "Jakarta",
        "country": "Indonesia",
        "uuid": "INS123",
        "gdpr_optin": true,
        "whatsapp_optin": true
    }
});
window.InsiderQueue.push({
    type: 'init'
});

Set Custom Attributes

In addition to the user attributes, you can also set custom attributes for your users.

Your title goes here

Make sure to push the custom attribute after setting an identifier to push the respective custom attribute to the respective identified user.

See below for a sample code to set custom attributes for a user:

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'attribute',
    value: {
        wallet_point: 250.99
    }
});

In the example above, “wallet_point” is the custom attribute with 250.99 as its value.

Purchase Tracking

Purchase tracking allows you to keep track of your users’ purchases. You need to use the push method on the success pages (i.e. after payment, confirmation pages, etc.) to define the page type as purchase along with the transaction details.

Click to see the keys you need to push in the value.

Key	Description	Data Type	Sample Value	Required
order_id	Order ID of the transaction	String	INS2468	Yes
total	Total price of the transaction including shipping fees and taxes	Float	273.39	Yes
items	The list of purchased items	Array	[{"id": "abc1234", "name": "Blue Dress", "taxonomy": ["Dresses", "Night Dresses", "Long Sleeve"]}]	Yes
id	Unique product ID of the purchased product	String	abc1234	Yes
name	Name of the purchased product	String	Blue Dress	Yes
taxonomy	Category tree of the product	Array	["Dresses", "Night Dresses", "Long Sleeve"]	Yes
unit_price	Price of the purchased product without any discount(s)	Float	100.00	Yes
unit_sale_price	Unit price of the purchased product	Float	95.20	Yes
url	URL address of the purchased product	String	https://push.useinsider.com/dresses/blue-dress-abc1234	Yes
stock	Stock information of the product that shows the number of products left in stock	Number	11	No
color	Color of the product selected by the user	String	Blue	No
size	Size of the product selected by the user	String	S	No
product_image_url	URL address of the product image	String	https://posh.useinsider.com/blue-dress-image	Yes
quantity	Number of products	Number	2	Yes
custom	Custom object that includes custom properties to be collected to Insider database as custom event parameters	Object	{"season": "winter"}	No

See below for a sample code to set the page type as purchase and push the details of the transaction.

In the following example, you need to reinit the ins.js. The Confirmation Page View (Purchase) event requires the ins.js to be reinited to read the data as it will already be inited once on the page load.

In the following example, you need to push the currency method as the purchase property includes product-related information.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'purchase',
    value: {
        "order_id": "INS2468",
        "total": 273.39,
        "items": [{
            "id": "abc1234",
            "name": "Blue Dress",
            "taxonomy": [
                "Dresses",
                "Night Dresses",
                "Long Sleeve"
            ],
            "unit_price": 100.00,
            "unit_sale_price": 95.20,
            "quantity": 2,
            "url": "https://push.useinsider.com/dresses/blue-dress-abc1234",
            "stock": 11,
            "color": "Blue",
            "size": "S",
            "product_image_url": "https://posh.useinsider.com/blue-dress-image",
            "custom": {
                "merchandiser": "store123"
            }
        }, {
            "id": "zxc5678",
            "name": "Yellow T-Shirt",
            "taxonomy": [
                "T-Shirts",
                "Oversize"
            ],
            "unit_price": 75.00,
            "unit_sale_price": 75.00,
            "quantity": 1,
            "url": "https://www.mywebsite.com/en-US/product/zxc5678/",
            "stock": 11,
            "color": "Yellow",
            "size": "L",
            "product_image_url": "https://www.mywebsite.com/product_images/zxc5678.png"
        }]
    }
});
window.InsiderQueue.push({
    type: 'currency',
    value: 'USD'
});
window.InsiderQueue.push({
    type: 'init'
});

If you want to push only the page type information for the success page (i.e. after payment, confirmation), you should push only the type as follows.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'purchase'
});
window.InsiderQueue.push({
    type: 'init'
});

The example above pushes the Purchase (Confirmation Page View) event. To push other page view events, refer to the following Event Tracking section.

Event Tracking

Event tracking allows you to track user actions on your website. You can define events when your users visit a specific page type, add items to their carts, remove these items from their carts, or take any other action.

Triggering Page View Events

You should detect the page type a user is visiting and push it as a page view event. Once you push the page view events, you can use these events to trigger campaigns and create advanced segmentation options. You can push the following default events:

Homepage View Event
Listing Page View Event
Product Page View Event
Cart Page View Event
Confirmation Page View (Purchase) Event

To push any custom page view event, refer to the Triggering Custom Events section.

Homepage View Event

You should push the page type as home when a user is visiting the homepage of your website.
See below for a sample code to push the Homepage View event.

In the following example, you need to reinit the ins.js. The Homepage View event requires the ins.js to be reinited to read the data as it will already be inited once on the page load.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'home'
});
window.InsiderQueue.push({
    type: 'init'
});

As given in the example above, the type value should be string home and start with a lower case.

Listing (Category) Page View Event

You should push the page type as category when a user is visiting the category page of your website.
See below for a sample code to push the Listing Page View event.

In the following example, you need to reinit the ins.js. The Listing Page View event requires the ins.js to be reinited to read the data as it will already be inited once on the page load.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'category'
});
window.InsiderQueue.push({
    type: 'init'
});

As given in the example above, the type value should be a string category and start with a lower case.

To push any values for the category page, you should add the value property and pass the category tree of the respective page in an array as follows.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'category',
    value: ['Women', 'Tops', 'Shirts']
});
window.InsiderQueue.push({
    type: 'init'
});

Product Page View Event

You should push the page type as product when a user is visiting the product page of your website.
See below for a sample code to push the Product Page View event.

In the following example, you need to reinit the ins.js. The Product Page View event requires the ins.js to be reinited to read the data as it will already be inited once on the page load.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'product'
});
window.InsiderQueue.push({
    type: 'init'
});

As given in the example above, the type value should be string product and start with a lower case.

To push any values for the product page, you should add the value property and pass the product details of the respective page. Click to see the property table.

Property	Description	Data Type	Sample Value	Required
id	Unique product ID of the product	String	abc1234	Yes
name	Product name	String	Blue Dress	Yes
taxonomy	Category tree of the product	Array	["Dresses", "Night Dresses", "Long Sleeve"]	Yes
unit_price	Price of the purchased product without any discount(s)	Float	100.00	Yes
unit_sale_price	Unit price of the product	Float	95.20	Yes
url	URL address of the product	String	https://posh.useinsider.com/blue-dress	Yes
stock	Stock information of the product that shows the number of products left in stock	Number	11	No
color	Color of the product selected by the user	String	Blue	No
size	Size of the product selected by the user	String	S	No
product_image_url	URL address of the product image	String	https://posh.useinsider.com/blue-dress.png	Yes
custom	Custom object that includes custom properties to be collected to Insider database as custom event parameters	Object	{"merchandiser": "store123"}	No

See below for a sample code to push values for the Product Page View event.

In the following example, you need to push the currency method as the purchase property includes product-related information.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'product',
    value: {
        "id": "abc1234",
        "name": "Blue Dress",
        "taxonomy": [
            "Dresses",
            "Night Dresses",
            "Long Sleeve"
        ],
        "unit_price": 100.00,
        "unit_sale_price": 95.20,
        "url": "https://posh.useinsider.com/blue-dress",
        "stock": 11,
        "color": "Blue",
        "size": "S",
        "product_image_url": "https://posh.useinsider.com/blue-dress.png",
        "custom": {
            "merchandiser": "store123"
        }
    }
});
window.InsiderQueue.push({
    type: 'currency',
    value: 'USD'
});
window.InsiderQueue.push({
    type: 'init'
});

Cart Page View Event

You should push the page type as cart when a user is visiting the cart page of your website.
See below for a sample code to push the Cart Page View event.

In the following example, you need to reinit the ins.js. The Cart Page View event requires the ins.js to be reinited to read the data as it will already be inited once on the page load.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'cart'
});
window.InsiderQueue.push({
    type: 'init'
});

As given in the example above, the type value should be string cart and start with a lower case.

To push any values for the cart page, you should add the value property and pass the product details of the respective page. Click to see the property table.

Property	Description	Data Type	Sample Value	Required
shipping_cost	Shipping cost of the item(s) in the cart	Float	7.99	No
total	Total price of the cart item(s) including shipping fees and taxes	Float	273.99	Yes
items	The list of cart items	Array	[{"id": "abc1234", "name": "Blue Dress", "taxonomy": ["Dresses", "Night Dresses", "Long Sleeve"]}]	Yes
id	Unique product ID of the product	String	abc1234	Yes
name	Product name	String	Blue Dress	Yes
taxonomy	Category tree of the product	Array	["Dresses", "Night Dresses", "Long Sleeve"]	Yes
unit_price	Price of the purchased product without any discount(s)	Float	100.00	Yes
unit_sale_price	Unit price of the product	Float	95.20	Yes
quantity	Number of items	Number	2	Yes
url	URL address of the product	String	https://posh.useinsider.com/blue-dress	Yes
stock	Stock information of the product that shows the number of products left in stock	Number	11	No
color	Color of the product selected by the user	String	Blue	No
size	Size of the product selected by the user	String	S	No
product_image_url	URL address of the product image	String	https://posh.useinsider.com/blue-dress.png	Yes
custom	Custom object that includes custom properties to be collected to Insider database as custom event parameters	Object	{"merchandiser": "store123"}	No

See below for a sample code to push values for the Cart Page View event.

In the following example, you need to push the currency method as the purchase property includes product-related information.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'cart',
    value: {
        "shipping_cost": 7.99,
        "total": 273.39,
        "items": [{
            "id": "abc1234",
            "name": "Blue Dress",
            "taxonomy": [
                "Dresses",
                "Night Dresses",
                "Long Sleeve"
            ],
            "unit_price": 100.00,
            "unit_sale_price": 95.20,
            "quantity": 2,
            "url": "https://posh.useinsider.com/blue-dress",
            "stock": 11,
            "color": "Blue",
            "size": "S",
            "product_image_url": "hhttps://posh.useinsider.com/blue-dress.png",
            "custom": {
                "merchandiser": "store123"
            }
        }, {
            "id": "zxc5678",
            "name": "Yellow T-Shirt",
            "taxonomy": [
                "T-Shirts",
                "Oversize"
            ],
            "unit_price": 75.00,
            "unit_sale_price": 75.00,
            "quantity": 1,
            "url": "https://posh.useinsider.com/yellow-tshirt/",
            "stock": 11,
            "color": "Yellow",
            "size": "L",
            "product_image_url": "https://posh.useinsider.com/yellow-tshirt.png"
        }]
    }
});
window.InsiderQueue.push({
    type: 'currency',
    value: 'USD'
});
window.InsiderQueue.push({
    type: 'init'
});

Confirmation Page View Event

You should push the page type as purchase when a user is visiting the confirmation page of your website.
See below for a sample code to push the Purchase (Confirmation Page View) event.

In the following example, you need to reinit the ins.js. The Confirmation Page View (Purchase) event requires the ins.js to be reinited to read the data as it will already be inited once on the page load.

window.InsiderQueue = window.InsiderQueue || [];
window.InsiderQueue.push({
    type: 'purchase'
});
window.InsiderQueue.push({
    type: 'init'
});

As given in the example above, the type value should start with a lower case.

Triggering Cart Events

Add to Cart Event

You should push the Add to Cart event when a user adds an item to their cart. This event updates the cart property under the InsiderQueue array, and updates the storages. id, price, and quantity properties are required to push this event.

See below for a sample code to push the Add to Cart event.

If you have set the empty InsiderQueue array on the page you are pushing this event before, you do not need to set it again.

In the following example, you need to push the currency method as the purchase property includes product-related information.

window.InsiderQueue.push({
    type: "add_to_cart",
    value: {
        "id": "abc1234",
        "name": "Blue Dress",
        "taxonomy": [
            "Dresses",
            "Night Dresses",
            "Long Sleeve"
        ],
        "unit_price": 100.00,
        "unit_sale_price": 95.20,
        "quantity": 2,
        "url": "https://posh.useinsider.com/blue-dress",
        "stock": 11,
        "color": "Blue",
        "size": "S",
        "product_image_url": "https://posh.useinsider.com/blue-dress.png",
        "custom": {
            "merchandiser": "store123"
        }
    }
});
window.InsiderQueue.push({
    type: 'currency',
    value: 'USD'
});

Remove from Cart Event

You should push the Remove from Cart event when a user removes an item from their cart. This event updates the storage and the cart property under the InsiderQueue array. id, price, and quantity properties are required to push this event.

See below for a sample code to push the Remove from Cart event.

If you have set the empty InsiderQueue array on the page you are pushing this event before, you do not need to set it again.

In the following example, you need to push the currency method as the purchase property includes product-related information.

window.InsiderQueue.push({
    type: 'remove_from_cart',
    value: {
        "id": "abc1234",
        "name": "Blue Dress",
        "taxonomy": [
            "Dresses",
            "Night Dresses",
            "Long Sleeve"
        ],
        "unit_price": 100.00,
        "unit_sale_price": 95.20,
        "quantity": 2,
        "url": "https://posh.useinsider.com/blue-dress",
        "stock": 11,
        "color": "Blue",
        "size": "S",
        "product_image_url": "https://posh.useinsider.com/blue-dress.png",
        "custom": {
            "merchandiser": "store123"
        }
    }
});
window.InsiderQueue.push({
    type: 'currency',
    value: 'USD'
});

Triggering Custom Events

In addition to the default Homepage View, Listing Page View, Product Page View, Cart Page View, Confirmation Page View (Purchase), Add to Cart, and Remove from Cart events, you can also push custom events.

The value property should be an array.
The event_name and event_parameters properties are required for the value property.

See below for a sample code that pushes the event named ins_event with the source, url, and name event parameters.

window.InsiderQueue.push({
    type: 'custom_event',
    value: [{
        event_name: 'ins_event',
        event_parameters: {
            "source": "web",
            "url": 'https://posh.useinsider.com',
            "name": "insiderevent"
        }
    }]
});

Script Initialization

You should init the ins.js for several cases. These include pushing:

Pageview events
user property
currency property
Single page applications

Reiniting the script allows it to read any data that is pushed after the script's first initialization on the first page load. Following the code samples, you can see that the init method is pushed to make sure the ins.js processes the respective pushed data.

The init method does not require the value property.

You should push this method for your single page websites. Refer to Insider Tag on Single Page Applications (SPA) for further examples.

Apart from the exceptional cases listed above, you can push the init method whenever initialization is required.

window.InsiderQueue.push({
    type: 'init'
});

Was this article helpful?

What's Next

Table of contents

Scope
Integration Platforms
Integration