Decision Module

Vidora’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 optimizing dynamic decisions. The Decision module contains all functionality needed to enable your team with high-performing decisions, made in real-time using both historical and in-session data. Dynamic decisioning includes use cases like next-best-action and next-best-offer.

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 Decision Optimization

Decision optimization allows our partners to dynamically determine in real-time which experience should be served to each user in order to achieve a higher-level business objective (e.g. maximize likelihood of conversion, maximize net revenue, etc.). Common use cases include next-best-action and next-best-offer.

These decisions are based on underlying predictions generated by a Real-Time Future Events or Uplift pipeline. For example, a pipeline predicting the likelihood subscribing within 10 minutes of seeing a paywall can be used to optimize the decision around whether to show the paywall to a given user at a given time. In another example, a set of pipelines predicting the likelihood of interacting with a particular modal can be used to determine which modal to show in order to encourage the highest value action for that user.

The following sections describe various functions contained within the Decision module of the JavaScript SDK, as well as the objects through which these functions can be accessed.

Configuring the Module

In order to translate predictions into user journey decisions, the JavaScript SDK relies on two pieces of decision logic specified in a configuration: (1) an action threshold, and (2) an explore/exploit setting.

To override the default configuration and add custom business logic to a given pipeline, talk to your account manager or contact support@vidora.com

Action Threshold

Specifies the rule for translating predictions into actions. This rule consists of two settings: field, and value.

Setting Description
Field Which field should be used to set the threshold? Options include (1) prediction score, or (2) prediction percentile.
Value What is the cutoff value above which the user should receive the treatment (i.e. the treatment intervention in an Uplift pipeline, or the trigger event of a Future Events pipeline).

 

By default, Uplift pipelines automatically find the optimal score threshold that will maximize each user’s likelihood of conversion. For example, say the below Uplift pipeline found an optimal score threshold of 0.6 –

  • Pipeline: Predicting the impact of paywall (treatment) vs. no paywall (control) on each user’s likelihood to subscribe within 10 minutes.
  • Action Threshold: Field = prediction score | Value = 0.6

This threshold equates to a default decision rule of: “If the user’s prediction score > 0.6, show them a paywall. Else, do not show the paywall”.

Optionally, you may override this default by setting your own score or percentile threshold. This is only recommended if you would like to optimize for something other than the likelihood of conversion. For example, if there is a cost to treatment you may wish to set a higher threshold so as to avoid incurring cost by treating users who will only be marginally impacted by treatment.

Future Events pipelines use a default percentile threshold of 0.5. For example, consider the below pipeline –

  • Pipeline: Predicting each user’s likelihood to subscribe within 10 minutes of being shown a paywall (treatment).
  • Action Threshold: Field = percentile | Value = 0.5

This threshold equates to a default decision rule of: “If the user’s predicted conversion probability is above the 50th percentile (compared to all predictions in the training data), show them a paywall. Else, do not show the paywall.”

This default threshold can be overridden based on business logic, or optimized based on an analysis of explore/exploit results (see below).

Explore/Exploit Settings

In order to gather unbiased data from which to learn, Vidora uses an explore/exploit framework in which decisions are randomized for a small percentage of users (the “explore” cohort). By randomizing decisions for a small set of users the system collects data to train the decisioning framework and ensure that optimal decisions are made moving forward. There are two default settings that may be overridden.

Setting Description
Explore Type Should randomization occur at the user level or the session level? Default is user-level randomization.
Explore Percentage What percent of users / sessions (depending on the value of “explore type”)  should be placed in the “explore” cohort? Default is 5%.

 

Loading a Pipeline

Get Pipeline

Load a pipeline into the client, so that it may be used to generate real-time decisions as a user browses your site. This function is accessed through the Vidora API object, and returns a Pipeline object.

Request

api.getPipeline(pipelineId)

Parameters

Parameter Type Description
pipelineId string Unique ID for the pipeline. This can be accessed from Cortex or via the Pipelines API.

 

