Introduction to Realeyes Reporting Client Side SDK

Common

Realeyes Reporting Client Side SDK (hereinafter SDK) allows you to include Realeyes reports into your web site. To start using SDK you should add script tag for our realeyesit-reporting-visualization.js javascript file to the head section of your html page.

<script type="text/javascript" src="//reportingapicdn.realeyesit.com/sdk/v1/dev/realeyesit-reporting-visualization.js"></script>

The main citizen of our SDK is Realeyesit.Reporting.Visualization class that you will have to use in order to put any report on you page. To isolate our reports from your web page we render them inside the iframe element. The constructor of this class accepts only one parameter options, that describes which type of report to create and where to render. options object has the following structure:

{
   // required
   type: 'norms|emotionall',
   element: "elementId" // or DomElement,
   data: 'path' // or data object itself,
   
   // optional
   width: number|string,
   height: number|string,
   stylesheet: 'path',
   template: 'path',
   templateFunctions: object,
   onRendered: function(){...},
   onError: function(errorData){...}
}

type - name of the report you want to visualize.

element - id of the container html element or the element itself where the report’s iframe will be appended.

data - absolute or relative path to the data that will be used to create report. Usually it will be a url pointing to our Reporting Rest Api.

width - width of the report’s iframe element. Can be a number or string (e.g. “100%).

height - height of the report’s iframe element. Can be a number or string (e.g. “100%).

stylesheet - absolute or relative path to the stylesheet file that you would like to include inside report’s iframe document. This is usually used to customize report appearance. See “”Customizing reports”” paragraph for details.

template - absolute or relative path to the html template file that will be used to render report inside iframe. See “”Customizing reports”” paragraph for details.

onRendered - callback function that is called when the report finished rendering. The function is triggered in the context of current window global object, not iframe’s window.

onError - callback function that is called when an error occured when rendering the report. errorData is passed inside the callback. The structure of errorData is described in each report’s documentation page. The function is triggered in the context of current window global object, not iframe’s window.

templateFunctions - object whose properties represent the collection of javascript functions (key - name of the function, value - function body) that can be referenced inside template markup. See “”Customizing reports”” paragraph for details.

templateFunctions - object whose properties represent the collection of javascript functions (key - name of the function, value - function body) that can be referenced inside template markup. See “”Customizing reports”” paragraph for details.

Realeyesit.Reporting.Visualization class contains the following public methods:

{
   load: function(){...},
   refresh: function(){...}
}

load - loads and renders the report.

refresh - reloads the report.

This property list may be supplemented by additional parameters related to each separate report type. See each report’s documentation part for details.

Customizing reports

By default reports use our default designs. Sometimes you may want to customize report’s design. For this purpose we introduced different levels of customizations avaliable to you. All our reports use template model to render themself. Each report has its own html template that is compiled and filled in with data. You can find those templates under ‘sdk\html’ folder.

This is how the example simple template for missed calls report can look like:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
   <head>
      <link type="text/css" href="//.../simple-report.css" rel="stylesheet" />
      ...
      <script type="text/javascript" src="//.../simple-report.js"></script>
      ...
   </head>
   <body>
      <div data-template-id="root">
         Name: {{Name}} 
         <br/>
         Phone Number: <span data-template-id="Phone" class="phone"></span>
         <div data-template-id="MissedCalls">
            <p>{{Date}} {{Time}}</p>
         </div>
      </div>
   </body>
</html>

Each template file is usually a full html page markup, that contains the html template itself inside body element, css stylesheets in the head and javascript file that is responsible for compiling and rendering the template. It is important to note that only contents of the body element are processed as a template while outer markup is used to add external dependencies(stylesheets, javascript files)

To customize our report you have two options:

  1. use options object stylesheet parameter to pass in the url to your css file that will be appended to the end of our template and may add or override some styles there.
  2. create you own html template file and pass it as a template parameter inside options object. Basically you will copy our current template as a starting point.
  3. draw report yourself using data that you used to pass inside options object.

Lets examine the first option. This option is handy because it requires less work for you and is acceptable if you are glad with our template markup structure, but only want to restyle using only css capabilities. In the nearest version we will give you the possibility to include arbitary javascript file inside our template to do some complex styling that is not achievable using only css.

The second option is required when you want to take more control over markup of our template. You can copy our template file to you web server, modify it in any allowed way and reference inside options object. You can do almost anything with template but remember:

  • you should not remove existing javascript references from the file, because usually they are responsible for rendering the template.
  • you should modify the template (body contents) in such a way that it would not break the schema that is defined for each report in the documentation separately.

Lets see what does schema of the report template mean. Lets recall our missed calls report template example:

