Guide for Server-Side Usage

This document provides an overview for companies that would like to integrate Conductrics into another system using our Server-Side API (aka Web Service). You could use this to infuse your app, site, or tool with Conductrics-powered testing, optimization, or targeting functionality.

You could use the conceptual steps explained here to connect Conductrics to:

• Content Management Systems (CMS's)
• Marketing Automation Systems
• Other internal or third-party systems where there are conceptual "variations" of some kind.

Of course, the exact steps and code you'll write will depend on the nature of your site, app, or tool. Our goal in this guide is to help you understand the overall conceptual steps and when you'll want to make "calls" to Conductrics APIs.

Here are the basic steps we'll cover:

1. [Get Conductrics Account Credentials] (#1-get-conductrics-account-credentials)
2. [Provide a Way to Create or Connect to a Conductrics Agent] (#2-provide-a-way-to-create-or-connect-to-a-conductr)
3. [Getting Agent Selections at Runtime] (#3-getting-agent-selections-at-runtime)
4. [Sending Rewards Back to Conductrics] (#4-sending-rewards-back-to-conductrics)

1. Get Conductrics Account Credentials

The first thing you'll want to do is provide some way for your users to provide their Conductrics account credentials. Depending on what you're building, you might provide an online form where they can provide this information, or provide way for them to provide it in a configuration file, etc.

At a minimum, you'll need your users to provide the following, which they can find in the Conductrics admin under Developers > API Info and Keys:

• Conductrics Account Code - The account code starts with ac-, so something like ac-a1b2c3d4e5.
• Runtime API Key - The API Key starts with api-, so something like api-1234567890
• Runtime API URL - This is often https://api-v3.conductrics.com, but may be different depending where the company is located, or if they are using an on-premise install of Conductrics.

Optionally, you may also want to get some additional information if you want your users to be able to list, start, stop, or create Conductrics agents from within your app or tool:

• Admin API Key - The Admin API Key will start with admin-, so something like admin-1234567890.
• Admin API URL - This may or may not be different from the Runtime API URL.

Encourage your users to generate fresh API Keys
You should strongly recommend that the user generate a fresh API keys just for your use, rather than using an API Keys that are also being used by some other system. This way, they can revoke access to connected applications (such as yours) separately. Users can generate keys in the Conductrics Admin, under Developers > API Keys and Info, as shown below.

2. Provide a Way to Create or Connect to a Conductrics Agent

Now you can get to the fun part, which is providing some way for your users to create a "test" or "optimization" or "campaign" or whatever you want to call it on your side. Each one of these will have a corresponding Conductrics Agent which "runs" the test. The agent will be responsible for selecting between a set of "variations", each of which is usually a reference to a corresponding "content object" or similar concept on your side.

📘

To put it another way, you can think of a Conductrics Agent as having a "bag" of "content objects" or similar "things" that the end user creates on your side. For each visitor, the agent will reach into the "bag" and select one of the content objects (or whatever they are), and your code will take care of displaying or providing that "thing" to the end user.

The workflow and UX for your content authors will depend entirely on what you're building, but
one way or another, the user is going to end up creating:

• A Conductrics Agent. The agent has an agent code and a friendly name. Generally the user creates the agent in the Conductrics Admin, but you can also automate the creation of the agent if you wish (see below).
• The "variations" that the agent will select from, each of which having:
  • A code for the variation, typically A or B or similar (this is called the choice code in our API docs). Generally the user does this in the Conductrics Admin when creating the agent, unless you are providing a way to create the agent "natively" in your tool.
  • A friendly name for the variation, often just Variation A or similar by default, but the user may want to provide a more meaningful name. Again, generally the user does this in the Conductrics Admin when creating the agent, unless you are providing a way to create the agent "natively" in your tool.
  • The actual variation "content" or "experience" that actual visitors or "end users" should see or receive. This lives on your side and is up to you.
• One or more Conductrics Goals. Each goal has a goal code and a friendly name. Again, generally the user creates the goal in the Conductrics Admin while creating the agent itself, but you can automate the creation of the goals if you wish.

The user may also want to provide:

• Whether the agent should select randomly ("A/B Testing" scenario) or via Conductrics Predictive Analytics ("Optimization" scenario).
• Targeted Selection Rules, if they want to "hard code" the "A" variation to certain visitors and the "B" variation to other visitors, or some similar type of use case.

So, where do your users create the Conductrics Agent? That's up to you.

1. You could have your user create the agent in the Conductrics Admin, and then paste the agent's code into your form. You don't need an Admin API Key for this.
2. You could have your user create the agent in the Conductrics Admin, then let them pick the agent from a dropdown list in your form. You'll need an Admin API Key for this, so you can get the list of agents from Conductrics using our Agent Management API.
3. You could provide a way for the user to create an agent from within your tool. You would provide a form or similar where the user can provide a name for the new agent, and the variation (aka "choice") codes that the agent should select from. See Creating an Agent in our Agent Management API.

📘

The first of the above options is easiest for you as a developer but more work for your users, and the last option is the most work for you but easiest for your users. You might want to "start simple" with the first option as a proof of concept, then move to the next option as time allows.

Usually the second option is the "sweet spot" that makes it reasonably easy for you and for your users. Your users create their agents, variations, and goals on the Conductrics side, but don't need to remember the corresponding API codes and such when setting things up on your side.

It's the same basic story with Goals. you could have your users create them in the Conductrics Admin, or you could create them programatically.

3. Getting Agent Selections at Runtime

The next step is getting a selection from Conductrics, so that your visitors or end users get assigned to a particular variation. You do this by calling our Runtime API Overview. (By "runtime" we mean when actual visitors or "end users" are visiting or running your app, site, or tool.)

📘

Conductrics Markup for Web Pages

As an alternative, if what you're building is web-based, you might want to consider using Conductrics Markup to do the work of displaying the appropriate content variations to your visitors. In many cases you can replace this whole step with the markup approach.

Let's assume that the visitor has just arrived at some page, screen, or moment where you know Conductrics should be involved.

Here's what you'll need to make the API call:

• The Conductrics Account code (from step 1), for example acc-xxxxxxxx
• The Runtime API Key (from step 1), for example api-1234567890
• The Runtime API URL (from step 1), for example https://api-v3.conductrics.com
• The Agent Code (from step 2), for example my-agent-1
• A unique session identifier, for example 123

The only thing in the above list that we haven't already discussed is the session identifier, which you can think of as a "visitor ID". It's up to you to provide this identifier. You probably already have this handy in a "cookie" or other type of session record. You may provide a hash of an existing identifier or make one up (at the user or visitor level) just for passing to Conductrics.

You can put those all together to make a POST call to the Conductrics API, like so:

POST https://api-v3.conductrics.com/acc-xxxxxxxx/v3/agent-api?apikey=api-1234567890&session=123

{
  "commands": [
    {"a":"my-agent-1"}
  ]
}

📘

Please refer to the API Usage via Web Service and Runtime API Reference pages for more details on the above call, but in many cases this is basically how your calls will look.

Conceptually, the above call simply asks Conductrics to make a selection for the visitor. It will select a variation using the appropriate Selection Policy and return its code to you. It will also remember the variation that it selected for the visitor.

The server will reply with a JSON-formatted response that looks something like this (whitespace added for clarity):

{
  "items": [
    {"a": "my-agent-1", "c": "B", "p": "r"}
  ],
  "traits": [],
  "sels": {
      "my-agent-1": "B"
  }
}

The most important part of the response is the agent's selection. In the above example, the agent has selected variation B. The selected variation code appears in the items array as well as in the sels object. Look in either spot to get the agent's selection - whichever is more convenient for you and your code.

Now that you have the selection, it's up to you to do the appropriate thing for "B". By design, Conductrics really has no idea what "B" is - it might be something simple like an alternate headline, hero image, or promotion, or it could be something more abstract like an alternate search algorithm or shipping method.

// pseudo-code
switch response.sels[ agent_code ]
  case "A"
    // do or show the "A" thing
  case "B"
    // do or show the "B" thing

🚧

Considerations if Caching Agent Responses

You may feel that you want to "cache" the selections from Conductrics, either to reduce network latency or reduce the number of calls you have to pay Conductrics for (but talk to us if you are concerned about pricing).

You are of course free to store the responses in something like Memcached, Redis, or an internal database table, and it may very well make sense to do so. However, we suggest caching for a relatively short time, in case your users decide to stop or pause the agents.

In other words, in most cases it's enough to reduce the number of "duplicate" calls, not eliminate them entirely. We generally recommend considering a cache TTL of something like several minutes or half an hour, as opposed to many hours or days.

📘

The API supports getting more than one agent selection at a time for a given visitor, in which case you'll provide multiple "a" commands in your POST, and you'll get back multiple selections in the items array and sels object.

You must make a separate API call for each visitor (that is, for each session identifier), however.

Adding Targeting Information

• You may also provide the visitor's IP address, if you have it and if it is appropriate from a privacy perspective. If you provide it, Conductrics can look up geographical information for reporting or learning purposes.
• For web applications, you may also provide the visitor's user agent string, if you have it and it is appropriate to provide it from a privacy perspective. If you provide the user agent, Conductrics can identify the browser type, whether the user is using a mobile or desktop device, etc.
• Optionally, you may provide additional visitor traits to Conductrics when making the selection calls. For instance, if the end user or visitor has a profile on your side, you might send along their "favorite category" or "customer type" as traits. The traits can be used internally by Conductrics machine learning, and will appear in Conductrics reporting. See Custom Visitor Traits for details.
• Instead of providing visitor traits, you may find it easier to provide Custom Input Params that may be relevant. This will allow your users to use the Conductrics Admin to "bucket" into visitor traits using conditions that are based on the input params you provide.

4. Sending Rewards Back to Conductrics

The final step is in many ways the most important. You need to tell Conductrics when a "success" or "conversion" event occurs, so that Conductrics can "credit" the selection that was made for the visitor and update its internal statistics. In Conductrics we call these Goals.

Goals are what drive the Conductrics reporting and machine learning and make your agents actually useful. Without goals, there is nothing to measure the success of your variations against.

📘

Conductrics Markup for Web Pages

Again, if what you're building is web-based, you might want to consider using Conductrics Markup to do the work of sending the appropriate goals back to your agents. In many cases you can replace this whole step with the markup approach.

So, when the user gets to a page, view, moment, or conceptual "spot" in your app or site that should be considered a goal event, you notify Conductrics by sending the appropriate goal to "reward" your agent for the selection it made for the visitor.

The API call to send the goal is almost the same as the one to get a selected variation. Here's what you'll need:

• The account code, Runtime API Key, and Runtime API URL (same as when you got the selection)
• The session identifier (same as when you got the selection).
• The goal code, for example my-checkout-goal.
• Optionally, a numeric reward value, for e-commerce and other similar scenarios where the conceptual value of the goal event varies depending on what the user is buying, viewing, or doing.

POST https://api-v3.conductrics.com/acc-xxxxxxxx/v3/agent-api?apikey=api-1234567890&session=123

{
  "commands": [
    {"g":"my-checkout-goal"}
  ]
}

You don't generally need to do anything with the response except for debugging purposes, but there are details about it in the API Usage via Web Service and Runtime API Reference doc pages.

Other Things You May Want to Provide:

Other things you might want to consider:

• A way to change the agent's status (running, stopped, "paused" at a particular variation code, etc) - or you can just have your users just use the Conductrics Admin for this purpose.
• A way to see basic agent-level stats (number of selections made today, etc) within your admin console or dashboard - see the Reporting API for details.
• Convenient links to the Conductrics Admin, so it's easy for the user to view reports and so on.