Web SDK Integration Guide

Suggested Readings: Guide to Events and Attributes, Data Collection, Data Ingestion

Insider’s Web SDK enables seamless data collection and real-time personalization by capturing detailed data on user attributes, behaviors, and interactions across your website. Once the integration is complete, you can immediately use this robust and unified data for customer identification, purchase tracking, and revenue analysis. This provides the foundation to personalize your users’ experience with dynamic content, create advanced segmentation with the help of attributes, and target users effectively across channels like Email, SMS, WhatsApp, and Facebook Custom Audiences channels.

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

• Integration platforms
• Integration components
• Integration
  • Insider Queue array
  • Insider tag
  • User data - Attributes
  • User data - Currency
  • User data - Cart (optional)
  • Page data - Home
  • Page data - Category
  • Page data - Product
  • Page data - Cart
  • Page data - Purchase
  • Page data - Other
  • Initialization push
  • Add to cart and remove from cart
  • Custom events
• Configuration for Google Tag Manager

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 (e.g., viewing a page, adding an item to cart, completing a purchase, etc.).
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.

With a complete Insider Web SDK integration, you can:

• Set and update attributes,
• Keep track of users’ visited products,
• Detect the page types and actions taken on these pages,
• Track customer behavior and purchase history,
• Share consent information with Insider,
• Unify user data across platforms,
• Get accurate metrics like conversions, conversion rates, and revenue,
• Set initialization rules to trigger data processing where needed.

Integration platforms

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

• Source code integration: This guide primarily focuses on adding scripts directly to your website's source code.
• Google Tag Manager (GTM): A comprehensive set of details for GTM integration is provided in a dedicated section. You are required to follow this document along with that specific section. The principles can also be adapted for other tag managers.
• Other tag managers: You can consult the Insider One team for tag managers like Tealium Tag Manager or Adobe Launch.

Required implementation flow

This section provides a high-level overview of the integration flow. It introduces the main components of the SDK setup. You can follow the rest of this guide to configure these components.

A typical integration follows an order as below:

• The InsiderQueue array must be defined before the Insider tag loads. This is the queue where all integration data will be pushed.
• Then, load the Insider tag (ins.js).
• Push the user data: attributes (type: ‘user'), the user’s current currency (type: 'currency') if needed, and items currently in the user's cart if preferred (type: 'cart'). You can push these components in any order.
• After the user data, push the correct page type to define the current page context (e.g., type: 'home', type: 'product').
• At the end, push type: 'init' to signal Insider tag that the full data is ready. This triggers a page view event and updates the user profile. This is the most critical push in the Insider's Web SDK.
• Event pushes such as type: 'add_to_cart', type: 'remove_from_cart', and type: 'custom_event' should be triggered by your site logic as needed, but only after the Insider tag is loaded.

Integration

You can follow these steps to configure the integration.

Insider Queue array

The InsiderQueue is a JavaScript array you define on your website. Its purpose is to collect all user attributes, page details, and events before the Insider tag processes them.

To implement it, you must add the following line of code to every page where you will use the SDK. You must place this script before the Insider tag (ins.js).

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

Insider Tag (ins.js)

Insider Tag integration is the core script that tracks user behavior, such as purchase and visit history, processes the data from the InsiderQueue, and enables all Insider functionalities on your website. Below, you can find the example script for Insider tag.

<script async src="//{partnerName}.api.useinsider.com/ins.js?id={partnerId}"></script>

User data - Attributes

With the type: 'user' method, you define your user's default and custom attributes. This allows Insider to identify, unify, and track users correctly based on your Identity Resolution Management settings.

It is highly recommended to push all available user information every time you send a type: ‘user’ push. This practice ensures data consistency across all user identification and unification scenarios.

While defining your user’s attributes, you must follow the data table below for data types and requirements.

Below, you can find the example script for the type: ‘user’ method of Insider Web SDK.

window.InsiderQueue.push({
    type: 'user',
    value: {
        "uuid": "INS123",
        "gender": "M",
        "birthday": "1990-01-14",
        "gdpr_optin": true,        
        "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",
        "whatsapp_optin": true,
        "custom": {
            "user_lifetime": 23,
            "membership_type": "Silver"
        }        
    }
});

User data - Currency

With the type: ‘currency’ method, you define the currency that is currently used by the user to view your website. This method is essential for customers supporting multiple currencies. It is used while converting the price information in the InsiderQueue events and using the correct currency while displaying a campaign with price information.

Below, you can find the example script for the type: ‘currency’ method of Insider Web SDK.

window.InsiderQueue.push({
    type: 'currency',
    value: 'USD'
});

You can contact the Insider One team to skip the type: 'currency' method if you only allow a single currency on your website.

User data - Cart (optional)

The type: ‘cart’ method is used for defining the page type as a cart page and updating the user’s cart information for Insider. This means your user’s data will already be updated in every cart page view. However, if you are sensitive about the up-to-dateness of your cart data, you can use this method on every page to update the user’s cart information. This way, Insider will be up-to-date about the user’s cart regardless of page type. If not, you can skip this section and use the type: ‘cart’ method for defining cart page type and sending cart page view.

While defining your user’s cart items, you must follow the data table below for data types and requirements.

Below, you can find the example script for the type: ‘cart’ method of Insider Web SDK.

window.InsiderQueue.push({
    type: 'cart',
    value: {
        "shipping_cost": 7.99,
        "total": 200.39,
        "items": [{
            "id": "abc1234",
            "name": "Blue Dress",
            "taxonomy": [
                "Dresses",
                "Night Dresses",
                "Long Sleeve"
            ],
            "unit_price": 90.00,
            "unit_sale_price": 75,
            "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"
            }
        }, {
            "id": "zxc5678",
            "name": "Yellow T-Shirt",
            "taxonomy": [
                "T-Shirts",
                "Oversize"
            ],
            "unit_price": 60.00,
            "unit_sale_price": 50.39,
            "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"
        }]
    }
});

