Experiment Link Documentation

The experiment link provides a flexible method for handoff from a panel company into the eyetracking session, and then back to the panel company's success or abort links.

In order to make it easy to return all URL variables, it was necessary to include session-related parameters using a technique other than query-string. This has been accomplished by using the path part of the URL in the form parameter-1-name/parameter-1-value/parameter-2-name/parameter-2-value.

Structure of an experiment link URL:

Click the different parts of the URL for information on how each should be constructed, and how it is used by the eyetracking system.

The parameters and URL variables are optional - therefore, the simplest deployment link is http://experiments.sticky.ai/experimentid, which will use all the defaults described in this document.

Experiment ID

This should simply be the experiment id as displayed in the eye portal.

Session optional parameters:

These parameters are optional. If they are not included, the default values will be used instead.

Default values

participant                      [randomly generated]

recorder                          webcam:flash

channel                           release

cloud                               sticky

locale                               en

successlink                     [shows a success message instead of redirecting]

failurelink                         [shows a failure message instead of redirecting]

forwardAllUrlVars          true

These parameters are optional. If you want to use the default values, the parameter should not be included in your experiment link. To include a parameter, it must be encoded as follows:

For each parameter:

"/" + encodeURIComponent(parameter name) + "/" + encodeURIComponent(value)

All the encoded parameters should be appended together, then added to the experiment link after the experiment id. This will result in a URL like "http://experiments.sticky.ai/experimentid/param1/value1/param2/value2/param3/value3

URL variable merge codes

If you need to provide session parameters that have been sent as a URL variable, you can use a merge code in the value you pass as the parameter.

A URL variable merge code is created by combining two underscores, followed by "URLVAR", then a single underscore, then the exact name of the URL variable, then finally ending with two underscores.

We envision this mainly being used when a panel company provides a specific URL variable to identify the panelist. Let's say the panel company adds a URL variable like "pzid=cooluser23", and you want to make sure the eyetracking session records "cooluser23" as the participant. Here's how you can set this up:

"http://experiments.sticky.ai/experimentid/participant/__URLVAR_pzid__"

The system will then look for the URL variable "pzid" and use it as the participant parameter.

You can use merge codes for other URL variables and session parameters as well. Let's say the panel company is sending a URL variable for the language code as "langCode=es". The eyetracking platform uses the parameter "locale" to select a language, so you could set things up like this:

URL variables

By default, URL variables passed to the experiment link have no impact on how the session is set up and run. If the session parameter "fowardAllUrlVars" is either omitted or set to "true", all URL variables will be appended to successlink and failurelink before the user is redirected. This means that by default, all variables sent in by a panel company will be passed back when the user is redirected.

If you want to forward specific URL variables, but not all of them, read below "Using merge codes with successlink and failurelink".

Using successlink and failurelink:

If these session parameters are included, the user will be forwarded to the one of the links depending on the outcome of their session.

Using merge codes with successlink and failurelink:

The redirect links can include standard URL merge codes as described above, but they can also include session merge codes, which allow you to pass session parameters or error information to the redirect link.

Some examples of session parameter merge codes:

  • __SESSIONPARAM_participant__
  • __SESSIONPARAM_locale__
  • __SESSIONPARAM_recorder__

The failurelink may use the merge code __SESSION_FAILURE_CODE__, which will be replaced by a code describing the reason the session failed.

Caveats

For testing purposes, this alternate syntax is supported:

If your experiment link does not intend to use the alternate syntax, it cannot include the character pair #! (pound-sign followed by an exclamation point).

Did this answer your question?