Getting started

To measure emotions and behaviour, copy and paste the following code on every page you want to track, substituting the ‘accountId’ attribute with your own unique account ID.

<script>
(function (w, d, tn, p, n, e, f, co) { w['RealeyesitUBACore'] = n; w[n] = w[n] || function (m, h) { h.t = w[n].gt ? w[n].gt() : Date.now();co = {}, co.m = m, co.args = h; (w[n].q = w[n].q || []).push(co); }; e = d.createElement(tn), f = d.getElementsByTagName(tn)[0]; e.async = 1; e.src = p; f.parentNode.insertBefore(e, f) })(window, document, 'script', '//datacollection2cdn.realeyesit.com/DataCollectionSDK/live/realeyesit_UBA_SDK_js.min.js?v='+Date.now(), 'rubac');
rubac('initialize', {  accountId: 'aaaaaa-bbbbbb', plugins: ["youtube"], allowWebcamAccessTimeout: 25000 });
</script>

This code loads the Realeyesit_UBA_SDK_js.js bootstrap module asynchronously and initializes it once it’s loaded. The module will then load all necessary dependencies and set up our JavaScript communication interfaces. Moreover, it creates a global rubac function that works as a channel and can be used to communicate with our SDK.

In the initialization phase it uses the supplied accountId to associate the behavioural data with your account. The accountID is a fixed supplied string identifying account and collection, but can be extended to also specify campaign (ie. study) in order to segment results, see On the fly campaign creation

Then it optionally loads plug-ins specified as an array of names or settings objects. Plug-ins are modules with the necessary code to handle most frequent usage scenarios, such as video playback via YouTube player or video playback via the standard html5 video element. We already cover a few basic scenarios and more are on the way. However, if you find that we don’t support the scenario you are after, such as a specific video player, you can easily use our APIs to build a plug-in of your own.

The allowWebcamAccessTimeout parameter can be used to specify how many milliseconds later should the system continue playing the video, if the user doesn’t respond to the camera access prompt. This is an optional parameter, its value is 45 seconds by default and the minimum value it can take is 3 seconds.

Using Live Measurement in an iframe

If Live Measurement is injected into an iframe the iframe must have permission to access the camera otherwise Live Measurement will fail to record. For this the iframe tag must have an allow attribute with - at least - camera as value. Example:

<iframe allow="camera" id="LiveMeasurementIframe" width="800" height="600" src="//somedomain.com/collect"></iframe> 

This is due to the Feature-Policy specification that recent browsers started to support.

Opt-in prompt overlay handling

When you implement the minimum required to support the video player, users will see a regular webcam allow / deny prompt that appears when you try to access the webcam via WebRTC getUserMedia API.

While it covers the minimum requirements to make the tracking work, it’s not necessarily optimal from the user experience point of view, so we’ve implemented helper methods so that you can display additional prompts for users giving them more detail on why the webcam access is being requested, and why they should allow it. Usually these opt-in prompts will be overlaid on top of the video player.

While the overlay opt-in prompt is being shown, the video will be paused until access is given, denied or times out.

Implementing these overlay functions is optional, but strongly recommended.

pauseVideo - overlay-specific method. Called by our overlay manager to before showing the overlay. Should pause video, but you can use it for any activities that should be taken before showing the overlay when playing the video.

playVideo - overlay-specific method. Called by our overlay manager to after hiding the overlay. Should resume video if it was paused by pauseVideo, but you can use it for any activities that should be taken after hiding the overlay on a paused video.

getDisplayArea - overlay-specific method. Optimally, it returns an object with the DOM element (for example, the HTML5 video element) and the positioning rectangle (top, left, width, height) in it, like this: { domElement: htmlNode, rectangle: { top: number, left: number, width: number, height: number } }. However, you can return the rectangle object itself, describing the player’s display area in pixels or the DOM element whose display area (excluding margins) coincides with the player’s display area (e.g the player’s container or the player itself). This area will be used to show the overlay above. Note that when returning coordinates object, its values should be relative to the whole document. In that case we also display the overlay using absolute positioning. Such an approach has some drawbacks (e.g. showing overlay when player is hidden) that we have tried to solve in the second approach when you return a DOM element. You are also able to specify the z-index of the overlay, by setting the zIndex property on the rectangle object. Example: { domElement: htmlNode, rectangle: { zIndex: 500, top: number, left: number, width: number, height: number } }

