Iframe Integration

Realeyes collections can be integrated into webpages, surveys etc. by use of iframes. Iframes act as portals which display a webpage within a defined area of another webpage.

How the iframe integration works

The iframe displays a Realeyes facial coding test within a webpage, allowing the participant to remain on a single platform without the need to fully redirect them to a Realeyes page.

The facial coding test will broadcast a status message once a participant has completed, failed to complete, or declined to take the test. This message can be captured by an event listener (see below) and used to redirect participants appropriately, depending on their status.

How to integrate with the Realeyes collection client via iframes

  1. The Realeyes.CollectionListener.js script (the event listener) must be inserted somewhere on the page that displays the iframe. To do this, simply include the following HTML script line on the page.

        <script src="https://codesdwncdn.realeyesit.com/helpers/Realeyesit.CollectionListener.js"></script>
    
  2. (Optional) To be compatible with Internet Explorer 9 and below, json2.js must be inserted somewhere on the iframe page. The script can be downloaded from here.

  3. Insert the following event handler and message handler code below the Realeyes.CollectionListener.js script on the page. The message handler should then be set up to handle the participants as required.

        <script>
            window.onload = function() {
                Realeyesit.CollectionListener.listenTo(
                    document.getElementById('collectionIframe'), 
                    messageHandler
                );
            };
    
            var messageHandler = function(messageObj) {
    
        //Perform action(s) based on the attribute values of the messageObj
    
        }
        </script>
    
  4. Finally, insert the code for the iframe within the body tags of the page.

        <iframe id="collectionIframe" width="800" height="600" src="//collect.realeyesit.com/x0aUsv?CustomParticipantID=TEST_SESSION" allow="microphone; camera"></iframe> 
    

Please note the allow attribute of the iframe element that is crucial in order for the iframe to be able to access the camera and/or the microphone!

Once completed, the above steps provide a basic Realeyes iframe integration. The code has not been set up to do anything beyond displaying the facial coding test. Please see below for example implementations that demonstrate what can be achieved with the integration.

The message object structure

The message object (the message broadcast from the Realeyes collection client once the participant has completed, failed or declined to take the facial coding test) has three attributes:

  • id – A numeric representation of the participant’s state.
  • name – The name of the state.
  • reason – A brief description of the cause of the status. Mainly used to determine what technical issue caused the participant to fail the test (see below).

A participant can have one of three statuses:

  • Complete – id: 13, name: Collected. This indicates the participant has successfully completed the facial coding test
  • Declined – id: 14, name: Declined. This indicates the participant has declined to grant access to their webcam or quit part way through the test.
  • Failed – id: 15, name: Failed. This indicates the participant is not capable of taking the test due to a technical issue.

Participant IDs

Participants can be assigned unique IDs on the Realeyes collection platform by including the ID as a URL variable.

The ID must be provided to the Realeyes platform using the variable name ‘CustomParticipantID’.

An example of this can be seen in the iframe code (step 4) above. In this case the ID has been set to a static value of ‘TEST_SESSION’, however when implementing the iframe integration the ID should be unique and dynamically inserted into the URL per session.

This ID can then be used to merge any survey or demographic data with the emotions data after the project has closed.

Examples

Here are some additional more common example implementations of the messageHandler function:

  1. Redirect participants based on their status; Complete participants sent to a ‘Thank you’ page, and Failed and Declined participants sent to a disqualification page.

        var messageHandler = function (messageObj) {
    
            //if the status of the participant is ‘collected’ (complete)…
            if (messageObj.id === 13) {
               //This is a fake URL and must be replaced
                window.location = 'http://fake-survey.com/thank_you_page';
    
            }
            //if the status of the participant is ‘failed’ or ‘declined’ (non-complete)…
            else {
                //This is a fake URL and must be replaced
                window.location = 'http://fake-survey.com/disqualified';
            }
        };
    
  2. Allow participants who were classed as Failed due to not having a webcam the chance to retry once they have fixed the issue.

    
        var messageHandler = function (messageObj) {
    
            //if the ID of the participant's status is 14 or 15 (Declined or failed respectively)...
            if (messageObj.id === 14 || messageObj.id === 15) {
            
                //if the reason for the failure is "No Webcam"...
                if (messageObj.reason === "No Webcam") {
            
                    //Display a confirmation box that gives the participant the chance to plug in their webcam
                    if (confirm("Please connect a webcam and press 'Ok', or 'Cancel' if you do not have one or are not willing to use it.")) {
                    
                        //Reload the page if the participant presses Ok
                        window.location.reload();
                    }
                    else {
                    
                        //If the participants pressed cancel, redirect participant to a disqualified page.
                        window.location = 'http://fake-survey.com/disqualified';
                    }
                }
                
                //if the reason for the failure is not "No Webcam" then redirect to a disqualified page
                else {
                
                    //Redirect the participant to a disqualified page.
                    window.location = 'http://fake-survey.com/disqualified';
                }
            }
            
            //if the ID of the participant's status is not 14 or 15, meaning they are a complete...
            else {
            
                //Redirect the participant to a thank you page.
                window.location = 'http://fake-survey.com/thank_you_page';
            }
        };