JavaScript

To get started with JavaScript, you can add an HTML script snippet to each page in your application. By default, this will start tracking Web Session and Page View events, and will allow you to start sending custom events.

The JavaScript SDK is great for client-side tracking and can be used in conjunction with our API to send server-side events.

Installation

Script for Non-AMD Sites

Please note, the instructions in this section are only valid for sites that don’t use AMD (e.g. require.js). 

First, you’ll need to asynchronously load our script into your site. Add this script in either your site’s  or tag:

<script type="text/javascript">
        (function(apiKey) {
                var ind = document.createElement('script');
                ind.src = '//cdn.indicative.com/js/1.0.2/Indicative.min.js';
                ind.type = 'text/javascript';
                ind.async = 'true';
                var ind_init = false;
                ind.onload = ind.onreadystatechange = function() {
                    var rs = this.readyState;
                    if (ind_init || (rs && rs != 'complete' && rs != 'loaded')) return;

                    ind_init = true;
                    Indicative.initialize(apiKey);
                    Indicative.buildEvent('Page View');
                };

                var s = document.getElementsByTagName('script')[0];
                s.parentNode.insertBefore(ind, s);
        })("YOUR_API_KEY_GOES_HERE");
</script>

This script tag asynchronously loads Indicative.js from our CDN and initializes the JavaScript code with your unique API key. You will need to set your API key in quotes where it says “YOUR_API_KEY_GOES_HERE”. You can find a list of all of your projects and appropriate API keys here.

To choose between your site’s  or  tags, note the pros and cons of each. The  tag will allow you to access the Analytics object earlier (on load), however your site will not load until everything in the  tag is loaded. So, if you do not need the Analytics object immediately, we recommend putting this snippet in the  tag.

If you would like a version of the script that does not ask require.js, please reach out to support@mparticle.com. 

Example Module for Require.js Enabled Sites

requirejs.config({    paths: {        Indicative: '//cdn.indicative.com/js/1.0.2/Indicative.min',    }});define(['Indicative'], function (Indicative) {    Indicative.initialize('5b440efe-603a-494d-8c89-4c55a4d489f6');    Indicative.buildEvent('Page View');});

Building and Sending an Event

Recording an event is easy and customizable. It can be as simple as:

Indicative.buildEvent('event-name');

The above line will build and send an event named ‘event-name’ with a unique ID set as a random UUID.

You can also add your own user IDs and important properties to every event to further enrich your data for more impactful analyses like in the example below.

Indicative.buildEvent('Purchase', 'unique-user-id', {    billing_status: 'Premium',     payment_plan: 'Annual'});

Some properties may be stored as a persistent cookie, so that every page can share some common properties or unique ID instead of explicitly passing them every time you build an event. Additionally, Indicative automatically tracks some properties by default; learn more. 

Validating Integration

Open up the Debug Console in Analytics to view all incoming events. You should expect to see your data in Analytics

Additional Information

For advanced JavaScript settings, please refer to our documentation.

For a full list of our Analytics Object API, please click here.

Advanced Settings

Callbacks

Indicative also allows callbacks, which will be fired after a successful or unsuccessful stat post. You can include a callback function in any of the buildEvent methods, like so:

var callbackFn = function () {
        console.info("callback!");
};

Indicative.buildEvent('event-name', callbackFn);
Indicative.buildEvent('event-name', 'unique-user-id', callbackFn);
Indicative.buildEvent('event-name', 'unique-user-id', {propertyName: 'propertyValue'}, callbackFn);
Indicative.buildEvent('event-name', {propertyName: 'propertyValue'}, callbackFn);

With so many different ways to build an event, you’ll have a lot of flexibility to build and send any custom events you need. For further references, refer to the Analytics object API table below.

Stateful Variables

We allow you to set stateful variables across every page. Stateful variables are stored as a persistent cookie, so every page will be able to share the same common properties and a uniqueID for the user triggering events on your site. Anywhere in your JavaScript, after Analytics was initialized, call:

