References

IntegrationAPI.Client

init

  • init. Starts collection initialization process.
        var config = {};
        config.apiKey = "{{apiKey}}"; //PUT THERE YOUR API KEY
        config.key = "myNewStudy";

        var video1 = {};
        video1.key = "TestVideo1";
        video1.url = "https://datacollection2cdn.realeyesit.com/IPSOS/video/3b488644-8a7f-4576-b96c-4af747276f35_converted.mp4";

        config.elements = [video1]
        Realeyesit.IntegrationAPI.Client.init('integrationContainer', config);    

onReady

  • onReady. Indicates that all API related stuff was downloaded and initialized and now ready to be used. Has 1 callback parameter. the callback will be executed when client will be ready.

showPrivacy.

  • showPrivacy. This is the simplest starting point of integration. It displays a welcome screen, and a privacy screen before the main flow is starting. Has 2 callback parameters.
var successCallback = function(msg) {
              alert(msg.state);
};

var failedCallback = function(msg) {
              alert(msg.state);
};

//if want to start the collection with every screens.
Realeyesit.IntegrationAPI.Client.showPrivacy(callback, failedCallback);

askWebcamPermissons.

  • askWebcamPermissons. Other starting point for integration. If you don’t want to see the welcome and privacy screens, just start the main flow. Asks user for webcam access. Has 4 parameters: 1 boolean dontCheckCameraQuality and 3 callback parameters, all of them will be called with one parameter, which contains two properties state and (optionally) reason.

    Possible values of the state property: readyToUse | allowed | denied | failed NOTE: state readyToUse will be returned only if parameter dontCheckCameraQuality = false, null or undefined. Otherwise the check web cam quality dialog will not be shown and final states for askWebcamPermissons will be: ‘allowed’ | ‘denied’

var successCallback = function(msg) {
              alert(msg.state);
};

var failedCallback = function(msg) {
              alert(msg.state);
};

var progressCallback = function(msg) {
              alert(msg.state);
};

//if want to ask webcam permissions and check quality of webcam immideatelly. Final states then readyToUse | denied | failed
Realeyesit.IntegrationAPI.Client.askWebcamPermissions(callback, failedCallback, progressCallback);

//or

//if want to ask webcam permissions. Final states then: allowed | denied | failed
Realeyesit.IntegrationAPI.Client.askWebcamPermissions(callback, failedCallback, progressCallback, true);

NOTE: if you set parameter dontCheckCameraQuality = true then you should execute checkWebcamQuality method before start playing medias. Otherwise it will be called automatically and check quality screen will be displayed

checkWebcamQuality.

  • checkWebcamQuality. Checks webcams and switchs to active webcam. Asks user to adjust environment if it needed. Has 3 callback parameters, all of them will be called with one parameter, which contains two properties state and (optionally) reason.

    Possible values of the state property: readyToUse

var successCallback = function(msg) {
              alert(msg.state);
};

var failedCallback = function(msg) {
              alert(msg.state);
};

var progressCallback = function(msg) {
              alert(msg.state);
};

Realeyesit.IntegrationAPI.Client.checkWebcamQuality(callback, failedCallback, progressCallback, dontCheckCameraQuality);

preloadMedias.

  • preloadMedias. Starts preloading the involved media. Has 3 callback parameters.
    • progressCallback: called with one parameter, contains 2 property state and progress, the latter has the following properties
  - itemsCount
  - loadedBytes
  - remainingBytes
  - remainingTimeEstimate
  - speed
  - totalBytes

Possible values of the state property: started
  • finishedCallback/failedCallback: called with one parameter, contains 2 properties state and reason.
Possible values of the state property: finished
var progressCallback=function(msg){
   if(msg.status=='started'){
       alert('download started');
   }
   if(msg.status=='donwloading'){
       alert(msg.progress.remainingTimeEstimate);
   }
}

var finishedCallback=function(msg){
   alert(msg.state); //msg.state='finished'
}

var failedCallback=function(msg){
     alert('Downloamd failed');
}

Realeyesit.IntegrationAPI.Client.preloadMedias(finishedCallback, failedCallback, progressCallback);

play

  • play. Start playing the involved media. Has 3 callback parameters, all of them will be called with one parameter, which contains two property; state and reason. ProgressCallback contains an additional property element that shows info about the current element like:
  • ExternalKey - key value of media from provided configuration

  • SequenceNo - sequence number of element during displaying

  • URL - url to media element

  • TestElementExternalKey - uniqe identity of test element (testElementKey from initial configuration)

    Possible values of the state property: started | playing | finish-playing | finished

Realeyesit.IntegrationAPI.Client.play(succesfullCallback, failedCallback, progressCallback)

