How Can We Help?

SDK Overview

Cortex’s JavaScript SDK provides a robust set of functionality for developers to interface with Cortex directly from the client-side. This document provides an overview of the SDK, as well instructions for how to initialize the API and access its functions.

SDK Functionality

The SDK’s methods are divided into 3 distinct modules: Identification, Behavioral, and Decision. Click these links for detailed reference of the specific methods available across these three areas.

Module Description
Identification Set, generate, and retrieve a unique ID for each of your users.
Behavioral Send behavioral events to Cortex as users browse your site. These events serve as the basis for predictions made by your ML Pipelines.
Decision Deploy your ML Pipelines through a decisioning framework which dynamically determines the right onsite experience to provide each user. These decisions are based on predictions from your ML Pipelines, and can be configured to optimize for conversions, revenue, or more.

Initializing Cortex’s API

Load Cortex’s JavaScript API

Depending on which modules you’d like to access, the SDK can be loaded into the client with one of the following script tags:

Identification and Behavioral Modules

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

Identification, Behavioral, and Decision Modules

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

These 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.6.0).

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>

Multiple SDK Instances

If you have multiple Cortex accounts with different API keys, you can load multiple instances of the SDK by adding multiple snippets. You can modify the window object that the SDK is initialized on by modifying the parameters in the snippet:

<script>(function(...){ ... })(window,document,"vidora",ACCOUNT1_API_KEY);</script>
<script>(function(...){ ... })(window,document,"vidora_account2",ACCOUNT2_API_KEY);</script>
<script src="https://assets.vidora.com/js/vidora-client.1.x.x.min.js" type="text/javascript"></script>
<script>
  // Access each instance as defined by the parameters above.
  window.vidora.push([...]);
  window.vidora_account2.push([...]);
</script>

Cortex’s Global and API Objects

After including either the loader snippet or cortex-client.js, any call to the Cortex Global Object (window.vidora) is valid. All calls to Cortex’s API must route through window.vidora and will queue until the Cortex API has finished loading.

The window.vidora.ready call will allow the Cortex API to complete loading and produce a Cortex API object that you can safely access. For example:

window.vidora.ready(function(api) {
   console.log("Vidora API finished initializing!");
   api.getUUID();
});

Calling API Functions

Function calls to Cortex’s JavaScript API can be made with array arguments or with closures.

Calls with Array Arguments

Push an array to the Cortex API Object, with the first element specifying the function name and subsequent values specifying the arguments to be sent to the function call. Note, you cannot get values calling an API function with a push format.

Request

window.vidora.push([functionName, arguments]);

Parameters

Parameter Type Description
functionName string The name of the API function.
arguments string A string of a single argument or an array of argument strings.

Calls with Closures

While the push format will not allow you to get values, accessing the API with a closure lets you call any function within the Cortex API Object.

Request

window.vidora.ready(function(api) {   
  api.functionName(arguments);
});

Parameters

Parameter Type Description
closure function A function that takes a single argument, which is the Cortex API Object.

Miscellaneous

Handling Ad Blockers

When a user has enabled certain ad blockers, Cortex-powered modules may be prevented in the browser. Cortex’s JavaScript API allows you to configure a content delivery network (CDN) to bypass these ad blockers using the below four steps:

  1. Set up a CDN in front of origin domain alloy.vidora.com, so that requests are routed through the CDN rather than made directly to a Cortex domain.
  2. Do not cache Cortex’s responses in the CDN, so that every request is redirected to Cortex’s servers.
  3. Import your SSL certificate to the CDN so that HTTPS allows the client to connect with the CDN.
  4. Ensure that all requests to Cortex’s APIs and links to Cortex assets use the CDN domain.

Security

Event data is always sent with HTTPS using TLS to Cortex’s servers. We do not allow SSL 3.0 due to potential for the POODLE Attack.

Each Cortex API Key is securely generated and revocable on Cortex’s servers.

If signed authentication is necessary, please see documentation on calling our Personalization API with server side integration. Please note that one cannot mix signature authentication and token-only authentication for the same service calls, as the signature would no longer be useful for authentication.

Tested Browsers

The JavaScript API goes through automated and manual tests to ensure cross-browser functionality. We currently test on Internet Explorer 9-11, Firefox, Chrome, Safari, Opera, and mobile browsers on iOS and Android.

Unsupported browsers, such as IE6, fail gracefully; a user viewing a site with IE6 will see the site as it would appear without Cortex’s script-loading, and user events will not be collected.

Please contact support@mparticle.com if you find any issues with a particular browser or have additional requirements!

Related Links

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

Table of Contents