Docs
Go to Conductrics.com →
  1. Main Runtime API

Using the Local JS API

For running A/B Experiments and other Conductrics Agents via an API running locally in the browser

This page explains how to use the Local JavaScript "flavor" of the Conductrics Runtime API, which runs locally in web browsers, including:

  • Getting set up
  • Getting a selection from an agent
  • Sending a reward to an agent

Please see the Runtime API Overview for an overview of the API concepts, such as "getting selections" and "sending rewards".

📘

We also offer a "REST API" flavor of the API, which is has almost the same capabilities but which runs on our servers. Please see the Runtime API Overview for more about these two ways to access the API.

👍

You can also create "Conductrics Express" agents which run Custom JS Code that you provide in the Conductrics Admin. The difference is that with the Local JS API being discussed here, the actual variation "content" (that is, what happens or gets shown if the visitor is selected into variation A vs B or whatever) lives on your side, whereas with Conductrics Express, the code to show/render your variation is stored and managed in Conductrics ("on our side").

Getting Set Up

If you haven't already, fill out the initial setup form for your "Site". You're guided through this process when you first sign into the admin.

One of the main things that you're asked to do at this point is to paste a <script> tag into your pages. That tag will make the Conductrics.ClientApi class available. The remainder of this doc assumes that you've gone through this process and added the <script> tag already.

Local API Usage

Now that you've included our runtime scripts on your page, you can start using your agents in your own code. The first thing to do is to create an instance of the ClientApi class, like so:

// Get an instance of the ClientApi class
var api = new Conductrics.ClientApi();

Now you can use the exec method to execute one or more commands.

Each command will do one of the following:

  • get a selection from one of your agents, or
  • send a goal to reward prior selections.
📘

API Testbed, BTW

If you like, you can use the API Testbed to assemble commands with the appropriate agent codes, etc.

Example: Getting a selection from an agent

The following is a quick example of how to get a basic selection from an agent by calling the exec method.

  • The first parameter is an array of API "command" objects. In this case there is just one, because we're interested in just getting a selection from a single agent.

  • The second parameter is a callback, which receives the result. The result will contain a sels object, which is a simple map of agent codes to the selection made for each agent (one for each a command you passed in). The result object includes a few other bits of information as well, see the Runtime API Reference for details.

// Get an instance of the ClientApi class
var api = new Conductrics.ClientApi();

// Get variation selections from one or more agents
api.exec([
  {a: 'my-agent-1'} // get a selection from agent 'my-agent-1'
], function(err, res) {
  // print selection to the console
  console.log( 'Agent selected ' + res.sels['my-agent-1'] ); // "Agent selected B"

  switch (res.sels['my-agent-1']) {
    case 'A':
      do_old_thing(); // whatever should happen for "A"
      break;
    case 'B':
      do_new_thing(); // whatever should happen for "B"
      break;
  }
});
📘

For all details about the parameters to include in the a command, please see the Runtime API Reference.

Providing Visitor Traits

If you would like to provide Custom Visitor Traits along with the selection request, you can provide them as an array of strings to the ClientApi constructor. Each should be a name/value pair, separated like so:

// Get an instance of the ClientApi class
var api = new Conductrics.ClientApi({
  traits: ['tier:gold', 'interest:music']
});

// Get variation selections from one or more agents
api.exec(...);

If preferred, you may provide the traits as an object instead, like so:

// Get an instance of the ClientApi class
var api = new Conductrics.ClientApi({
  traits: {
    tier: 'gold',
    interest: 'music'
  }
});

// Get variation selections from one or more agents
api.exec(...);

See the Runtime API Reference page for details and other information you can provide to the Conductrics.ClientApi constructor.

Example: Sending a Goal event to an agent

Sending a goal to an agent uses the same overall pattern, except that you provide a g command with the API code for the goal you want to send.

// Get an instance of the ClientApi class
var api = new Conductrics.ClientApi();

// Execute one or more commands
api.exec([
  {g: 'signup'} // send reward for goal 'signup'
], function(err) {
  if (err) {
    // optional logging of errors, etc
  } else {
    console.log( 'Reward sent.' );
  }
});
📘

Numeric values and additional parameters

For e-commerce or other similar scenarios where it makes sense to send a numeric value along with the goal event, you can include a v parameter that specifies the value, so perhaps something like {g: 'purchase', v: 19.99} if your visitor just made a $19.99 purchase, for instance. You can also specify a currency via the vc parameter for goals that have currency conversion enabled.

See Goals / Conversions for details about numeric goals, and see also the Runtime API Reference for all details about the parameters to include in the g command.

Updated about 1 year ago