Page data - Home

The type: ‘home' method defines the page type as home. With the type: ‘init’ method, it sends a Home Page View (home_page_view) event, which you can see on the User Profiles. You can define only one product per product page.

For this push to work, type: 'init' must be pushed once per page afterward.

Below, you can find the example script for the type: ‘home’ method of Insider Web SDK. Since the default parameters of Homepage View are sent automatically, you can only define custom parameters for this page type.

window.InsiderQueue.push({
    type: 'home',
    value: {
      "custom": {
        "home_page_version": "version1",
        "daily_count": 14
      }
    }
});

Page data - Category

The type: ‘category' method defines the page type as category/listing. With the type: ‘init’ method, it sends a Listing Page View (listing_page_view) event, which you can on the User Profiles.

For this push to work, type: 'init' must be pushed once per page afterward.

Below, you can find the example script for the type: ‘category’ method of Insider Web SDK.

window.InsiderQueue.push({
    type: 'category',
    value: {
        breadcrumb: ['Dresses', 'Night Dresses'],
    },
});

Page data - Product

The type: ‘product' method defines the page type as home. With the type: ‘init’ method, it sends a Product Page View (product_detail_page_view) event, which you can observe on the User Profiles. You can define only one product per product page.

While defining the product page data, you must follow the data table below for data types and requirements.

For this push to work, type: 'init' must be pushed once per page afterward

Below, you can find the example script for the type: ‘product’ method of Insider Web SDK.

window.InsiderQueue.push({
    type: 'product',
    value: {
        "id": "abc1234",
        "groupcode": "abd5678",
        "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"
        }
    }
});

Page data - Cart

The type: ‘cart' method defines the page type as cart and updates the user’s cart information for Insider. With the type: ‘init’ method, it sends a Cart Page View (cart_page_view) event, which you can observe on the User Profiles.

The User data - Cart method is used for updating the user’s cart information for Insider. Since it also defines the page type as cart, you just need to push/fire the type: ‘cart’ method once on your cart page. If you already added (or fired) this method on your cart page to update the user’s cart information, you can skip this section of the integration because the page type is already defined as cart.

While defining cart page data, you must follow the data table below for data types and requirements.

For this push to work, type: 'init' must be pushed once per page afterward.

Below, you can find the example script for the type: ‘cart’ method of Insider Web SDK.

window.InsiderQueue.push({
    type: 'cart',
    value: {
        "shipping_cost": 7.99,
        "total": 200.39,
        "items": [{
            "id": "abc1234",
            "name": "Blue Dress",
            "taxonomy": [
                "Dresses",
                "Night Dresses",
                "Long Sleeve"
            ],
            "unit_price": 90.00,
            "unit_sale_price": 75,
            "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"
            }
        }, {
            "id": "zxc5678",
            "name": "Yellow T-Shirt",
            "taxonomy": [
                "T-Shirts",
                "Oversize"
            ],
            "unit_price": 60.00,
            "unit_sale_price": 50.39,
            "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"
        }]
    }
});