<div data-template-id="root">
   Name: {{Name}} 
   <br/>
   Phone Number: <span data-template-id="Phone" class="phone"></span>
   <div data-template-id="MissedCalls">
      <p>{{Date}} {{Time}}</p>
   </div>
</div>

Each part of the template (nested template) is identified by data-template-id attribute. When we will render the template we will use these attribute to find corresponsing parts of the report to render it’s contents. The {{Name}} interpolated form is used as a shortcut to <in data-template-id="Name"></in> nested template. By default it is styled as an inline text node. You can see that the template is hierarchical (contains other nested templates). Also each template element can contain additional attributes with specific meaning. These are the common list of such attributes:

  • on-rendered or data-on-rendered should contain the name of the javascript function that is called after the template finished rendering. The function is searched first in the templateFunctions obejct inside options object and if not found in the iframe’s window global object. The function is called with the following parameters function(element, data) where element is the template’s rendered Dom element and data is the data object used by the renderer. You can put data-on-rendered attribute on the root template element to trigger the function when the whole report finished rendering. This attribute is usually supported for majority of templates except of low level templates that render text values only. For those you can use formatter attribute.
  • formatter or data-formatter should contain the name of the javascript function that will be called to format the output. Function is called with one value parameter and should retrun the formatted string value instead. The input value parameter is string value in most cases but can also can be an object. This attribute is supported only on template elements that render text values.

In interpolated form of a template you can specify those attributes after : symbol, like {{Date:formatter(ToShortDate),on-rendered(OnDateRendered)}}.

In the result we can specify the schema of the template as set of rules that determine: ids(names) and hierarchical structure of the templates, optionality, list of supported attributes, their input and meaning. Usually we will specify the schema as a table. This the example table for the missed calls report template above:

template-idancestorrequireddefault formatteradditional info
rootbodyyes
Namerootno
Phonerootno
MissedCallsrootnolist template
DateMissedCallsno
TimeMissedCallsno

Note that default formatter column value shows if the rendered text data is preformatted by us. If some templates are required, but you still dont want to show these parts of report, use css customization to hide them. Majority of template ids can be defined multiply time inside template and will be rendered multiply times in turn without errors. This is not documented yet and can be used at your own risk.

Lets customize our above missed calls template for clarity:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
   <head>
      <link type="text/css" href="//.../simple-report.css" rel="stylesheet" />
      <style>
         .phone{
            color:red;
         }
      </style>
      ...
      <script type="text/javascript" src="//.../simple-report.js"></script>
      ...
      <script>
         function FormatPhone(value){
            ...
            return newvalue;
         };
         function FormatDate(value){
            ...
            return newvalue;
         };
      </script>
   </head>
   <body>
      <div data-template-id="root">
         {{Name}} - <span data-template-id="Phone" class="phone" data-formatter="FormatPhone"></span>
         <div data-template-id="MissedCalls">
            <div>Missed Call: {{Time}} {{Date:formatter(FormatDate)}}</div>
         </div>
      </div>
   </body>
</html>

Custom templates and versions

When overwriting our templates you should consider the versioning that we apply to our SDK by default. When you use realeyesit-reporting-visualization.js using our content delivery network you will always get uptodate version of our SDK (be aware of browser caching). This includes latest templates with latest stylesheets and renderers inside it. To overwrite our templates it is recommended to use templates that we already deployed to our CDN as a starting point because they differ from the source files in our repository: inside they reference to already bundled, minified css and javascript files that are also deployed to our CDN, so you won’t need maintain those dependencies yourself. For example norms this is how head section of norms report template on cdn reportingapicdn.realeyesit.com/sdk/v1/live/html/realeyesit-reporting-norms.tpl.html looks like:

<head>
   <link type="text/css" href="//reportingapicdn.realeyesit.com/sdk/v1/live/css/realeyesit-reporting-norms.1.0.css" rel="stylesheet" />
   <script type="text/javascript" src="//reportingapicdn.realeyesit.com/sdk/v1/live/libs/jquery-1.11.1.min.js"></script>
   <script type="text/javascript" src="//reportingapicdn.realeyesit.com/sdk/v1/live/libs/moment.min.js"></script>
   <script type="text/javascript" src="//reportingapicdn.realeyesit.com/sdk/v1/live/realeyesit-reporting-norms.1.0.min.js"></script>
</head>

You can compare it with the source file in the API package ‘sdk\html\realeyesit-reporting-norms.tpl.html’:

<head>  
    <link type="text/css" href="/css/realeyesit-reporting-common.css" rel="stylesheet" />
    <link type="text/css" href="/css/realeyesit-reporting-norms.css" rel="stylesheet" />
    <script type="text/javascript" src="/js/libs/jquery-1.11.1.min.js"></script>
    <script type="text/javascript" src="/js/libs/moment.min.js"></script>
    <script type="text/javascript" src="/js/src/realeyesit-reporting-templator.js"></script>
    <script type="text/javascript" src="/js/src/realeyesit-reporting-formatter.js"></script>
    <script type="text/javascript" src="/js/src/realeyesit-reporting-norms.js"></script>
</head>

Pay attention that inside CDN template css and javascript bundled files contain version inside (e.g. 1.0 inside realeyesit-reporting-norms.1.0.min.js). That is how we version SDK files and after next release the template will contain 1.1 version. But when you ve copied previous template file’s code to customize it, you stick with the previous 1.0 version files referenced inside. This is actually good because as long as you ve modified the template we there is a chance (though we try to avoid it) that future versions of stylesheet and javascript files can incorrectly style and render the modified template. If you still want to stick with the latest stylesheet and javascript files inside your modification of template you can just remove version suffix from cdn path realeyesit-reporting-norms.1.0.min.js -> realeyesit-reporting-norms.min.js inside your template. In this example realeyesit-reporting-norms.min.js always refers to the latest release version of file (be aware of browser caching).

NOTE: When using options object stylesheet parameter to inject your css inside our template you will use our latest template with latest dependecies inside.

Charting

Usage

As it is written in the Common section of the client side SDK, there are two ways to provide data source for the Reports. Ether you can provide a url or you can provide the JSON data itself.

  • Concrete example with the usage of the sample JSON

    <div id="chart-container"></div>
    
    <script type="text/javascript" src="http://reportingapicdn.realeyesit.com/sdk/v1/live/realeyesit-reporting-visualization.js"></script>
    <script type="text/javascript">
        
         var options = {
            type: "charting",
            element: "charting-container",
            data: "https://reportingapibucket.s3-eu-west-1.amazonaws.com/json/v1/realeyesit-reporting-charting.json",
            width: 1240,
            height: 1500,
            requestType: Realeyesit.Reporting.requestType.post
        };
    
        var visualization = new Realeyesit.Reporting.Visualization(options);
        visualization.render();
    </script>
    

Customization

For general customization possibilities please check the Common part of the client side SDK documentation. Download the latest template file realeyesit-reporting-norms.tpl.html (CDN) modify this template and reference it in the options object for customization.

Template structure

Here is the specified schema of the template as set of rules that determine: ids(names) and hierarchical structure of the templates, optionality, list of supported attributes.

template-idancestorrequireddefault formatteradditional info
rootbodyyes
templaterootyes
chartProgresstemplateno
showChartViewstemplateno
chartViewstemplateno
dynamicColorchartViewsyes
metricsColorchartViewsyes
metricsHueschartViewsyes
renderAreachartViewsyes
renderBarchartViewsyes
renderLinechartViewsyes
renderScatterchartViewsyeslist template
offsetStackchartViewsyes
offsetStreamchartViewsyes
offsetPctchartViewsyes
offsetValuechartViewsyes
smoothingchartViewsyes
smoothingSliderchartViewsyes
lagchartViewsyes
lagSliderchartViewsyes
resetButtonchartViewsyes
scaleFromchartViewsyes
scaleTochartViewsyes
scaleSliderchartViewsyes
mediaContainertemplatenolist template
videomediaContaineryes
imagemediaContaineryes
thumbnailmediaContaineryes
metrictemplatenolist template
metricDisplaymetricyes
filtertemplatenolist template
namefilteryes
filterButtonfilteryes
filterButtonDisplayfilterButtonyes
charttemplateno
yAxischartyes
graphchartyes
errorContainertemplatenoonly visible in case of chart error
errorMessageerrorContaineryes
aggregationTabletemplateno
tableHeadaggregationTableyeslist template
metricNametableHeadyes
tableRowaggregationTablenolist template
rowHeadertableRowyes
tableCelltableRownolist template
legendMarkertableCellyes
filterValuetableCellyesroundNumber || percentage formatter
preloadertemplateyes

Emotional All

Usage

As it is written in the Common section of the client side SDK, there are two ways to provide data source for the Reports. Ether you can provide a url or you can provide the JSON data itself.

  • Concrete example with the usage of the sample JSON

    <div id="emotionall-container"></div>
    
    <script type="text/javascript" src="http://reportingapicdn.realeyesit.com/sdk/v1/live/realeyesit-reporting-visualization.js"></script>
    <script type="text/javascript">
    
        var options = {
            type: "emotionAll",
            element: "emotionall-container",
            data: "https://reportingapibucket.s3-eu-west-1.amazonaws.com/json/v1/realeyesit-reporting-emotion-all.json",
            width: 1000,
            height: 480
        };
    
        var visualization = new Realeyesit.Reporting.Visualization(options);
        visualization.render();
    </script>
    

