More About Sessions

How we track visitors as they move around your site or app

In the Quick Guide, you saw how to get a simple decision from a Conductrics Agent:

GET http://api.conductrics.com/acme/agent-1/decision

And how to send a reward to the Agent:

POST http://api.conductrics.com/acme/agent-1/goal

You might be wondering:

  • How does the service know that the goal is conceptually connected to the decision?

  • In other words, how does the service track visitors?

  • Does it set a cookie? If so, how can that work when calling Conductrics from a server?

This page should answer those questions for you.

Visitor Sessions in a Nutshell

There's Always a Session

All decisions and goals happen in the context of a 'Session' which is remembered by your agent.

We need a Session ID to keep the sessions straight. You can provide the Session ID, or we can make it up for you.

Without the concept of Session IDs, we wouldn't have a good way of matching goals back to the decisions that led to them. Our service wouldn't be able to learn.

We Can Set a Cookie If You Want

If you are using our service 'client-side', meaning that you are making calls to our service via AJAX / jQuery / JavaScript, then to make things simple, our service is happy to set a cookie with the Session ID.

This cookie support also works great with our Simple Redirects feature, so you don't need to use any scripting at all.

For details, see Automatic Cookies, below.

Otherwise, pass us the Session ID

If you're calling our API from the 'server-side', or any other scenario where cookies don't apply, you need to pass us a session ID.

You pass the ID as a URL parameter called session, or as an HTTP header called x-mpath-session. The value can be just about any string you make up, as long as it's unique to a given 'visit' or 'session'.

Often, you will have a 'session' or 'visit' type of ID on hand already, via whatever software or framework you are calling our service from. You can just use that (or a hash of it) as the ID you pass to us.

If you don't pass an ID, we'll make one up and return it in our response. It's up to you to pass us back that same ID for the next request from the same conceptual session.

It's best if the ID you provide contains only letters, numbers, underscores and dashes (if not, we will still accept it, but we'll strip out any spaces or other characters and use that--the cleaned ID will come back in our response).

Automatic Cookies

If you are using our service 'client-side' (so, the calls are coming to us straight from a browser), our service can set a cookie to track each visitor's session.

Basically, this means that:

  • We check for the presence of a cookie (that we set) as each decision or goal call comes in from a browser.
  • The first time we get a request to make a decision for a visitor that doesn't have our cookie, we'll make up a new Session ID and set it in the cookie.
  • The user's browser should return the cookie to us on subsequent calls (such as goals).
  • This gives us what we need to learn value of each decision in real time.

If you don't want us to set cookies, you can turn them off via the Cookies checkbox in your Agent's Settings (under the Advanced tab).

Technical Details

For developers that are interested, some details about how the automatic cookies are set:

  • The cookie will be set with a PATH attribute that includes your owner and agent code.

  • The cookie will be set as a non-persistent cookie, meaning that if the user closes their browser and returns to your site or app, they will get a new session with a new session ID. If it is important to you that the user's session be able to survive a browser restart, then you will need to set the cookie yourself via scripting.

Would you like to be able to specify that the cookie never expires (persistent cookie), or be able to specify a custom cookie duration? We don't have such an option at present to keep things as simple as possible, but please let us know if control over the expiration would be helpful for you.