startRecording

  • startRecording. Start the recording. Has 2 callback parameters, all of them will be called with one parameter, which contains two property; state and reason.

    Possible values of the state property: started | playing | finish-playing | finished

Realeyesit.IntegrationAPI.Client.startRecording(succesfullCallback, failedCallback)

stopRecording

  • stopRecording. Stop the recording. Has 2 callback parameters, all of them will be called with one parameter, which contains two property; state and reason.

    Possible values of the state property: started | playing | finish-playing | finished

Realeyesit.IntegrationAPI.Client.stopRecording(succesfullCallback, failedCallback)

addSessionStateListner

  • addSessionStateListner. Register a function as a new callback for session notification messages. Listener will be called with one parameter, which is a JSON object having 3 attributes
    • id: numeric representation of the state
    • name: name of the state
    • reason: complementary message to the state

Possible values of the state: * id: 13, name: ‘Collected’ * id: 14, name: ‘Declined’, * id: 15, name: ‘Failed’

var messageHandler=function(msg){
    alert(msg.name);
}

Realeyesit.IntegrationAPI.Client.addSessionStateListner(messageHandler);

getSessionInfo

  • getSessionInfo. Returns to you object with current sessionId and state with the following object:
{
sessionId,
stateId,
reasonId,
reasonName
}

there are list of all supported states:

ID-Name

  • 1- New
  • 2- Checking Environment
  • 3- Selecting Webcam
  • 4- Requesting Access to Webcam
  • 5- Checking Video Quality
  • 6- User is Correcting Environment
  • 7- Requesting Full Screen Permission
  • 8- Calibrating
  • 9- Processing Calibration
  • 10- Preloading Media
  • 11- Collecting
  • 12- Processing
  • 13- Collected
  • 14- Declined
  • 15- Failed
  • 16- Processed
  • 17- Processing Failed
  • 18- Checking Camera Feeds
  • 19- Connecting to media server

NOTE: reasonId and reasonName it’s autogenerated stuff and it can be just a text message which clarify why state was changed to current one.

Examples:

 {sessionId: 905688, stateId: 10, reasonId: 103, reasonName: "Environment Checks Succeeded"}
 {sessionId: 905688, stateId: 19, reasonId: 128, reasonName: "Media preloaded"}
 {sessionId: 905688, stateId: 13, reasonId: 201, reasonName: "Success, study completed, results submitted"}
Realeyesit.IntegrationAPI.Client.play(callback)

Example:

<script>
                 var parentWin = parent;
                 if (window.addEventListener) {
                     window.addEventListener("load", function () { startFunction(); });
                 } else if (window.attachEvent) {
                     window.attachEvent("onload", function () { startFunction(); });
                 }
                 var startFunction = function () {
                     var firstscript = parentWin.document.getElementsByTagName('script')[0];
                     var script = document.createElement('script');
                     script.type = 'text/javascript';

                     if (script.addEventListener) {
                         script.addEventListener("load", function () { insertFrame(); });
                     } else if (script.attachEvent) {
                         script.attachEvent("onload", function () { insertFrame(); });
                     }

                     script.async = 1;

                     script.src = '{{integrationScriptUrlManager}}';

                     firstscript.parentNode.insertBefore(script, firstscript);

                     //   head.appendChild(script);

                     var insertFrame = function () {
                         var newFrame = parentWin.document.createElement("frame");
                         newFrame.setAttribute("id", "dataCollectionIframe");
                         newFrame.setAttribute("name", "dataCollectionIframe");

                         newFrame.onload = function () {
                             parentWin.Realeyesit.IntegrationAPI.IntegrationManager.init(newFrame);
                             if (typeof callback === "function") {
                                 callback.apply(null, []);
                             }
                         };
                         newFrame.setAttribute("src", "//localhost:5006/kexbop?jsapienabled=true&origin=" + location.origin);
                         var mainFrame = parent.document.getElementById("mainFrame");
                         mainFrame.parentElement.rows = "*,1,1";
                         mainFrame.parentElement.appendChild(newFrame);
                     };
                 };
</script>

checkEnvironment.

  • checkEnvironment. checks if user’s environment is capable to run Realeyesit’s software. Checks if browser is capable, flash version, webcam etc. There are two parameters for the method:
    • succesfullCallback: register callback function which will be executed if environment is capable
    • failedCallback: register callback function which will be executed if environment isn’t capable

both callbacks will recieve next json object

//In case when all tests are passed
{
    checksPassed: true
    ,failureReasonCode: null
    ,failureReasonString: null
}
  
//In case when a check fails
{
    checksPassed: false
    ,failureReasonCode: 3
    ,failureReasonString: FLASH_BLACKLISTED
}

