Javascript Embed – Worked Example

This example will show you how to embed Stim Engine into a website and respond to events to guide participants through the viewing process. It’s so easy, we will use the JSFiddle online prototyping tool to show you!

Example code

  1. Empty Fiddle, ready for your code: https://jsfiddle.net/davexlabscomau/5055z9mh/1/
  2. Demo Fiddle, ready to be used: https://jsfiddle.net/davexlabscomau/7dgz2Lx4/109/
  3. Demo Fiddle viewing link (add /show ): https://jsfiddle.net/davexlabscomau/7dgz2Lx4/109/show/

Instructions

  1. Create a new JSFiddle at https://jsfiddle.net
  2. Paste in the HTML and Javascript snippets from the “empty fiddle” link above
  3. Login to Stim Engine, create a new Project.
  4. Add a Stim to your project, set AOIs and other options.
  5. In Stim Engine, select the ‘Code’ page from the menu on the left.
  6. Select your Project
  7. Adjust any options, such as enabling Emotion facial coding.
  8. Click ‘Generate code’
  9. You will see a blob of generated code. Copy it and paste it into the JS pane in your JSFiddle, between the “PASTE CODE HERE” comments.
  10. Modify the code to add handlers for broken missing cameras, incompatible devices and browsers, and any other errors (see below).
  11. Open the Fiddle in a new window with the /show suffix to execute the Fiddle and experience the Stim Engine data collection process.

About JS Fiddle

JSFiddle is a service that allows you to quickly try our HTML/Javascript and CSS experiments on the web. It’s a perfect way to test integration with Stim Engine.

Explanation of Demo Code

The demo code is very simple. It is just a page to embed the Stim Engine viewing code. It is configured to allow you to deploy a project for Amazon Mechanical Turk (MTurk). Participants must click the “Start” button, then follow the Stim Engine instructions, and view a video or image.

The way MTurk works is that when participants complete the task, you show them a code. They enter this code into the MTurk interface to prove they completed the task.

HTML code

The HTML code for the demo is very simple. We have a <div> element with a <h1> header. We have a “Start” button and a <p> element that’s used to display messages to the user.

Javascript code

The Javascript code is also very simple. We have a method “createCode()” that generates a random string to show to users who complete the task.

We have another method “showStatus( text )” which shows messages to the user in the <p> element described above.

We have our “viewStim” function which will wrap the code we paste from the Stim Engine, and a function called “onStartStimEngine()” that … starts the Stim Engine experience.

Pasting the Stim Engine Embed Code

The Stim Engine embed code should be pasted between the “PASTE CODE HERE” comments, in the viewStim function.

Set the Participant ID

You may want to link results in Stim Engine with survey questions and other data in pages that embed the viewer. The example code shows how to override the third-party (that’s you) participant identifier by setting the ‘newVisitor’ property of the JSON structure to “my-id-” + the current date. Of course, you can set it to anything you wish.

Adding handlers for events

After you have pasted the embed code, for a fully working demo it is necessary to handle some error conditions that may occur in a large sample. For example, not all users will have a working webcam.

Please refer to the “Demo Fiddle” link above for code changes we will make. The changes are described below. Note that there are other callbacks you can override to further customize the viewing experience.

onReady callback

This callback occurs when the Stim Viewer module is ready to start the session. We will add some code to implement a “fail safe” timer: If there is any problem tracking and measuring the emotions and eye/gaze of the user’s face, we will stop the viewer with stimViewer.abort() and then showStatus() an error message to explain.

showStatus( “Viewer ready.” );

if(!faceDetected) {

  failSafeTimer = setTimeout(function () {

    stimViewer.abort();

    showStatus( ‘Face not detected, or camera not found. You must have a working webcam to complete this task.’ );

  }, FAIL_SAFE_TIMER );

}

onFirstFace callback

As soon as the camera starts working, and a valid image is received, and we can actually see a human face, this callback occurs. This means we know we have a decent picture and the viewing should proceed. So, in response we cancel our “failsafe” handler to avoid aborting the session.

console.log(‘**** Detected face: Cancel failsafe.’);

clearTimeout( failSafeTimer );

failSafeTimer = null;

faceDetected = true;

onFinalised callback

This callback happens when the whole session has been recorded and uploaded to the server successfully. This is now the time to continue your survey, or thank users for participating. In our case, we will add code to show our users a completion code.

var status = “Your completion code is: ” + createCode();

showStatus( status );

Unsupported Browser exception

Currently Stim Engine works with Google Chrome (55% market share), Mozilla Firefox (27% market share) and Opera Browser (1% market share). In the near future we will add support for the Microsoft Edge browser. To filter out users with incompatible browsers, we throw an exception for these browsers. You should handle this exception by redirecting users to a screenout pathway or informing them they are not eligible to participate.

The only change we make to the code here, is to add one line to display a warning message to users who have incompatible browsers:

showStatus( status );

Unsupported Architecture exception

Currently Stim Engine only works with Desktop, Laptop and some tablet devices such as Microsoft Surface. In the near future we will add support for a range of tablets. To filter out users with incompatible devices, we throw an exception for these devices. You should handle this exception by redirecting users to a screenout pathway or informing them they are not eligible to participate.

The only change we make to the code here, is to add one line to display a warning message to users who have incompatible devices:

showStatus( status );

Running your Demo

Once you have modified the code as described above, you can share the link to your fiddle and test it with your colleagues! Feel free to share the link around.

For non-technical participants, add /show to your Fiddle’s URL. This will hide the source code and only show the HTML page.