How Can We Help?

Segment – Client Side

A Data Source in Cortex represents an integration between your Cortex account and a third-party platform used for enterprise data storage. Once your source is connected, data will regularly flow into Cortex where it can be used to build Machine Learning pipelines.

Segment collects user events and traits from your web & mobile apps and provides a complete data toolkit to every team in your company.  This provides a single view of the customer and allows you to integrate your data with numerous sources.  In this guide, we’ll walk through how to integrate using the Cortex-Segment Client Side Integration to enable Real Time Decisioning using existing event tracking through the Segment SDK.

Updating Segment SDK Installation

Built into the Segment Analytics.js SDK, the global analytics object will emit events whenever you call alias, group, identify, track or page. This on method can be used to set listeners for these events and run custom code. This makes it very easy to update the Segment SDK Installation to forward all Client Side data automatically to the Cortex SDK.

Step 1: Install the Cortex SDK

For this integration, we will want to initialize the version of the SDK that includes the Decisioning Module, which is how we will take advantage of the Real Time Client Side tracking to make Real Time Decisions.

<script src="https://assets.vidora.com/js/vidora-client-rt.1.x.x.min.js" type="text/javascript"></script>

This script tags will load the latest version of the SDK, so that you don’t have to manually update your JavaScript embed when a new version is released. Alternatively, you may hardcode a particular version of the SDK (the latest being 1.5.3).

Add Loader Snippet

Paste the following loader snippet with your API Key in the head section of your html document before the Cortex script tag and before any calls are made to the Cortex Global Object.

<script>(function(n,_,i,u,a){var r={_q:[]};r.ready=r.push=function(n){r._q.push(n)};var E="vidora_ns";E in n||(n[E]=[]),n[E].push(i),i in n||(n[i]=r),n[i].ready(function(n,_){_._i(u,i,a)})})(window,document,"vidora",YOUR_API_KEY);</script>

<script src="https://assets.vidora.com/js/vidora-client.1.x.x.min.js" type="text/javascript"></script>

Step 2: Update the .on Method in the Segment SDK

The .on() method will listen for any events to be tracked to the Segment SDK, and the emitter will run before events are processed by the Segment integration.  It is within this method that we can forward all events to Cortex, automatically.

analytics.on(method, callback);

method

String

Name of the method to listen for

callback

Function

A function to execute after each emitted method, taking three arguments: event, properties, options

Track

Below is how to automatically forward all Track events to the Cortex SDK

analytics.on('track', function (event, properties, options) { 
    vidora.ready((api) => { 
        api.send(event, null, { params: properties }); 
    }); 
});

Identify

Below is how to automatically forward all Identify events to the Cortex SDK

analytics.on('identify', function (event, properties, options) { 
    vidora.ready((api) => { 
        api.send(event, null, { params: properties }); 
    }); 
});

Recording an Event without Sending

The api.notify function allows you to record user behavioral events in the client without sending them to Cortex’s analytics servers. This functionality is useful if you are already sending behavioral events from the server (e.g. through Cortex’s Behavioral API or Segment’s Server Side integration), but would like to make client-side decisions based results from a real-time ML pipeline. The api.notify function accomplishes this by recording client-side events so that real-time decisions can incorporate behavior from the current session, while ensuring that duplicate events are not sent to Cortex from both the client and the server.

Simply change

api.send(event, null, { params: properties }

to

api.notify(event, null, { params: properties }

Step 3: Retrieve Decisions

Once the SDK is set up and Pipelines are created in Cortex, these decisions can be retrieved through the SDK indicating the ideal action to take for each user.

The first step is to load the project from Cortex where the Decision Prediction is being created:

api.getProject(projectId)

With this project loaded, decisions can now be retrieved in real time for each user:

project.getDecision(function(decision) { 

    // user-defined logic to act on the decision 

});

Within the Decision object, an action will be returned indicating the ideal action for each user:

decision.action;

Step 4: Tying Events to Decisions

In order for the SDK to continually learn and optimize over time, it is important to create a feedback loop indicating that a decision from the SDK was taken and shown to the end user. This will enable the SDK to learn behaviors over time to ensure it is always returning optimal decisions.  Tying the Treatment Event to the Decision can be done directly in the Segment.track call.

For example, if a decision is being made to Show or Not Show a paywall, then an event tracking a ‘shown_paywall’ event should be sent indicating this decision was taken based on the response from the SDK:

segment.track("shown_paywall", decision.tieEventToDecision())

Related Links

Still have questions? Reach out to support@mparticle.com for more info!

Table of Contents