The current version of the telemetry specification is 3. Version 3 is a complete rewrite of the specification where we have generalized the events in 17 generic event types to be able to capture all possible use-cases and not tied to any specific domain.
Version 3.1
The telemetry version has been updated to 3.1 on 06/10/2021 with the addition of new optional attribute platform under the pdata section of the event envelope/structure.
The version 3 spec has provision to capture producer information in pdata as follows:
pdata: { "id": "", // unique id assigned to that component. For ex: "sunbird.mobile" in case of a mobile app or "sunbird.desktop" incase of desktop
"pid": "", // In case the component is distributed, then which instance of that component. For ex: "sunbird.mobile.contentplayer" incase of content player
"ver": ""// version number of the build. For ex: "3.9.437"}
However of late we have observed that there is increasing need to analyze the system/component usage by the underlying OS. For ex: Mobile usage distributed by android vs iOS is one example of it. Desktop usage segregated by Windows vs Ubuntu vs Mac is another example. To be able to support the need to analyze by the underlying platform we have introduced one more attribute platform under pdata as follows:
pdata: { "id": "", // unique id assigned to that component. For ex: "sunbird.mobile" in case of a mobile app or "sunbird.desktop" incase of desktop
"pid": "", // In case the component is distributed, then which instance of that component. For ex: "sunbird.mobile.contentplayer" incase of content player
"ver": "",// version number of the build. For ex: "3.9.437""platform": ""// Underlying OS platform. For ex: "Android/iOS/Windows/Ubuntu/MacOS"}
Telemetry V3 Event Structure
All events follow a common data structure, though the event data structure (“edata”) differs for each event. The complete data structure is as follows:
{
// About the event
"eid": , // Required. ID of the event
"ets": , // Required. Epoch timestamp of event (time in milli-seconds. For ex: 1442816723)
"ver": , // Required. Version of the event data structure, currently "3.1"
"mid": , // Required. Unique message ID. Used for deduplication, replay and update indexes
// Who did the event
"actor": { // Required. Actor of the event.
"id": , // Required. Id of the actor. For ex: uid incase of an user
"type": // Required. User, System etc.
},
// Context of the event
"context": { // Required. Context in which the event has occured.
"channel": , // Required. Channel which has produced the event
"pdata": { // Optional. Producer of the event
"id": , // Required. unique id assigned to that component
"pid": , // Optional. In case the component is distributed, then which instance of that component
"ver": , // Optional. version number of the build
"platform": "" // Optional. Underlying OS platform. For ex: "Android/iOS/Windows/Ubuntu/MacOS"
},
"env": , // Required. Unique environment where the event has occured.
"sid": , // Optional. session id of the requestor stamped by portal
"did": , // Optional. uuid of the device, created during app installation
"cdata": [{ // Optional. correlation data
"type":"", // Required. Used to indicate action that is being correlated
"id": "" // Required. The correlation ID value
}],
"rollup": { // Optional. Context rollups
"l1": "",
"l2": "",
"l3": "",
"l4": ""
}
},
// What is the target of the event
"object": { // Optional. Object which is the subject of the event.
"id": , // Required. Id of the object. For ex: content id incase of content
"type": , // Required. Type of the object. For ex: "Content", "Community", "User" etc.
"ver": , // Optional. version of the object
"rollup": { // Optional. Rollups to be computed of the object. Only 4 levels are allowed.
"l1": "",
"l2": "",
"l3": "",
"l4": ""
}
},
// What is the event data
"edata": {} // Required.
// Tags
"tags": [] // Optional. Encrypted dimension tags passed by respective channels
}
Note:
All events have the same structure with only difference in edata structures.
All events have unique event codes i.e., (IDs).
All events are as per platform schema
Events Specs
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.
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 to log telemetry when an object is changed. This includes life-cycle changes as well
Error - This method is used to capture when users face an error
Heartbeat - This method is used to log telemetry for heartbeat event to denote that the process is running
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 - This method is used to log telemetry for service business metrics
Summary - This method is used to log telemetry summary event
Exdata - This method is used as a generic wrapper event to capture encrypted or serialized data
End - This method is used to capture closure after all the activities are completed
Start
This API is used to log telemetry when users view content or initiate game play
The "edata" structure of Start is as follows:
{
"edata": {
"type": "", // Required. app, session, editor, player, workflow, assessment
"dspec": DSPEC, // Optional. Device spec
"uaspec": UASPEC, // Optional. User agent spec
"loc": "", // Optional. Location of the device
"mode": "", // Optional. Mode of start. For "player" it would be "play/edit/preview". For Workflow it would be Review/Flag/Publish. For editor it could be "content", "textbook", "generic", "lessonplan" etc
"duration": , // Optional. Time taken to initialize/start
"pageid": "" // Optional. Page/Stage id where the start has happened.
}
}
This API is used to log telemetry of user interactions on the page. For example, search, click, preview, move, resize, configure
The "edata" structure of Start is as follows:
data - Object //Required
{
"edata": {
"type": "", // Required. Type of interaction TOUCH,DRAG,DROP,PINCH,ZOOM,SHAKE,ROTATE,SPEAK,LISTEN,WRITE,DRAW,START,ENDCHOOSE,ACTIVATE,SHOW,HIDE,SCROLL,HEARTBEAT,OTHER
"subtype": "", // Optional. Additional types for a global type. For ex: for an audio the type is LISTEN and thesubtype can be one of PLAY,PAUSE,STOP,RESUME,END
"id": "", // Required. Resource (button, screen, page, etc) id on which the interaction happened - use systemidentifiers when reporting device events
"pageid": "", // Optional. Stage or page id on which the event happened
"target": TARGET, // Optional. Target context where the interaction has happened
"plugin": PLUGIN, // Optional. Plugin on which the interaction has happend
"extra": { // Optional. Extra attributes for an interaction
"pos": [{"x":,"y":,"z":}], // Array of positional attributes. For ex: Drag and Drop has two positional attributes. One where the drag has started and the drop point
"values": [], // Array of values, e.g. for timestamp of audio interactions
}
}
}
This API is used to log telemetry of assessments that have occured when the user is viewing content
The "edata" structure of Start is as follows:
{
"edata": {
"item": QUESTION, // Required. Question Data
"index": , // Optional. Index of the question within a content.
"pass": "", // Required. Yes, No. This is case-sensitive. default value: No.
"score": , // Required. Evaluated score (Integer or decimal) on answer(between 0 to 1), default is 1 if pass=YES or 0 if pass=NO.
"resvalues": [{"id":"value"}], // Required. Array of key-value pairs that represent child answer (result of this assessment)
"duration": // Required. time taken (decimal number) for this assessment in seconds
}
}
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.
The "edata" structure of Start is as follows:
{
"edata": {
"type": "", // Required. [m:background, m:resume]
"pageid": "" // Optional. Page id where the interrupt has happened
}
}
This API is used to log telemetry of feedback provided by the user.
The "edata" structure of Start is as follows:
{
"edata": {
"rating": 3, // Optional. Numeric score (+1 for like, -1 for dislike, or 4.5 stars given in a rating)
"comments": "User entered feedback" // Optional. Text feedback (if any)
}
}
This API is used to log telemetry for service business metrics (also accessible via health API).
The "edata" structure of Start is as follows:
data - Object - Required
{
"edata": {
"metric1": Int,
"metric2": Int
/// more metrics, each is a key value
}
}
Summary
This API is used to log telemetry summary event
The "edata" structure of Start is as follows:
{
"edata": {
"type": "", // Required. Type of summary. Free text. "session", "app", "tool" etc
"mode": "", // Optional.
"starttime": Long, // Required. Epoch Timestamp of app start. Retrieved from first event.
"endtime": Long, // Required. Epoch Timestamp of app end. Retrieved from last event.
"timespent": Double, // Required. Total time spent by visitor on app in seconds excluding idle time.
"pageviews": Long, // Required. Total page views per session(count of CP_IMPRESSION)
"interactions": Long, // Required. Count of interact events
"envsummary": [{ // Optional
"env": String, // High level env within the app (content, domain, resources, community)
"timespent": Double, // Time spent per env
"visits": Long // count of times the environment has been visited
}],
"eventssummary": [{ // Optional
"id": String, // event id such as CE_START, CE_END, CP_INTERACT etc.
"count": Long // Count of events.
}],
"pagesummary": [{ // Optional
"id": String, // Page id
"type": String, // type of page - view/edit
"env": String, // env of page
"timespent": Double, // Time taken per page
"visits": Long // Number of times each page was visited
}],
"extra": [{ // Optional. Additional summary data specific to mime type or app. For ex: wordsPerMin
"id": "", // Required. Key for the extra data
"value": "" // Required. Value for the extra data
}]
}
}
Exdata
This API is used to log telemetry for external data, while playing content
The "edata" structure of Start is as follows:
{
"edata": {
"type": "", // Free flowing text. For ex: partnerdata, xapi etc
"data": "" // Serialized data (can be either encrypted/encoded/stringified)
}
}
This API is used to log telemetry while the user is closing or exiting the content or game
The "edata" structure of Start is as follows:
{
"edata": {
"type": , // Required. app, session, editor, player, workflow, assessment
"mode": "", // Optional. Mode of start. For "player" it would be "play/edit/preview". For Workflow it would be Review/Flag/Publish. For editor it could be "content", "textbook", "generic", "lessonplan" etc
"duration": , // Optional. Total duration from start to end in seconds
"pageid": "", // Optional. Page/Stage id where the end has happened.
"summary": [{"key":"value"}] // Optional. Summary of the actions done between start and end. For ex: "progress" for player session, "nodesModified" for collection editor
}
}