The iMotions Lab API
iMotions Lab provides an API to extend the capabilities of iMotions. Below you can read about some of the things that the API will allow you to do. For detailed documentation please refer to the Help Center.
Using the API requires advanced knowledge of programming and experience with sending and receiving events to an API
Event Forwarding
Forward events from iMotions Lab to a third party application with a real-time data feed.
During a respondent test, the software collects various types of data from different sources. In a dual screen setup, this data is used to provide visualizations. It is also cached in memory and logged to the database at the end of the test. During study analysis, the data is loaded from the database and used to perform the analysis and paint various visuals e.g. gaze replay. The data can also be exported to a text file so that 3rd party applications can be used to perform custom analysis.
The event forwarding interface extends this model to allow third party applications to receive the data in real time as it is received by the iMotions system. When an event is received by the software e.g. a mouse click or an eyetracker sample, the application will now check to see if event forwarding is enabled. If it is, the event is serialized into a text string, and the string is forwarded as an event message. An external application can listen for these event messages. It would then process the event as part of performing some application specific task. Typically, this would be used in a screen recording, where the application under test would be receiving the external events and adjusting behavior based on them e.g.
- The respondent could be shown different images based on where they looked in the previous image.
- If the last second of eyetracker data indicates that the respondent has looked away or closed their eyes, then an audible “wakeup” could be played to get the respondents attention. Imotions software can send events to an external application using either TCP or UDP.
- When using TCP, the software acts as a server and listens for connections on a specific port. Once a connection has been established with a client, iMotions will forward all event messages to the client using this connection. The client application simply needs to read the event messages from the connection.
- When using UDP, iMotions will send each event message as a UDP datagram to a configured server/port combination.
Event Receiving
Integrate custom devices or applications with iMotions.
iMotions currently supports a number of sensors for measuring a respondent’s state during a test e.g. Emotiv EEG, Affectiva QSensor. However there are many more sensor devices that a customer could use, and it is impractical for iMotions to support every such device. Instead it is envisaged that a 3rd party application would be created that interfaces with their desired device set, and then passes the data thus collected to iMotions software. This data will be treated in the same way as data collected from the sensors with built in support e.g. it will be synced with all other collected data, it can be visualised on a graph, will be stored in the database and saved with the study, will be available in the text data export for further analysis etc.
This document describes the method whereby a 3rd party application can send captured sensor readings to iMotions software.
NOTE:
Whilst we tend to focus on the “unsupported external sensor” scenario, it should be noted that there is no limitation to where the data arriving from the 3rd party application was sourced. It will be stored in the software as a stream of external events. Whether they originated from external sensor devices, or the values were generated internally by the 3rd party application is not important to iMotions.
Remote Control
The remote control API allows external programs to control the iMotions software i.e. perform certain tasks without interacting with the user interface. The following commands are available.
| Command | Action |
| Minimize | If idle, causes iMotions to minimize to the task bar. The software will not minimize if it is currently running a test. |
| Maximize | iMotions window will be restored. |
| Shutdown | iMotions will close. If running a test, then the command is rejected. |
| Run <Study> <Respondent> | iMotions will use the command parameters to select the study and respondent to test. Then a test will be run. If a test is already in progress, the command will be rejected. |
| Next Slide | Requests the slide-show to proceed to the next slide. Equivalent to the Shift-Space keyboard combination |
| Cancel Slide-show | Requests the slide-show to abort. Equivalent to Shift-F1. |
| Status | The Status command can be sent to iMotions at any time. It will send a response which will indicate if the software is idle or currently running a test. If a test is ongoing, then details of the current test will be included in the response. |
| Save <DataToSave> <Study> <Respondent> | If idle, iMotions will save the selected Study/Respondent to file. The resulting zip file will be saved in a configurable folder in the file system. The location of the zip file will be included in the command response. |
| Load <ZipFile> <TargetStudy> <AddMerge> | Loads the contents of a study export into iMotions. This will either create a new study or merge the data for the tested respondents in the zip file into an existing study. |
| Delete <Study> | Delete a study. |
| Export Sensor Data | Exports the study data to a raw text file that can be loaded into Excel, Matlab etc. |
| Export Video Recordings | Exports the screen or face-camera recordings to a folder. |
This limited set of commands is targeted at allowing a customer, with a large data collection network, to integrate iMotions software into their existing study distribution infrastructure.
API Guide and Documentation
Please consult the Help Center for a complete list of available commands and guides to using the API.
