The Sticky API is organised around REST. This means that we’ve designed it to have resource-oriented URLs and be as predictable as possible for you as developer. To test the API, you can use any REST client or try our own.
Below are the supported method calls for the API to interact with each type of data stored in the system. You must be logged in with the correct permissions to use these queries. Your user account will define which studies and media are visible based on their user groups.
Login
First and foremost, to be able to integrate with our API, create experiments, run sessions and read analytics, you will need to log into the system.
To do so, use following API request:
POST: https://eyeapi.sticky.ai/accounts/<<EMAIL_HERE>>/login?session=http
Payload:
{"password":"<<PASSWORD_HERE>>","username":"<<EMAIL_HERE>>"}
It should be sent with Content-Type of application/json. By running this request, you’ll receive Cookie in the response. We use cookie (session) based authentication, so in the following requests, it’ll be required to pass in the cookie.
Experiments (studies)
To run a study, you’ll need to create an experiment. This can be done using this API request:
POST: https://eyeapi.sticky.ai/experiments
Payload:
{"playlist":[],"lists":{}}
In the response, there will be an `id` of the experiment. This ID will be useful for upcoming requests in the flow to refer to this new experiment.
After creating an experiment, a sample should be created. It is done by requesting:
POST: https://eyeapi.sticky.ai/experiments/<<EXPERIMENT_ID_HERE>>/samples
Payload:
{
"segmentation":{
},
"crowd":{
"recorder":"webcam",
"mobile":false,
"orientation":null,
"participant_experience":"dcp",
"share":"redirect",
"locale":"en",
"surveyType":0,
"completes":100,
"channel":"release",
"eyetrack":"v3"
}
}
Depending on how many participants there should be, and if the sample should be mobile or desktop, payload should be modified. This request will return id of the sample in the response. This will be useful later when launching an experiment.
Media and Playlist items
To create a media, following steps should be taken:
POST: https://eyeapi.sticky.ai/media
Payload needs to be a binary file (image/video) sent as Form Data. In the response of this request, there will be id field which is ID of the media that was just created. It will be needed when creating playlist items. Playlist items are items displayed to the participants during a session. Each experiment has a list of playlist items that will be displayed.
To attach playlist items to the empty experiment that was created, run a following request:
PUT: https://eyeapi.sticky.ai/experiments/<<EXPERIMENT_ID_HERE>>
Payload:
{
"playlist":[
{
"id":"<<UNIQUE_UUID_HERE>>",
"type":"calibration",
"params":{
"pattern":"recalibrate_16"
}
},
{
"id":"<<UNIQUE_UUID2_HERE>>",
"name":"images.jpeg",
"type":"image",
"params":{
"contentId":"<<MEDIA_ID_HERE>>",
"advanceOnClick":false,
"advanceOnSpace":false,
"length":5,
"scrollable":0,
"is_thumbnail_icon":true
}
}
],
"lists":{
}
}
Playlist attribute is the list of playlist items. First element in the list for calibration we highly recommend to always include, since it will display calibration dots to the participant before any media, which will make our Eye Tracking algorithm perform significantly better.
The second item is related to attaching media that was created. Params field within this playlist item control how this media should behave - how long it should be displayed (in this case 5 seconds), if participant should be able to advance on click or space button and if it should be scrollable.
AOIs (Areas of Interest)
To create Areas of Interest, which are areas that will be analyzed together with the gaze data to provide metrics such as Seen %, Time until notice etc., following request should be used:
PUT: https://eyeapi.sticky.ai/media/<<MEDIA_ID_HERE>>/aois
Payload:
[
{
"name":"test",
"points":[
{
"x":0.3850267379679144,
"y":0.4230769230769231
},
{
"x":0.6149732620320856,
"y":0.4230769230769231
},
{
"x":0.6149732620320856,
"y":0.6709401709401709
},
{
"x":0.3850267379679144,
"y":0.6709401709401709
}
],
"color":[
183,
100,
219
],
"word_count":0,
"required":null,
"same_label_accepted":null,
"colorHex":"#b764db"
}
]
This is sample payload, but it shows that each AOI can have name, coordinates on the media and color that will be used to distinguish it within the system.
Once AOIs, playlist items and medias are set on experiment, we can launch and field it (show it to participants).
Launching
POST: https://eyeapi.sticky.ai/experiments/<<EXPERIMENT_ID_HERE>>/samples/<<SAMPLE_ID_HERE>>/field
Payload should be empty in this case. If the launch is successful, it should give status code of 200. To let participants, conduct the experiment, following link may be used:
https://tobii-data-collection.sticky.ai/<<SAMPLE_ID_HERE>>
Session Summary
To view number of complete and incomplete sessions, run following request:
GET: https://eyeapi.sticky.ai/experiments/<<EXPERIMENT_ID_HERE>>/sessionssummary
Analytics
To run analytics for specific experiment and media, following endpoints can be used:
Video heat maps:
https://eyeapi.sticky.ai/experiments/<<EXPERIMENT_ID_HERE>>/media/<<MEDIA_ID_HERE>>/analysis/videoheatmap?participants=%3CALL_SESSIONS%3E&alignment=start&aoi_overlay=true&kernel_size=0.15&fps=10&window=500&render=heatmap&gaze=raw&start_time=0&end_time=5000&media_file_size=4048&is_video=false&is_webpage=false
Picture heatmaps:
https://eyeapi.sticky.ai/experiments/<<EXPERIMENT_ID_HERE>>/media/<<MEDIA_ID_HERE>>/analysis/pictureheatmap?participants=%3CALL_SESSIONS%3E&alignment=start&aoi_overlay=false&kernel_size=0.15&export=webp&render=heatmap&gaze=raw&media_file_size=4048&is_video=false&is_webpage=false
AOI statistics:
IMPORTANT NOTE: Analytics API calls are permissible exclusively once an experiment has attained the "Complete" phase.
Fetch/Duplicate Experiments
To fetch all experiments, you’ve created in the system, run:
GET: https://eyeapi.sticky.ai/experiments?filter=editable_only
To duplicate existing experiment, following request can be used:
POST: https://eyeapi.sticky.ai/<<EXPERIMENT_ID_HERE>>/duplicate
The experiment will be duplicated without medias which will need to be uploaded again.