How Can We Help?
Identification SDK Module
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 module related specifically to identifying your users.
| 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. |
Overview of User IDs
Cortex relies on unique user IDs in order to collect behavioral event data and generate predictions for each of your users. The JavaScript SDK provides various ways to set, generate, and retrieve these unique user ids.
| Function | Description |
| api.setUserId | Specify an id to associate with event data sent to Cortex’s servers. |
| api.getUserId | Retrieve the user id that has been set with api.setUserId. If an id has not yet been set and api.getUserId is run, Cortex will generate a unique user id (UUID) and store this value in a vidoraUserId cookie |
| api.getUUID | Generate a unique user id (UUID) and store this value in a vidoraUserId cookie |
If you have unique ids for your users, Cortex recommends specifying this id (userId) using api.setUserId. Setting the id allows you to tie predictions from your machine learning models back to a known list of users, so that you can consider model outputs in conjunction with other user information that you may have. Once you have set the userId, any behavioral event sent to Cortex during the user’s session will be automatically associated with that ID.
If you do not have a unique id (e.g. for anonymous users), Cortex can handle user tracking for you by generating a unique user id (UUID) and storing the value in a vidoraUserId cookie. A cookie will be created when any of three things occur:
- getUUID is run
- getUserId is run when an id has not been set using api.setUserId
- A user’s id has not been set and an event is submitted for that user
If you wish to avoid creating a cookie, ensure that (1) no calls to api.getUUID are run, (2) calls to api.getUserId are not made prior to setting the user id, and/or (3) a user id is set with api.setUserId prior to sending an event for the user.
Note that if you have more than one identifier for each user, you may add an ID Mapping data source to Cortex in order to reconcile these disparate IDs into a unified profile for each user.
The following sections describe how to call various functions contained within the Identification module of the JavaScript SDK.
Setting the UserId
Using the api.setUserId function, you can specify a userId to associate with event data sent to Cortex’s servers. When a userId is set, subsequent events that occur on the page will be assigned to that user. Note that api.setUserId should be called on every page load to ensure that data is sent from across your entire site.
If api.getUUID is run after a userId is set, events will still be sent with the userId that you specified, but Cortex will also generate a unique user id (UUID) and store this value in a vidoraUserId cookie.
Request
api.setUserId(userId)
Parameters
| Parameter | Type | Description |
| userId | string | The user id value to send to Cortex’s servers. It is important that each user, both logged in and anonymous, is assigned a unique id. |
Example 1: Array Arguments
The setUserId function is executed on the Cortex’s API Object once the API has loaded, setting the userId to “7baffc459cd6047b7a059f697681c04e”:
window.vidora.push(["setUserId", "7baffc459cd6047b7a059f697681c04e"]);
Example 2: Closures
Similar to the prior example, the closure will execute api.setUserId once the API has loaded, setting the userId to “7baffc459cd6047b7a059f697681c04e”:
window.vidora.ready(function(api) {
api.setUserId("7baffc459cd6047b7a059f697681c04e");
});
Getting the UserId
Once the userId has been set with the api.setUserId function, the api.getUserId function retrieves the userId and prints this value to the developer’s console.
If api.getUserId is run but you have not set an id for the user, Cortex will generate a unique user id (UUID) and store this value in a vidoraUserId cookie.
Request
api.getUserId()
Since the api.getUserId function retrieves a value, it must be run with closures rather than array arguments.
Example: Closures
Once the API has loaded, the api.getUserId function gets the userId and prints this value to the developer’s console.
window.vidora.ready(function(api) {
console.log("UserId: " + api.getUserId());
});
Getting The Unique User Id (UUID)
When the function call api.getUUID is run, Cortex will generate a unique identifier for the user and store this value in a vidoraUserId cookie. For example, if an anonymous user is interacting with your site, a UUID will be generated for this user if the user’s events are submitted to the API. The value of the vidoraUserId cookie can also be accessed by calling api.getUUID. The default expiration date of the vidoraUserId cookie is 2 years since the time it was created.
If an anonymous user is later authenticated, note that you may use an ID Mapping data source to tie together multiple IDs into a single user profile.
Request
api.getUUID()
Since the api.getUUID function retrieves a value, it must be run with closures rather than array arguments.
Example: Closures
Once the API has loaded, the api.getUUID function gets the vidoraUserId cookie value and prints this value to the developer’s console.
window.vidora.ready(function(api) {
console.log("Vidora UUID: " + api.getUUID());
});
Related Links
Still have questions? Reach out to support@mparticle.com for more info!