Possible failure reasons that we report

  • 1 - FLASH_NOT_INSTALLED
  • 2 - FLASH_TOO_OLD
  • 3 - FLASH_BLACKLISTED
  • 4 - BROWSER_BLACKLISTED
  • 5 - MOBILE_BROWSER
  • 6 - NO_WEBCAMS_DETECTED
  • 7 - OTHER_ERROR

Example:

var messageHandler=function(msg){
    alert(msg.name);
}

Realeyesit.IntegrationAPI.Client.checkEnvironment(messageHandler);

NOTE: All script files and other resources for the test execution are loaded over Amazon Web Services Cloudfront content delivery network with more than 35 edge locations across the world and are compressed to improve the user experience (except media files unless a CDN URL is given for them).

onError

onError. Indicates that an error occured during initialization or test process and normal flow of collection data can’t be continued.

addPostProcessingAction

Adds a URL callback action that is executed after the session was processed and marked as included or excluded.

No parameters will be attached to the URLs. In case you need extra identifiers, we suggest adding it to the callback URL.

Example:

// when session is included, call includedCallbackUrl
var dataIncluded = {
    url: includedCallbackUrl,
    trigger: 'included'
};

Realeyesit.IntegrationAPI.Client.addPostProcessingAction(dataIncluded);

// when session is excluded, call excludedCallbackUrl
var dataExcluded = {
    url: excludedCallbackUrl,
    trigger: 'excluded'
};

Realeyesit.IntegrationAPI.Client.addPostProcessingAction(dataExcluded);

IntegrationAPI.IntegrationManager

init

  • init. Starts collection initialization process. NOTE: we keep the method for backward compatibility. it should be used only if you are integrated our solution to frameset.

If you are using frameset then the structure and integration flow should be following:

  • main window (contains the frameset)
    • child frame with clients survey content
    • child frame with realeyes emotion measurement component

Main idea of the integration is that the survey software shows their content with usual flow and only when media playback with emotion measurement is needed, the software will send commands to Realeyes API via the Client (commands like: askPermissions, preloadMedia, play etc.) which in turn then displays the neccesary webcam prompts and media.

The frame approach is required because of the security requirements of webcam access. Namely the access to the webcam can only be requested for the duration of a single page and in case the survey consists of multiple pages, then it would mean bothering the user multiple times. Having it in a frame that’s never loaded, would work around that.

To make the integration work, all components should be placed correctly:

Integration manager should be included in the main window.

<head>
  <script src="{{integrationScriptUrlManager}}"></script>
</head>

Integration client should be included in the child iframe with survey content.

<head>
  <script src="https://codesdwncdn.realeyesit.com/IntegrationAPI/3/Realeyesit.IntegrationAPI.Client.min.js"></script>
</head>

The iframe with realeyes emotion measurement component should be added on page and src should have link like:

<frame id="dataCollectionIframe" name="dataCollectionIframe"
       src="https://collect.realeyesit.com/A807JJ?jsapienabled=true"/>

Obligatory attributes of the Iframe.

  • ID should be set to datacollectionIframe, so that our manager script can find it.
  • Src should be set with the following attributes
    • The baseUrl of the collection site (eg. http://stagecollect.realeyesit.com (our sandbox), http://collect.realeyesit.com (live platform))
    • The JsApiEnabled query string parameter, you have to set it true, thus you can communicate with our javascript API.
    • The isReviewer query string parameter, if true then session will be excluded from analysis.
    • The CustomParticipantID query string parameter, you should put your session\participant identity to the parameter.
    • (optional) The URL hash of the involved collection (eg. A8077J) NOTE: Be aware of the parent framesets rows/cols attribute, you might want to modify it after adding frames.
<frameset id="frameset" rows="*,1,1" border="0" frameborder="no" framespacing="0" noresize="">

Note: Pay attention not to reload our emotion measurement component iframe, because the webcam access will be lost that way and the user would need to be prompted for access again.

When all the component have been added and loaded then the init method should be called as below:

        var config = {};
        config.apiKey = "{{apiKey}}"; //PUT THERE YOUR API KEY
        config.key = "myNewStudy";

        var video1 = {};
        video1.key = "TestVideo1";
        video1.url = "https://datacollection2cdn.realeyesit.com/IPSOS/video/3b488644-8a7f-4576-b96c-4af747276f35_converted.mp4";

        config.elements = [video1]
        Realeyesit.IntegrationAPI.IntegrationManager.init(window.document.getElementById('dataCollectionIframe',config));

onReady

onReady. Indicates that all API related stuff was downloaded and initialized and now ready to be used. Has 1 callback parameter. the callback will be executed when manager will be ready.

onError

onError. Indicates that an error occured during initialization process and normal flow of collection data can’t be continued.