NOTE: You can take a look at the complete implementation of YouTube player adapter in this repository - Realeyesit.Players.YouTube class.

Reporting the duration of videos is in seconds, but should be in milliseconds

Sending the duration in seconds will break reporting. You would need to change the following line to fix it (in RealeyesPlayerInterface.videoInfo):

duration: Math.round(adInfo.duration)

Calling convention of rubac from plugins

Sending commands or subscribing to events can be done via the previously mentioned rubac function. However, the name “rubac” is not fixed, it can be easily changed in the injection script, so it is better if you get the function reference in this way:

var rubac = rubac || window[window["RealeyesitUBACore"]];

Overlay z-index

It is possible to set the z-index CSS property of the overlay by returning the desired value in the getDisplayArea interface function. This is how we do it in one of our player interface:

    that.getDisplayArea = function () {
        var node = jQuery(this._video);
        var offset = node.offset();

        return {
            domElement: this._video,
            rectangle: {
                zIndex: 1000,
                top: offset.top,
                left: offset.left,
                width: node.width(),
                height: node.height()
            }
        };
    };

Related part in documentation: Writing a unified player interface implementation to support new video players, getDisplayArea

Implement the new start / stop API

To use the new API which allows better control over the emotion tracking refer to the following chapter in the documentation: Writing a unified player interface implementation to support new video players, Controlling the collection from the player

You can see an example implementation based on jwplayer from here https://datacollection2cdn.realeyesit.com/tests/JWPlayer/live/plugin/Realeyesit.Players.JWPlayer.js?v=1

Setting custom user identity

One may want to set predefined session/participant ID in order to link the session/participant to a third party system. You may also want to set the isReviewer flag for the session, if it is set to true this session will be excluded from the collection stats. This can be done with the help of the setIdentity / getIdentity API commands as seen in the example below:

    `rubac('setIdentity', { sessionId: '1', participantId: '2', isReviewer: true })` //set custom session id to 1, custom participant id to 2 and mark the session as a reviewer session.
    `rubac('setIdentity', { sessionId: '1' })` //set custom session id to 1
    `rubac('setIdentity', { participantId: '2' })` //set custom participant id to 2
    `rubac('setIdentity', { isReviewer: true })` //set isReviewer flag to exclude the session from stats.

You can also get this values (or default) with getIndentity command, for example:

    `rubac('getIdentity', function (identity) { var sid = identity.sessionId; var pid = identity.participantId })`
     //where sid would be custom or default session id and pid custom or default participant id

On the fly campaign creation

Using the accountId parameter one can segment the results by campaign (ie. study). That by adding a third section to the supplied accountId appended by a ‘-‘. That third section should be the name of the campaign that will be automatically created if non-existent yet.

Ex.:

  • supplied accountId: aaaaaa-bbbbbb
  • customized accountId: aaaaaa-bbbbbb-Any campaign name

Thus the injection script will look like this with a customized accountId:

<script>
(function (w, d, tn, p, n, e, f, co) { w['RealeyesitUBACore'] = n; w[n] = w[n] || function (m, h) { h.t = w[n].gt ? w[n].gt() : Date.now();co = {}, co.m = m, co.args = h; (w[n].q = w[n].q || []).push(co); }; e = d.createElement(tn), f = d.getElementsByTagName(tn)[0]; e.async = 1; e.src = p; f.parentNode.insertBefore(e, f) })(window, document, 'script', '//datacollection2cdn.realeyesit.com/DataCollectionSDK/live/realeyesit_UBA_SDK_js.min.js?v='+Date.now(), 'rubac');
rubac('initialize', {  accountId: 'aaaaaa-bbbbbb-Any campaign name', plugins: ["youtube"], allowWebcamAccessTimeout: 25000 });
</script>