Agnitio Monitoring API (iPad)

From Agnitio WIKI

The following methods are used within the HTML5-code of a Presentation, to ensure that the appropriate Monitoring-events are triggered, and the appropriate monitoring-data is submitted

Contents 1 Introduction 2 Monitoring data testing guide documents 3 Examples 3.1 Basic monitoring 3.2 Custom monitoring 4 Monitoring API Methods 4.1 SubmitSlideEnter 4.2 submitSlideExit 4.3 submitDocumentOpen 4.4 submitReferenceOpen 4.5 submitCustomEvent 4.6 submitUniqueCustomEvent 5 See also

Introduction

The iPlanner monitoring API is built into the iPlanner app, and will allow you to save data from your presentation. Examples of data that you can save:

• Slide/page viewing information (name, parent, order, timings, date)
• Opened documents (name, order, date)
• Custom data (clicks, drag and drop order etc)

There are two steps you need to take in order to enable monitoring in your presentation:

• You need to refer to the built-in JavaScript file: ../viewer/js/monitor.js
• You need to set the variable monitoringEnabled to true: window.monitoringEnabled = true;

Monitoring data testing guide documents

• Agnitio monitoring submit guide [1]
• Agnitio monitoring check guide [2]
• Agnitio monitoring debug guide [3]

Examples

Basic monitoring

Basic monitoring is saving slide viewings and opening of documents. To save a slide viewing you will need to call the following when entering the slide:

 submitSlideEnter('slideId', 'slideName', slideIndex, 'parentName', 'grandparentName');

In the above example 'slideName' and 'slideId' are often the same, slideIndex is a number unique to the slide (but if not used you can set any number), 'parentName' is often the name of the slideshow but it is optional to include it (as is 'grandparentName').

To save that a document was opened you need to call the following when opening the document:

 submitDocumentOpen('documentId', 'documentName');

In the above example 'documentName' and 'documentId' are often the same.

Custom monitoring

You can save any data in your presentation as long as you can convert it into a string. There are two API methods you can use:

 submitCustomEvent('categoryName', 'labelName', 'dataValue', 'valueType');

 submitUniqueCustomEvent('categoryName', 'labelName', 'dataValue', 'valueType');

As you can see they are very much the same, but the difference is that submitCustomEvent() will save the data each time it is called (you will get an entry each time it is called), while submitUniqueCustomEvent() will only save the latest value (you will only get one entry no matter how many time it is called).

Monitoring API Methods

SubmitSlideEnter

 submitSlideEnter(slideId : String, slideName : String, slideIndex : int, parentSlideName : String, parentOfParentSlideName : String) : void; 

• If there is "unclosed" event, call submitSlideExit() with parameters from the previous submitSlideEnter() call and category set to slideExit.
• Monitoring event properties:
  • type = "system"
  • categoryId = null
  • category = "slideEnter"
  • labelId = "id"
  • label = "name"
  • valueId = slideId
  • value = slideName
  • valueType = null
  • time = now()
  • slideIndex = slideIndex
  • parentSlideName = parentSlideName
  • parentOfParentSlideName = parentOfParentSlideName

submitSlideExit

 submitSlideExit() : void; 

• Private method called by submitSlideEnter() or on presentation close.
• Monitoring event properties:
  • Type = "system"
  • categoryId = null
  • category = "slideExit"
  • labelId = "id"
  • label = "name"
  • valueId = slideId
  • value = slideName
  • valueType = null
  • time = now()
  • slideIndex = slideIndex
  • parentSlideName = parentSlideName
  • parentOfParentSlideName = parentOfParentSlideName

submitDocumentOpen

 submitDocumentOpen(documentId : String, documentName : String) : void; 

• Monitoring event properties:
  • type = "system"
  • categoryId = null
  • category = "documentOpen"
  • labelId = "id"
  • label = "name"
  • valueId = documentId
  • value = documentName
  • valueType = null
  • time = now()

submitReferenceOpen

 submitReferenceOpen(referenceId : String, referenceName : String) : void; 

• Monitoring event properties:
  • type = "system"
  • categoryId = null
  • category = "referenceOpen"
  • labelId = "id"
  • label = "name"
  • valueId = referenceId
  • value = referenceName
  • valueType = null
  • time = now()

submitCustomEvent

 submitCustomEvent(category : String, label : String, value : Object, valueType : String = null, categoryId : String = null, labelId : String = null, valueId : String = null) : void; 

• Monitoring event properties:
  • type = custom
  • categoryId = categoryId
  • category = category
  • labelId = labelId
  • label = label
  • valueId = valueId
  • value = value
  • valueType = valueType
  • time = now()

submitUniqueCustomEvent

 submitUniqueCustomEvent(category : String, label : String, value : Object, valueType : String = null, categoryId : String = null, labelId : String = null, valueId : String = null) : void; 

• Monitoring event properties:
  • type = custom
  • categoryId = categoryId
  • category = category
  • labelId = labelId
  • label = label
  • valueId = valueId
  • value = value
  • valueType = valueType
  • time = now()

See also

• Agnitio System Overview
• Contacts formating requirements
• Monitoring Model
• Monitoring data transfer
• Presentation transfer and update
• A Guide for Agencies
• IPad Presentation Development Guide
• Dynamic Survey System (DSS) - create your own survey
• Agnitio iPlanner
• Agnitio iPlanner Light