The Pipeline Object

The SDK’s Pipeline object provides functions for making decisions based on predictions from an ML Pipeline built in Cortex. The following functions can be accessed through the Pipeline object:

Function Type Description
getDecision ((callback: (decision: Decision) => any) => void) | (options: Options, callback: (decision: Decision) => any) => void Get the object representing the optimal decision to be made for a given user (see below).

Getting a Decision

For a given user, return a Decision object containing information about whether or not the user should be treated, based on a real-time prediction from an ML Pipeline in Cortex. In this context, “treatment” refers to the action or intervention associated with a Future Events or Uplift pipeline.

When you make a getDecision call for a given user, the JavaScript SDK automatically combines information from the user’s current session with historical features in order to generate an up-to-date decision in real-time. 

Request

pipeline.getDecision(function(decision){ 
  // user-defined logic to act on the decision
});

Parameters

Parameter Type Description
callback function JavaScript function containing logic for executing the optimal decision (e.g. showing a paywall).
options hash Optionally, include key-value pairs corresponding to additional features which should be passed to the ML Pipeline when generating a real-time prediction (which will be used for decision optimization). Example: current_article_section: ‘news’

 

The Decision Object

The SDK’s Decision object represents a dynamic decision generated by an ML Pipeline. The following functions can be accessed through the Decision object:

Function Type Description
action int The action to be taken for the user.
explorationCohort int | null Whether or not the user is in the explore or exploit cohort. This function will return null if the user is in the Exploit cohort. Otherwise, it will return the action that is being Explored.
tieEventToPrediction (params?: {[key: string]: int | string}) => {[key: string]: int | string} When sending an event for the decision that was made (e.g. shown_paywall), include this function alongside event parameters so that the event can be tied to the decision that was returned by the SDK. This is required for proper functioning of Vidora’s SDK.

Getting Best Action

Get the optimal action to be taken for a user. Returns 1 if the user should be treated, and 0 if the user should not be treated. In this context, “treatment” refers to the action or intervention associated with a Future Events or Uplift pipeline.

Request

decision.action;

Getting Exploration Cohort

In order to translate predictions to optimal decisions, Vidora uses an explore/exploit framework wherein decisions are randomized for a small percentage of users (the “explore” cohort). The explorationCohort property indicates whether the user is in the explore cohort, and if so, which decision is being explored.

Request

decision.explorationCohort;

Recording Treatment Events

Decision optimization requires that a treatment event be sent to Vidora indicating that a decision was made and acted upon (e.g. showing a paywall). This treatment event must also be tied to the Pipeline from which the decision was generated. The tieEventToPrediction function automatically handles this connection. The function must be included as an argument to your existing event tracking, be it through the SDK’s Behavioral Module or another provider such as Google Tag Manager.

See below for an example of tying a “shown_paywall” event to a dynamic decision when recording events through the Vidora SDK:

Request

decision.tieEventToPrediction(params);

Example

api.send('shown_paywall', null, decision.tieEventToPrediction({device:"mobile", referrer:"www.example.com", cookie_id:"xyz"}));

Example Usage

The following example shows how the SDK might be used to dynamically determine whether a user should be shown a paywall. The SDK executes the following logic –

  • Load a pipeline into the client
  • Load a paywall into the client
  • Generate a dynamic decision to determine whether the paywall should be shown
  • Record a treatment event indicating whether or not the paywall was shown

Example

window.vidora.ready(function(api){
  var pipeline = api.getPipeline('your-pipeline-id');
  var modal = document.getElementById('subscription_paywall');

  pipeline.getDecision(function(decision){
    if (decision.action === 1) {
      modal.className = 'shown';
    } else {
      modal.className = 'hidden';
    }
    api.send('shown_paywall', null, decision.tieEventToPrediction({device:"mobile", referrer:"www.example.com", cookie_id:"xyz"}));
  });
});

Related Links

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

Table of Contents