Need

The purpose of a standalone JS library for telemetry is to facilitate capture and distribution of telemetry data by users who would like to use their own apps, content players or portals.

We chose to use a JS library for the following reasons:

• All the telemetry events that are generated and synced to the server have the same format (field data types and time zone value)

• It is easy to upgrade to new versions, in case of major changes in telemetry

• There is effortless backward compatibility, as changes are handled within the telemetry library. Any upgrade of the telemetry library does not require code changes in the content

• There are reduced number of API calls

• There are simple API methods to generate the complete telemetry event as only the required fields are passed

Prerequisites

The following are prerequisites to use or integrate the JS library:

• JQuery library should be available

• Valid Authtoken and Key to make API calls

• The telemetry.min.js{:target="_blank"} file

Note: For details on generating and using the Authtoken and Key, refer to the section

• Device ID value

Note: For details on how to get the device ID value, refer to website{:target="_blank"}

Configure

This JS library helps to generate telemetry events. These events sync to the server or data-pipeline in a batch as defined in the configuration. To log telemetry events, the user has to call the start method by passing the configuration along with other parameters.

Note: All telemetry events sync only to the server or data-pipeline, when connected to the Internet.

Telemetry events are generated based on the configuration of the telemetry library.

Required Configuration (Context)

Additional Configuration

Sample:

Dispatcher:

User can define custom dispatcher to override the default functionality of telemetry sync. By default telemetry events will send to default server/host. User can override this default functionality by defining his own "dispatcher" object to handle telemetry events.

Send this object as dispatcher in the above sample configuration ("dispatcher":customDispatcher).

How to use telemetry JS library

Download the telemetry-sdk npm module from here

Example:

To use the telemetry JS libraries, add the following to your HTML/application. The file path is a relative path, for example; assets/js to the associated files within the html content.

Telemetry API methods

Every API method has an associated event. The following API methods log details of the associated telemetry event.

• Start - This method initializes capture of telemetric data associated to the start of user action

• Impression - This method is used to capture telemetry for user visits to a specific page.

• Interact - This method is used to capture user interactions on a page. For example, search, click, preview, move, resize, configure

• Assess - This method is used to capture user assessments that happen while playing content.

• Response - This method is used to capture user responses. For example; response to a poll, calendar event or a question.

• Interrupt - This method is used to capture  interrupts triggered during user activity. For example;  mobile app sent to background, call on the mobile, etc.

• End - This method is used to capture closure after all the activities are completed

• Feedback - This method is used to capture user feedback

• Share - This method is used to capture everything associated with sharing. For example; Share content, telemetry data, link, file etc.

• Audit - This method is used when an object is changed to know previous and current state. This includes lifecycle changes as well.

• Error - This method is used to capture when users face an error

• Heartbeat - This method is used to know is process is running or not.

• Log - This method is used to capture generic logging of events. For example; capturing logs for API calls, service calls, app updates etc.

• Search - This method is used to capture the search state i.e. when search is triggered for content, item, assets etc.

• Metrics - Service business metrics (also accessible via health API)

• Summary - Summary event

• Exdata - This method is used as a generic wrapper event to capture encrypted or serialized data

Start

This API is used to log telemetry when users view content or initiate game play

Request Arguments:

Impression

This API is used to log telemetry when users visit a specific page.

Request Arguments:

Interact

This API is used to log telemetry of user interactions on the page. For example, search, click, preview, move, resize, configure

Request Arguments:

Assess

This API is used to log telemetry of assessments that have occured when the user is viewing content

Request Arguments:

Response

This API is used to log telemetry of user response. For example; Responded to assessments.

Request Arguments:

Interrupt

This API is used to log telemetry for any interruptions that have occurred when a user is viewing content or playing games. For example; screen lock, incoming call, etc.

Request Arguments:

Feedback

This API is used to log telemetry of feedback provided by the user.

Request Arguments:

Share

This API is used to log telemetry when a user shares any content with other users.

Request Arguments:

Audit

This API is used to log telemetry when an object is changed. This includes life-cycle changes as well.

Request Arguments:

Error

This API is used to log telemetry of any error that has occurred when a user is viewing content or playing games.

Request Arguments:

Heartbeat

This API is used to log telemetry for heartbeat event to denote that the process is running.

Request Arguments:

Log

This API is used to log telemetry of generic log events. For example; API calls, service calls, app updates, etc.

Request Arguments:

Search

This API is used to log telemetry when a user triggers a search for any content, item or asset

Request Arguments:

Metrics

This API is used to log telemetry for service business metrics (also accessible via health API).

Request Arguments:

Summary

This API is used to log telemetry summary event

Request Arguments:

Exdata

This API is used to log telemetry for external data, while playing content

Request Arguments:

End

This API is used to log telemetry while the user is closing or exiting the content or game

Request Arguments:

ResetContext

This is used to reset the current context value with new context object.

ResetObject

Which is used reset the current object value with new obj

ResetActor

Which is used reset the current actor value with new actor

ResetTags

Which is used to reset the current tag's value with new tag's

ChangeLogs

0.0.1

• Initial version of the telemetry-sdk npm

0.0.2

• Bug fixes

0.0.3

• Name space changes in the code
• Removed EkTelemetry keyword in the code and provided a backward compatibility

0.0.4

• Bug fixes - Duration issue fix in both START and END Event (Converting millisecond to seconds)

• Test case setup and improved code coverage

• Travis integration