Indicative.setUniqueID("unique-user-id");

This will allow you to log events without having to refer to a unique ID every time you build an event. Analytics also allows for stateful properties, as well, which can be added with the following calls:

Indicative.addProperty('propertyName', 'propertyValue');
Indicative.addProperties({propertyName: 'propertyValue', propertyName2: 'propertyValue2'});
Indicative.addProperties([{propertyName: 'propertyValue'}, {propertyName2: 'propertyValue2'}]);

These properties will be appended to subsequent event calls. They will not override the properties passed into a buildEvent call, rather append to the list of properties. If a common property isn’t applicable anymore, call:

Indicative.removeProperty('propertyName');

This will remove a single property. It’s just as easy to clear the entire common properties list:

Indicative.clearProperty();

How to Track Links

Tracking href link clicks can be challenging, because once the page changes we lose our chance to fire an event. To solve this problem, we’ve added a callback to our build object. Use the following function to track link clicks and then send the user to the linked page:

function linkClick (event, linkName) {
        var url = event.target.getAttribute('href');
        console.info(event);
        event.preventDefault();

        Indicative.buildEvent("Link Click", {Link_Name: linkName}, function () {
            console.info("go to site");
            if (url) {
                window.location = url;
            }
        });
}

To call this function in your HTML, set up a link like so: 

<a onclick="linkClick(event, 'home')" href="home.html">Home</a>

How to Track Web Sessions

We’ve implemented Web Sessions in our JavaScript SDK track users’ web sessions with just a slight change to one line of your code. If a user has no activity for 30 minutes (no events are fired locally), upon any new event activity, the JavaScript SDK will also fire a “Web Session” event to indicate the start of a new Web Session.

Note: The window of inactivity is customizable, but defaults to 30 minutes, with industry standards.

How to Integrate

Where you see the line in this snippet:

Indicative.initialize(apiKey);

Alter it to read:

Indicative.initialize(apiKey, {recordSessions: true});

If you want to alter the inactive session length, change the line to be this instead:

Indicative.initialize(apiKey, {recordSessions: true, sessionsThreshold: 5});

where 5 signifies 5 minutes.

Automatic Tracking

We automatically track the following properties:

• browser: browser
• operating system: browser_os
• device: browser_device
• referrer: browser_referrer
• language: browser_language
• page title: page_title
• url: page_url

We also automatically track marketing channels provided by UTM search parameters. You’ll be able to see the following properties if you have users loading your page with UTM properties in the URL: campaign_source,campaign_medium, campaign_term, campaign_content, and campaign_name. We will also provide these channel properties in their own section of the data panel, titled as User Properties - UTM (category).

How to Track Users Across Subdomains

We support tracking user sessions across various subdomains through the use of our SDK. If the option ‘cookiesOnMainDomain’ is set to true, it will store the cookie on the root domain.

Where you see this line in the snippet: 

Indicative.initialize(apiKey);

Alter it to read: 

Indicative.initialize(apiKey, {recordSessions: true, sessionsThreshold: 30, cookiesOnMainDomain: true });

Whenever the cookiesOnMainDomain option is set to true, it is recommended that you include the base domain name. If it is not set, our SDK will attempt to figure it out by taking the last two tokens of the domain name, and in some cases it may be invalid values (e.g. .com.mx).

To explicitly add the domain name, add the domainName to the initialization parameters. 

Indicative.initialize(apiKey, {recordSessions: true, sessionsThreshold: 30, cookiesOnMainDomain: true, domainName: ‘example.com.mx’ })

Warning: Changing or enabling this option may break existing cookie tracking.

Aliasing

Analytics supports aliasing between anonymous IDs and user IDs to allow customers to unify event streams submitted with separate unique keys. Click here for a full walkthrough of Analytics’ aliasing protocol.