Customization

For general customization possibilities please check the Common part of the client side SDK documentation. Download the latest template file realeyesit-reporting-emotion-all.tpl.html (CDN) modify this template and reference it in the options object for customization.

Template structure

Here is the specified schema of the template as set of rules that determine: ids(names) and hierarchical structure of the templates, optionality, list of supported attributes.

<<
template-idancestorrequireddefault formatteradditional info
rootbodyyes
templaterootyes
mainTitletemplateno
emotionAllScoretemplateno
emotionAllNormstemplateno
attractionScoretemplateno
retentionScoretemplateno
engagementScoretemplateno
impactScoretemplateno
attractionRetentionTitletemplateno
attractionCharttemplateno
attractionScoretemplateno
attractionNormstemplateno
retentionCharttemplateno
retentionScoretemplateno
retentionNormstemplateno
engagementImpactTitletemplateno
engagementCharttemplateno
engagementScoretemplateno
engagementNormstemplateno
impactCharttemplateno
impactScoretemplateno
impactNormstemplateno
errorContainertemplateno
errorTexterrorContainerno
preloadertemplateno

Client Side Error Handling

After emotion all data is retrieved it is possible that it contains some errors in this case the charts are not rendered and error message is displayed on the screen

Error message types

  1. ErrorCode 1: No sufficient amount of emotion data In such cases the error messages can be the following:

     "There is not enough emotion data collected for this ad to generate an EmotionAll report."
     "Not enough similar ads to compare this ad with."
    
  2. ErrorCode 2: No media In such cases the error messages can be the following:

     "This video has been excluded from EmotionAll reporting"
    
  3. ErrorCode 3: EmotionAll report is not supported In such cases the error messages can be the following:

     "Current study type does not support EmotionAll report."
    
  1. ErrorCode 4: Not a video In such cases the error messages can be the following:

     "Selected ad is not a movie. EmotionAll report is available for movies only."
     "Current study type does not have movies. EmotionAll report is available for movies only."
    

Custom error handling

  • If custom error handling was implemented as it was explained on the Common section the returned error data has the following structure

    {
        emotionAllErrorCode: 1, 
        emotionAllErrorMessage: "There is not enough emotion data collected for this ad to generate an EmotionAll report.",
        mediaErrorCode: 4,
        mediaErrorMessage: "Selected ad is not a movie. EmotionAll report is available for movies only." 
    }
    

Norms

Usage

As it is written in the Common section of the client side SDK, there are two ways to provide data source for the Reports. Ether you can provide a url or you can provide the JSON data itself.

  • Concrete example with the usage of the sample JSON

    <div id="norms-container"></div>
    
    <script type="text/javascript" src="http://reportingapicdn.realeyesit.com/sdk/v1/live/realeyesit-reporting-visualization.js"></script>
    <script type="text/javascript">
    
        var options = {
            type: "norms",
            element: "norms-container",
            // Example data json
            data: "https://reportingapibucket.s3-eu-west-1.amazonaws.com/json/v1/realeyesit-reporting-norms.json",
            width: 1000,
            height: 480
        };
    
        var visualization = new Realeyesit.Reporting.Visualization(options);
        visualization.render();
    </script>
    

Customization

For general customization possibilities please check the Common part of the client side SDK documentation. Download the latest template file realeyesit-reporting-charting.tpl.html (CDN) modify this template and reference it in the options object for customization.

Template structure

Here is the specified schema of the template as set of rules that determine: ids(names) and hierarchical structure of the templates, optionality, list of supported attributes.

template-idancestorrequireddefault formatteradditional info
rootbodyyes
templaterootyes
mediaNametemplateno
thumbnailtemplatenolist template
normsMediasCounttemplateno
mediaCountriestemplatenodecode formatter
normsCountriestemplatenodecode formatter
mediaDurationtemplatenoduration formatter
normsDurationtemplateno
mediaViewstemplateno
normsViewstemplateno
mediaUpdatedtemplatenodateWord formatter
normsUpdatedtemplatenodateWord formatter
metricDataRowtemplatenolist template
metricmetricDataRowno
percentagemetricDataRownopercentage formatter
percentageNormmetricDataRownopercentage formatter
avgmetricDataRownopercentage formatter
avgNormmetricDataRownopercentage formatter
minmetricDataRownopercentage formatter
minNormmetricDataRownopercentage formatter
maxmetricDataRownopercentage formatter
maxNormmetricDataRownopercentage formatter
preloadertemplateyes