Learning API Reference for decisions, rewards, and sessions
This document provides a reference for the main parts of the Conductrics APIs.
A few API topics are broken out into their own documents: See Reporting API and Targeting Rules API.
Getting Decisions
As explained in the Quick Guide, the basic call to get a decision from our service takes this basic form:
GET http://api.conductrics.com/demo/agent-1/decision
Additional parameters are listed below:
| point q h | A decision point code, if you want to use multiple decision points in your agent. See Multi-Faceted Agents for an explanation of what decision points are and when to use them. See note above about characters allowed in the point code. Optional. If not provided, we assume you are talking about the first decision point in your agent. If you've never specified a decision point explicitly, then your agent has one point called 'point-1', and that's what we'll use by default whenever you don't provide a point parameter. Auto Creation: If you do provide this parameter, and the decision point doesn't already exist, it will be added to your agent. |
|---|---|
| decision-policy q h | An explicit decision policy, to force our service to select options in a particular way. You can set this parameter to one of the following: explore - The selected option will be chosen randomly. exploit - The current 'winner' will be selected, meaning the option that has led to the most goals in the past. control - The current 'default' will be selected. Optional. If not provided, our service intelligently uses an automatic balance of the three policies to provide you with a self-tuning agent and sensible reporting. We generally do not recommend using this parameter unless you want to use our service to do "testing only" (no adaptive targeting) for a particular agent. Consider discussing with us before using! :) |
| session q h | A session identifier. Optional, but recommended unless the calls to us are coming from a browser (for instance, via a web page that uses AJAX). See Common Session Parameters for details about providing the session identifier. See note above about characters allowed in the session code. |
segment, features, ip, ua, referer | These parameters, all optional, are used for targeting. See Common Session Parameters in this document for details. Also check out our explanation of Targeting Rules. |
Sending Goals
As explained in the Quick Guide, the basic call to send a reward to our service takes this basic form:
POST http://api.conductrics.com/demo/agent-1/goal
Optionally, you may provide a specific goal code like this, where "purchase" is a goal code that you make up:
POST http://api.conductrics.com/demo/agent-1/goal/purchase
Additional parameters are listed below:
| goal | A goal code. You can see a goal code provided in the second example above. See note above about characters allowed in the goal code. Optional. If not provided, we assume you are talking about the first goal code known by your agent. If you've never specified a goal code explicitly, then your agent has one goal called 'goal-1', and that's what we'll use by default whenever you don't provide a goal parameter. |
|---|---|
| reward q h | A numeric reward value. The relative value of the goal, as perceived by you or your company. For instance, if the goal you're sending is that a user just completed a purchase, you can provide the actual dollar amount of the purchase as the reward. This will let our service learn in terms of how much money it can conceptually "make" by picking a particular option when making decisions in the future. Optional. If not provided, we assume a value of 1. There is nothing wrong with using the default value of 1. It simply means that our service will be learning in terms of how many goals occur, not on the value of the goals. So, it makes sense to simply omit this parameter when all of your goals have the same conceptual value to you or your organization. |
| session q h | A session identifier. Optional, but recommended unless the calls to us are coming from a browser (for instance, via a web page that uses AJAX). See Common Session Parameters for details about providing the session identifier. See note above about characters allowed in the session code. |
segment, features, ip, ua, referer | These parameters, all optional, are used for targeting. See Common Session Parameters in this document for details. Also check out our explanation of Targeting Rules. |
Ending Sessions
Sometimes you will have a scenario where you want to consider a person's session to be finished. For instance, if a user clicks some kind of "logout" button in your site or app, it probably makes sense to let our service know that the session has ended conceptually.
DELETE http://api.conductrics.com/demo/agent-1/session
or, if a DELETE isn't convenient to issue from your application, you can use:
POST http://api.conductrics.com/demo/agent-1/expire
In either form, the expire action doesn't take any additional parameters other than the common ones, listed below:
| session q h | A session identifier. Optional, but recommended unless the calls to us are coming from a browser (for instance, via a web page that uses AJAX). See Common Session Parameters for details about providing the session identifier. See note above about characters allowed in the session code. |
|---|---|
segment, features, ip, ua, referer | These parameters, all optional, are used for targeting. See Common Session Parameters in this document for details. Also check out our explanation of Targeting Rules. |
Just Passing Targeting Info without making a Decision
Generally, you pass targeting features or segments to Conductrics when you get a decision or send a reward as discussed above.
You may encounter a scenario where you want to pass additional features (or change the segment) without making a decision or sending a reward. This might be convenient in situations where some external factor has caused the visitor's conceptual profile to change, but for whatever reason it's not convenient for you to wait unti a decision or reward event to pass us the new features.
For instance, perhaps a decision has already been made for a given visitor, and then the visitor does something such as log in as a registered user. Now you might have some information (such as their gender or favorite type of music, etc) from their registration profile, which you'd like to pass to Conductrics as targeting features, but there isn't another decision to be made at that moment. You could simply wait until the next decision (if any) to pass the features to Conductrics, but if that isn't straightforward to implement, you can pass the features like so:
POST http://api.conductrics.com/demo/agent-1/session?features=gender:male,genre:shoegaze
In most cases you would supply a session identifier in addition to the features list. See the Common Session Parameters listed below.
Common Session Parameters for the Learning API calls
These parameters can all be provided when making session-related calls to our service: getting decisions, sending goals, or expiring sessions.
session | A session identifier. Optional, but Recommended. If not provided (and a cookie was not set per note below), our service will make up a new session identifier for you. The new identifier will be included in the reply. It is up to you to pass the same identifier back to us on subsequent calls for the same visitor/user. Cookies: When our service makes up a new session identifier (because one was not explicitly passed with this parameter), it will attempt to set a browser cookie when it responds. This means that if the requests are coming from a browser (for instance, if you are making the calls to us via AJAX), the same identifier should get sent back to us on subsequent requests for the remainder of the browser session. See note above about characters allowed in the session code. |
|---|---|
segment | A segment code, if you know a specific targeting segment that you want this user to be considered a member of (via a database lookup on your side, etc). See note above about characters allowed in the segment code. Optional. If not provided, the visitor will be 'bucketed' into a segment automatically by the Targeting Rules you are using, if any. Otherwise the session will be a member of the default segment, labeled (none) or (everyone else) in reports. for details. |
features | A feature code or codes, if you know specific targeting feature(s) that you want this user to be considered 'tagged' with. The features would likely be coming from a cookie or database lookup on your side, etc. Each of your feature codes should have two parts: a type and a value. Separate multiple feature codes with commas. For instance, you might pass something like If you don't provide a type for a particular feature, Conductrics will use |
ip | The IP address of the users/visitor's computer, if known. The IP is used only to enable the 'geo' related Source Data values for Targeting Rules. If you aren't using geo-related targeting rules, there is no need to pass us the IP, though you can if you might use targeting rules in the future. We don't store the IP on our side--it is only used for lookups and then discarded. Optional. If not provided, and you are using a targeting rule that wants the IP, we will use the IP address from the HTTP request itself. We also support the common x-forwarded-for header that many HTTP proxy servers and CDNs send along with requests. If you are making requests from a server, that means we'll always be using the server's IP address, so you should provide the IP address explicitly if you're using our service in this way. |
ua | The User-Agent string provided by the visitor's browser, if known. The User-Agent string is used only to enable the related Source Data values for Targeting Rules. If you aren't using user-agent-related targeting rules, there is no need to pass us the ua, though you can if you might want to use such targeting rules in the future. We don't store the User-Agent on our side--it is only used for lookups and then discarded. NOTE: Make sure to escape special characters in the User-Agent string (most HTTP libraries will do this for you). Optional. If not provided, and you are using a targeting rule that wants the User-Agent, we will use the User-Agent string from the HTTP request headers, if provided. If you are making requests from a server, that means we'll always be using whatever your server sends as a User-Agent (some won't provide anything by default), so you should provide the ua string explicitly if you're using our service in this way. |
referer | The page that the user/visitor is coming from (aka referring page or referer), if known. This information is used only to enable the 'ref' related Source Data values for Targeting Rules. If you aren't using referer-related targeting rules, there is no need to pass us the referer, though you can if you might use targeting rules in the future. We don't store the referer on our side. Optional. If not provided, and you are using a targeting rule that wants the referer, we will use the Referer header from the incoming HTTP request itself. If you are making requests to us from a server, no referer will be passed along unless you take steps to do so in your code, so any referer-related targeting rules will just be ignored. |
ts | A timestamp that represents when you want the request to have taken place, expressed as the number of seconds since January 1, 1970. You can use this to do batch-processing of events that have already taken place 'offline'. Optional. When not provided, the current time is used. Caveats: We consider the ts parameter to be an experimental feature. We don't recommend using it except in special scenarios. If you do use it for a given agent, you should always provide it, and the timestamps you pass need to be in order. If dates come out of order, or you don't consistently provide a ts with every call, reports will become nonsensical and learning will likely be inaccurate. Discuss it with us before using! :) |