Page data - Purchase

The type: ‘purchase' method defines the page type as purchase and updates the user’s cart information for Insider. With the type: ‘init’ method, it sends a Purchase (confirmation_page_view) event, which you can observe on the User Profiles. This method is highly crucial for Insider functions.

While defining the purchase page data, you must follow the data table below for data types and requirements.

For this push to work, type: 'init' must be pushed once per page afterward.

Below, you can find the example script for the type: ‘purchase’ method of Insider Web SDK.

window.InsiderQueue.push({
    type: 'purchase',
    value: {
        "order_id": "INS2468",
        "total": 200.39,
        "shipping_cost": 7.00,
        "items": [{
            "id": "abc1234",
            "name": "Blue Dress",
            "taxonomy": [
                "Dresses",
                "Night Dresses",
                "Long Sleeve"
            ],
            "unit_price": 90.00,
            "unit_sale_price": 75.00,
            "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": 60.00,
            "unit_sale_price": 50.39,
            "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",
            "custom": {
                "merchandiser": "store456"
            }
        }]
    }
});

Page data - Other

The type: ‘other' method defines the page type as other. With the type: ‘init’ method, it sends an Other Page View (other_page_view) event, which you can observe on the User Profiles. You can use this method to label any kind of page.

Only the name parameter is used to label the other pages with string data type. This parameter is not required and will be displayed in the User Profiles entries for Other Page View events. You can also use custom event parameters.

For this push to work, type: 'init' must be pushed once per page afterward.

Below, you can find the example script for the type: ‘other’ method of Insider Web SDK.

window.InsiderQueue.push({
    type: 'other',
    value: {
      "name": "landing page v.2",
      "custom": {
        "landed_previously": false,
        "traffic_source": "facebook"
      }
    }
});

Initialization push — A critical step

type: ‘init' is the most critical yet basic method in the Web SDK integration. It acts as the trigger that tells the Insider tag to pass the user and page data you have defined to Insider.

Every time you push this method to InsiderQueue:

• It tells the Insider tag to be initialized if it isn’t initialized yet.
• User data according to the last successful type: 'user' push made will be sent to Insider.
• Page view event, according to the last successful page definition you made, will be sent to Insider.
• It will check which “Rules” (and some other settings) are satisfied to display correct campaigns to correct users.

Below, you can find the example script for the type: ‘init’ method of Insider Web SDK.

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

Add to cart and remove from cart

The type: ‘add_to_cart' and type: ‘remove_from_cart' methods update the user's cart information according to user’s action and sends the related event to Insider: add to cart (item_added_to_cart) or remove from cart (item_removed_from_cart).

While pushing these two events, you must follow the data table below for data types and requirements.

Below, you can find the example script for these two methods of Insider Web SDK.

window.InsiderQueue.push({
    type: "add_to_cart",   // OR  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",
            "item_finish_date": "2021-01-20T00:00:00Z"
        }
    }
});

Custom events

The type: ‘custom_event' method lets you push custom events to Insider with selected parameters. With this method, you can hit nearly all segmenting and targeting use cases based on your business needs that are not covered via default methods.

While pushing these two events, you must follow the data types of your default custom parameters that you defined on the Attributes and Events page.

Below, you can find the example script for the custom event method of Insider Web SDK. No parameter id required except for event_name.

window.InsiderQueue.push({
    type: 'custom_event',
    value: [{
        event_name: 'name_of_your_custom_event', // as you defined
        event_parameters: {
            "quantity": 3, // number-typed default parameter, 
            "custom": {
                "domain_group_id": 123, // number-typed custom parameter example
                "action_taken": "abc12", // string-typed custom parameter example
                "isRepeated": "true", // boolea-typed custom parameter example
                "user_acq_time": "2021-01-20T00:00:00Z" // in  datetime-typed custom parameter example
            }
        }
    }]
});

Configuration for Google Tag Manager

This section provides detailed guidelines for integrating the Insider Web SDK using Google Tag Manager. The principles can be adapted for other tag management systems, as well.

In the table below, you can find all the tags to be created and the settings for correct firing.