Session Identifier Placeholders

📘
REST API Only
Session Identifier Placeholders work with the Conductrics REST-style API (aka Web Service) only. They aren't for use with Conductrics Express or the in-browser JS API , or for the on-device APIs for mobile. They may be used with our REST API helper libraries for Swift/iOS and Java/Android, however.

🚧
Session Identifier Placeholders became available beginning with Conductrics 3.7.4.

Sometimes you may need to use the Conductrics REST-style API to run an A/B test or optimization that "spans" devices.

For instance, consider a test that shows a variation on a web page, then continues on a mobile app.

If you have a stable identifier (perhaps provided by an analytics service, or because the visitor is "logged in" on both sides), you can simply provide that identifier (or a hash of it) as the session parameter when calling our REST API. No need to overthink it. :)
If, however, the visitor is "anonymous" at the point where they switch from the web page to the mobile app, you may not have a proper identifier to provide to Conductrics. You can use "Session Identifier Placeholders" as a workaround to get a reasonably stable identifier based on a portion of the visitor's IP address, plus the current time rounded to the nearest hour.

Using Session Identifier Placeholders

Here's how you use Session Identifier Placeholders:

For "fresh" visitors, provide a string such as {ip}_{1h} for the session parameter when calling the REST API (see Supported Placeholders section below).
Internally, Conductrics replaces the placeholders using simple string substitution, then hashes the resulting string and uses that as the session identifier as it processes your API request (selecting variations, accepting goals, etc).
Conductrics returns the "computed" session identifier as the session property of its response.
You store the returned identifier on your side (via a cookie or whatever mechanism is appropriate in your app).
For any subsequent requests, provide the "computed" identifier returned with the initial request.

❗️
Better Than Nothing, But Worse Than Something
Session Identifier Placeholders are very much a "workaround" for the problem of connecting variation selections and goals/conversions across devices, when there is no other means available. The approach is inherently imperfect. If you have a better identifier available to provide Conductrics with, please use that instead.

Supported Placeholders

At this time, the supported placeholders are:

{ip} - Gets substituted with a hash (that is, a scrambled version) of the visitor's IP Address.
{1h} - Gets substituted with the current date/time, rounded to the nearest hour. You can also use {2h}, {4h}, {8h}, {12h}, or {24h} for less granularity. Higher numbers mean less of a chance of "losing" a visitor over a time boundary, but more of a chance of "conflating" two different real-world visitors. Please feel free to contact Conductrics if you would like to think through the tradeoffs.

For example, to specify {ip}_{1d} as the session identifier, your REST API request might look something like the following:

POST https://api.conductrics.com/ac-xxx/v3/agent-api/dt-yyy?apikey=api-zzz&session={ip}_{1d}
{
	"commands": [ {"a": "my-agent-code"} ]
}

Note: In practice, the session={ip}_{1d} part would typically appear as session=%7Bip%7D_%7B1d%7D due to the curly-brace characters being escaped as %7B and %7D, but we've skipped that escaping above for clarity.

The reply might look something like:

{  
	"status": 200,  
	"data": {  
		"items": [{  
			"a": "my-agent-code",  
			"c": "B",  
			"p": "r",  
			"md": {},  
			"s": "ok"  
		}],  
		"sels": {  
			"my-agent-code": "B"  
		},  
		"traits": [],  
		"session": "db038026290b219c185427acc7c93c3698b0599e"  
	}  
}

It's up to you to store the returned session identifier and return it with subsequent requests (for instance, for goals/conversions, or when re-fetching the variation selection).

🚧
If you can't or don't want to store the returned "computed" identifier, you could simply provide the same "placeholdered" identifiers for all of your REST API requests (at least for a given test/agent). In such a case, you would probably want to use a longer time-block placeholder (such as 12h or 24h) to reduce the risk of "losing" the visitor before the subsequent events occur, unless you're only interested in subsequent requests that would happen very shortly after the original selection. That said, using a longer time-block would mean increasing the risk of conflating two real-world visitors. Please feel free to contact Conductrics if you have questions.

📘
The returned session identifier isn't magic, it's simply a hash of the string you provided, after the placeholder substitutions. You could just as easily create such a hash yourself, and pass it to Conductrics directly instead of using the placeholders. The placeholders are provided as a convenience, so you don't need to do things like attempt to determine the visitor's IP address and so on.

🚧
Calling the API Server-Side?
If you're calling the REST API from your servers or through some other network proxy (as opposed to directly from a visitor's browser or mobile device), then Conductrics only knows your server's IP address unless you pass along the visitor's IP address via the ip parameter (or via an x-forwarded-for or x-real-ip or client-ip header). Otherwise, the %ip% placeholder will always be substituted with your server's IP address, which would defeat the purpose.