It is an string containing unique device id.
" |
| endpoint | It is an string containing API endpoint. Please don't change default value. Update this only when the data is proxied | optional | Defaults to "/v3/telemetry" |
| tags | It is an array. It can be used to tag devices so that summaries/metrics can be derived via specific tags. Helpful during analysis | optional | Defaults to \[] |
| cdata | It is an array. Correlation data. Can be used to correlate multiple events. Generally used to track user flow | optional | Defaults to \[] |
| dispatcher | | | |
**Sample:**
```
{
"pdata": {
"id": "genie",
"ver": "6.5.2567",
"pid": ""
},
"env": "ContentPlayer",
"channel": "XXXX",
"did": "20d63257084c2dca33f31a8f14d8e94c0d939de4",
"authtoken": "XXXX",
"uid": "anonymous",
"sid": "85e8a2c8-bb8e-4666-a21b-c29ec590d740",
"batchsize": 20,
"mode": "play",
"host": "XXXX",
"endpoint": "/v3/telemetry",
"tags": [],
"cdata": []
}
```
**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.
```
var customDispatcher = {
dispatch: function(event){
// User defined logic to send telemetry to server or store locally etc..
}
};
```
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](https://www.npmjs.com/package/@project-sunbird/telemetry-sdk)
```
npm i @project-sunbird/telemetry-sdk
```
**Example:**
```
$t = require('@project-sunbird/telemetry-sdk');
$t.start(config, contentId, contentVer,data, options);
```
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](/use/jslibrary#start) - This method initializes capture of telemetric data associated to the start of user action
* [Impression](/use/jslibrary#impression) - This method is used to capture telemetry for user visits to a specific page.
* [Interact](/use/jslibrary#interact) - This method is used to capture user interactions on a page. For example, search, click, preview, move, resize, configure
* [Assess ](/use/jslibrary#access)- This method is used to capture user assessments that happen while playing content.
* [Response](/use/jslibrary#response) - This method is used to capture user responses. For example; response to a poll, calendar event or a question.
* [Interrupt](/use/jslibrary#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](/use/jslibrary#end) - This method is used to capture closure after all the activities are completed
* [Feedback](/use/jslibrary#feedback) - This method is used to capture user feedback
* [Share](/use/jslibrary#share) - This method is used to capture everything associated with sharing. For example; Share content, telemetry data, link, file etc.
* [Audit](/use/jslibrary#audit) - This method is used when an object is changed to know previous and current state. This includes lifecycle changes as well.
* [Error](/use/jslibrary#error) - This method is used to capture when users face an error
* [Heartbeat](/use/jslibrary#heartbeat) - This method is used to know is process is running or not.
* [Log](/use/jslibrary#log) - This method is used to capture generic logging of events. For example; capturing logs for API calls, service calls, app updates etc.
* [Search](/use/jslibrary#search) - This method is used to capture the search state i.e. when search is triggered for content, item, assets etc.
* [Metrics](/use/jslibrary#metrics) - Service business metrics (also accessible via health API)
* [Summary](/use/jslibrary#summary) - Summary event
* [Exdata](/use/jslibrary#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
```
start: function(config, contentId, contentVer, data, options) { }
```
Request Arguments:
```
let config = Object; // Telemetry Configurations
let contentId = String; //Required. Id of the content
let contentVer = String; //Required. Version of the content. Defaults to "1.0"
let data = { // Required. event data
"type": String, //Required. app, session, editor, player, workflow, assessment
"mode": "", //Required. mode of preview: preview, edit or play
"stageid": "" //Required. stage id where the play has been initiated
};
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Impression
This API is used to log telemetry when users visit a specific page.
```
impression: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"type": String, //Required. Impression type (list, detail, view, edit, workflow, search)
"subtype": String, //Optional. Additional subtype. "Paginate", "Scroll"
"pageid": String, //Required. Unique page id
"itype": "", // type of interaction - SWIPE, SCRUB (fast forward using page thumbnails) or AUTO
"stageto": "" // game level, stage of page id to which the navigation was done
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Interact
This API is used to log telemetry of user interactions on the page. For example, search, click, preview, move, resize, configure
```
interact: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"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
"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
"tid": "", // When interaction is between multiple resources, (e.g. drag and drop) - target resource id
"uri": "" // Unique external resource identifier if any (for recorded voice, image, etc.)
}
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Assess
This API is used to log telemetry of assessments that have occured when the user is viewing content
```
assess: function(data, options) { }
```
Request Arguments:
```
let QUESTION = {
"id": "", // unique assessment question id. its an required property.
"maxscore", // user defined score to this assessment/question.
"exlength": , // expected time (decimal number) in seconds that ideally child should take
"params": [ // Array of parameter tuples
{ "id": "value" } // for ex: if var1 is substituted with 5 apples the parameter is {"var1":"5"}
],
"uri": "", // Unique external resource identifier if any (for recorded voice, image, etc.)
"desc": "short description",
"title": "title",
"mmc": [], // User defined missing micros concepts
"mc": [] // micro concepts list
}
let data = { //Required
"item": QUESTION, // Required. Question Data
"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
};
```
```
let options = { //Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Response
This API is used to log telemetry of user response. For example; Responded to assessments.
```
response: function(data, options) { }
```
Request Arguments:
```
let TARGET = {
"id": "", // Required. unique id for the target
"ver": "", // Required. version of the target
"type": "", // Required. Type of the target
"parent": {
"id": "", // Optional. parent id of the object
"type": "" // Optional. parent type of the object. Required if parentid is present.
}
};
let data = { // Required
"target": TARGET, // Required. Target of the response
"qid": "", // Required. Unique assessment/question id
"type": "", // Required. Type of response. CHOOSE, DRAG, SELECT, MATCH, INPUT, SPEAK, WRITE
"values": [{ "key": "value" }] // Required. Array of response tuples. For ex: if lhs option1 is matched with rhs optionN - [{"lhs":"option1"}, {"rhs":"optionN"}]
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### 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.
```
interrupt: function(data, options) { }
```
Request Arguments:
```
let data = { //Required
"type": "", // Required. Type of interuption
"pageid": "", // Optional. Current Stage/Page unique id on which interuption occured
"eventid": "" // Optional. unique event ID
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Feedback
This API is used to log telemetry of feedback provided by the user.
```
// To log content start/play event
feedback: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"contentId": "", // Required. Id of the content
"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)
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Share
This API is used to log telemetry when a user shares any content with other users.
```
// To log content start/play event
share: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"dir": "", // In/Out
"type": "", // File/Link/Message
"items": [{ // Required. array of items shared
"obj": {
"id": "",
"type": "",
"ver": ""
},
"params": [
{ "key": "value" }
],
"origin": { // Origin of the share file/link/content
"id": "", // Origin id
"type": "" // Origin type
},
"to": {
"id": "",
"type": ""
}
}]
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Audit
This API is used to log telemetry when an object is changed. This includes life-cycle changes as well.
```
audit: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"edata": {
"props": [""], // Updated properties
"state": "", // Optional. Current state
"prevstate": "" // Optional. Previous state
}
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Error
This API is used to log telemetry of any error that has occurred when a user is viewing content or playing games.
```
error: function(error, options) { }
```
Request Arguments:
```
let error = { // Required
"err": "", // Required. Error code
"errtype": "", // Required. Error type classification - "SYSTEM", "MOBILEAPP", "CONTENT"
"stacktrace": "", // Required. Detailed error data/stack trace
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Heartbeat
This API is used to log telemetry for heartbeat event to denote that the process is running.
```
heartbeat: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"edata": {}
}
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Log
This API is used to log telemetry of generic log events. For example; API calls, service calls, app updates, etc.
```
log: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"type": "", // Required. Type of log (system, process, api_access, api_call, job, app_update etc)
"level": "", // Required. Level of the log. TRACE, DEBUG, INFO, WARN, ERROR, FATAL
"message": "", // Required. Log message
"params": [{ "key": "value" }] // Optional. Additional params in the log message
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Search
This API is used to log telemetry when a user triggers a search for any content, item or asset
```
search: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"type": "", // Required. content, assessment, asset
"query": "", // Required. Search query string
"filters": {}, // Optional. Additional filters
"sort": {}, // Optional. Additional sort parameters
"correlationid": "", // Optional. Server generated correlation id (for mobile app's telemetry)
"size": 333, // Required. Number of search results
"topn": [{}] // Required. top N (configurable) results with their score
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Metrics
This API is used to log telemetry for service business metrics (also accessible via health API).
```
metrics: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"edata": {
"metric1": Int,
"metric2": Int
/// more metrics, each is a key value
}
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Summary
This API is used to log telemetry summary event
```
summary: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"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
}]
}
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### Exdata
This API is used to log telemetry for external data, while playing content
```
exdata: function(data, options) { }
```
Request Arguments:
```
let data = {
"type":"" - Free flowing text.For ex: partnerdata,xapi etc
....Serialized data(can be either encrypted / encoded / stringified)
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### End
This API is used to log telemetry while the user is closing or exiting the content or game
```
end: function(data, options) { }
```
Request Arguments:
```
let data = { // Required
"contentId": "", // Required. Id of the content
"type": "", // Required. app, session, editor, player, workflow, assessment
"duration": "", // Required. Total duration from start to end in seconds
"pageid": "", // Optional. Page/Stage id where the end has happened.
"summary": [{ "key": "value" }] // Optional. Summary of actions done between start and end. For ex: "progress" for player session, "nodesModified" for collection editor
};
```
```
let options = { // Optional
context: {}, // To override the existing context
object: {}, // To override the existing object
actor: {}, // To override the existing actor
tags: {}, // To override the existing tags
runningEnv: "server" // It can be either client or server
};
```
### ResetContext
This is used to reset the current context value with new context object.
```
@param {context} Object - If context is undefined then library is reset to previous event context value.
$t.resetContext(context)
```
### ResetObject
Which is used reset the current object value with new obj
```
@param {obj} Object - If the Object is undefined then library is reset to previous event object value.
$t.resetObject(obj)
```
### ResetActor
Which is used reset the current actor value with new actor
```
@param {actor} Object - If the actor is undefined then library is reset to previous event actor value.
$t.resetActor(actor)
```
### ResetTags
Which is used to reset the current tag's value with new tag's
```
@param {tags} Array - If tags are undefined then library is reset to previous event tags value.
$t.resetTags(tags)
```
## ChangeLog
**Jan 2018**
* For the `start` event, Changed the both `contentId` and `contentVer` to an optional parameters from mandtory.
* Decoupling of the both init and start methods.
* Introduced new initialize method, Where user can initialize the telemetry without calling `start` event. [More details](/use/jslibrary#initialize)
* Introduced new context parameter in all telemetry event methods, Where user can easily update the context value for each event.
* Introduced `resetContext` method, Which is used to reset the context to new context value/global context. [More details](/use/jslibrary#resetcontext)
* Introduced `resetObject` method, Which is used to reset the current object value. [More details](/use/jslibrary#resetobject)
* Introduced `resetTags` method, Which is used to reset the current tags value. [More details](/use/jslibrary#resettags)
* Introduced `resetActor` method, Which is used to reset the current actor value. [More details](/use/jslibrary#resetactor)
* Previously if the user invokes an end event then the user must and should invoke start event to initialize the telemetry. but in the updated on no need to invoke start event because telemetry is initialized globally.
* Bug fixes
# html\_interface\_library
## Need
The HTML interface library eases the HTML developer’s effort to log telemetry events from HTML content. It uses simple API methods exposed by the library to log associated events. The reasons to develop the HTML interface library are:
* Any HTML content can package the interface library as part of the content. Thus using the library, the HTML content can log telemetry events.
* There are simple API methods to generate the complete telemetry event as only the required fields are passed
* It is easy to upgrade to new versions, in case of major changes in the telemetry library
* 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
* The library will handle logging of events from HTML content when it is playing in case portal or device/app.
## How to use HTML interface library
Add the following to your HTML Content:
The file\_path is the relative path (eg. assets/js) to these files within the html content.
```
//you can log telemetry interact event as shown below
org.ekstep.contentrenderer.interface.telemetryService.interact(data)
//or
RI.telemetryService.interact(data)
```
## API methods
The HTML interface provides simple methods to log telemetry, to handle the ContentRenderer overlay, to get content information, etc.
The HTML interface exposes the following list of API methods:
* [dispatchEvent](/use/html_interface_library#dispatchevent) - This method helps dispatch events to the ContentRenderer to handle specific functionality of ContentRenderer
* [getcontentMetadata](/use/html_interface_library#getcontentmetadata) - This method is used to access content metadata
* [getConfig](/use/html_interface_library#getconfig) - This method is used to access content-renderer configuration
* [gotoEndPage](/use/html_interface_library#gotoendpage) - This method helps to open the ContentRenderer end page after HTML content is completely viewed
* [exit](/use/html_interface_library#exit) - This method helps to close the ContentRenderer
* [telemetryService.interact](/use/html_interface_library#telemetry-interact)- This method helps to log telemetry interact event
* [telemetryService.impression](/use/html_interface_library#telemetry-impression) - This method helps to log the Impression event on page or state change
* [telemetryService.response](/use/html_interface_library#telemetry-response) - This method helps to log telemetry response event when an option is selected during an assessment
* [telemetryService.assessmentStart](/use/html_interface_library#telemetry-assessmentstart) - This method is used when an assessment begins and it returns the event object
* [telemetryService.assess](/use/html_interface_library#telemetry-assess) - This method helps to log the Assess event when the assessment is evaluated
* [telemetryService.exdata](/use/html_interface_library#telemetry-exdata) - This method helps log the telemetry ExData event
### DispatchEvent
Dispatch an specific event to control ContentRenderer functionalities.
```
/**
* eventName - Event name that has to dispatch to handle ContentRenderer functionality
*/
dispatchEvent: function(eventName) {
// dispatch event to control ContentRenderer functionalities
}
```
### getcontentMetadata
This will return the content metadata information(HTML Cotnent metadata here).
```
/**
* contentId - Current opened HTML content identifier
* cb - callback function after after getting content iformation from API call
*/
getcontentMetadata = function(contentId, cb){
}
```
### getConfig
This will return the content renderer configuration. This will help to know what is the context of HTML content playing in ContentRenderer.
```
getConfig = function(){
}
```
### gotoEndPage
After completion of HTML content, you can call this function to show ContentRenderer end-page. This will take the user out of HTML content view.
```
gotoEndPage = function(){
}
```
### exit
If you want to close the HTML game & contentRenderer to take user back to app, you can call this function.
```
exit= function(){
}
```
### Telemetry Interact
Api method to log telemetry interact events. Any interact events in HTML can log using this API method.
```
/**
* Interface to log temetry interact(INTERACT) event
* data - {Object} Telemetry event data
*/
interact: function(data){
_telemetryService.interact(data.type, data.id, data.extype, data.eks);
}
```
### Telemetry Response
Api method to log telemetry response events. When an assessment is playing in content, on selection of option/answer data can be passed by calling this function.
```
/**
* Interface to log telemetry response(RESPONSE) event
* data - {Object} Telemetry event data
*/
response: function(data){
_telemetryService.interact(data.type, data.id, data.extype, data.eks);
}
```
### Telemetry assessmentStart
Api method to get assessment start event data. This event object should be passed as a parameter while calling telemetry assess api method.
```
/**
* Interface to get assess start event
* data - {Object} Telemetry event data
*/
assessmentStart: function(data){
_telemetryService.assess(data.qid, data.subj, data.qlevel, data.data);
}
```
### Telemetry Assess
Api method to log telemetry assess event. After submitting/validating the result of assessment question, call this funciton to log assessment result data.
```
/**
* Interface to log telemetry assess(ASSESS) event
* event - {Object} telemetry event object returned after calling assessmentStart() API method
* data - {Object} Telemetry event data
*/
assess: function(event, data){
_telemetryService.assessEnd(event, data);
}
```
### Telemetry Impression
Api method to log telemtry impression event. When there is a state/page change, call this method to log impression event
```
/**
* Interface to log telemetry impression(IMPRESSION) event
* data - {Object} Telemetry event data
*/
impression: function(data){
_telemetryService.impression(data.stageid, data.stageto, data.data);
}
```
### Telemetry Exdata
Api method to log telemtry exdata events. Any additional information of can be passed by calling this function.
```
/**
* Interface to log telemetry Exdata(EXDATA) event
* data - {Object} Telemetry event data
*/
exdata: function(data){
_telemetryService.xapi(data);
},
```
# authtokengenerator\_jslibrary
## Methods
The following API methods are provided by the AuthToken generator library
### Generate new AuthToken
```
generate: function(key, secret){}
```
Request Arguments:
```
key- "key" of the JWT Credential For ex: '398e54e888da42f8d089je28c298o42b'
secret- "secret" of the JWT Credential For ex: '07c6e2t1rb92987fnrd705jkk8582p9e'
```
### Regenerate Expired AuthToken
```
refresh: function(oldAuthToken) { }
```
### Generate JWT With Bash
Authtoken can be generated using the bash script also, for more details refer
## How to generate authorization credentials
This section details the procedure to generate the AuthToken and secret key that is required to access any APIs and to configure the standalone telemetry JS library.
### Process
### Prerequisites
* Access to the Ekstep Community portal
### Procedure
| Step | Screen |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| Sign In
1. Sign in to Ekstep QA portal ()
2. Go to Resources > Developers
Note: If you have already created QA credentials and tested Sunbird, and are looking at acquiring production credentials, repeat the same steps on visit instead.
|  |
| Request API Access
1. Select API credentials
2. The Manage Credentials page is displayed
3. Click Request API access to request access for available API groups
|  |
| On successful submission of the API access request, the portal admin is notified. The admin either approves or rejects the request
You are notified of the admin’s action through a mail to your registered mail ID
You can also view the action taken, by clicking the notification icon on the portal
|  |
| Generate New Credentials
1. Enter the username
2. Enter notes, if any
3. The API groups that can be accessed with the created credentials are listed here
4. Click Generate credentials to generate key and secret
|  |
| Note the Credentials
1. Ensure to copy the key and secret and confirm the same
2. Click Close after copying the Key and Secret
|  |
# sending\_telemetry
## Prerequisites
The following are the prerequisites for sending telemetry:
### Authtoken
Authtoken is required to access any APIs. See [AuthToken generator JS](/use/authtokengenerator_jslibrary) to understand the process to generate authorization credentials.
### Channel Id
### API key
Sunbird implementors currently need to get a API key for accessing EkStep platform. Currently all the contents are stored here.
When you are initially trying out the Sunbird, please request the keys from the EkStep QA environment. For requesting the keys see [Procedure](/use/authtokengenerator_jslibrary#procedure) section and to follow the steps for getting secret key.
## Telemetry Helpers
The following telemetry helpers gives much insights about capturing and collecting the telemetry data.
### Standalone JS Library
The standalone telemetry JS library allows users to capture telemetry data without the restrictions of using any app that uses the Genie SDK, the EkStep content player or the EkStep or Sunbird portal. Partner users can use the JS library to log and sync telemetry data. They can decide how to use the Telemetry JS library, and integrate it with their app, webpage or web service
When using the standalone telemetry JS library, you can capture and sync telemetry data only when you are connected to the Internet.
There is no storage within the library. To capture offline telemetry data, users need to decide where the data will be stored and how it will sync with the servers when their app gets connected online. [Standalone JS Library](/use/jslibrary) section will help you in understanding better how JS library serves the purpose of capturing telemetry data.
### HTML Interface Library
The ContentRenderer handles telemetry events for ECML content. HTML content has functionality such as click, navigation, assessment, etc. These functionalities are specific to or different for individual HTML content pieces. For HTML Content, the ContentRenderer logs only the telemetry start event. It does not log telemetry for any other event. By embedding the HTML interface library within the HTML content helps log telemetry events for the actions that take place in the HTML content.
[HTML Interface Library](/use/html_interface_library) details information about the library used to log telemetry events for HTML content.
### AuthToken Generator JS
The AuthToken generator JS library is used to generate or refresh the user AuthToken. The Authtoken is mandatory for any API request. The AuthToken is passed as part of configuration to the telemetry JS library. [AuthToken Generator JS Library](/use/authtokengenerator_jslibrary) details method and process of generating key and tokens.
# consuming\_telemetry
## Telemetry Exhaust APIs
The Sunbird telemetry services are made available through a daily exhaust, supported by Ekstep infra from multiple channels. It is common that, these channels will not have the data pipeline to process the telemetry data. Hence, telemetry are made available to channels.
Steps involved in consuming Data Exhaust:
1. \[Automated] A User need to register using [Register User API](https://github.com/ekstep/Common-Design/wiki/Data-Exhaust-API-Specification#data-exhaust-register-user-api){:target="\_blank"}. This API returns a license key, which needs to be used when requesting telemetry data. This creates an entry for the user in `data_exhaust_users` table.
2. \[Manual] Access needs to be granted, manually, to this user to the dataset resource that they want to consume. This access is granted by making an entry, for corresponding user and resource, in `data_exhaust_users_resources` table.
3. \[Automated] User can then use [Datasets API](https://github.com/ekstep/Common-Design/wiki/Data-Exhaust-API-Specification#data-exhaust-dataset-api){:target="\_blank"} to download telemetry data. User has to pass the license key, got in Step 1, for authentication. Internally, Datasets API will invoke [Authentication API](https://github.com/ekstep/Common-Design/wiki/Data-Exhaust-API-Specification#data-exhaust-authenticate-api){:target="\_blank"} and [Authorisation API](https://github.com/ekstep/Common-Design/wiki/Data-Exhaust-API-Specification#data-exhaust-authorize-api){:target="\_blank"} to check if the user has is valid and has access to the requested resource, if the checks pass, dataset is returned.
`Note`: Database schema of Data Exhaust is described [here](https://github.com/ekstep/Common-Design/wiki/TDD-DataSets#database-schema-changes){:target="\_blank"}.
#### Using channel ID and API key to request channel telemetry
## Standard Telemetry Workflows
This section details **Standard Telemetry Workflows** for different access channels.
### Mobile App Workflow
```
START(type: "app")
...| --> app events such as IMPRESSION, FEEDBACK, etc may happen
START(type: "session")
...
| --> IMPRESSION - For the pages that the user visits
| --> INTERACT --> one of the content is clicked
| --> START(type: "player") --> events generated by specific content
...|
...| --> in-content events such as ASSESS, INTERACT, IMPRESSION, LEVEL_SET etc.
...|
| --> END(type: "player")
| --> IMPRESSION - Returned back to mobile app for content player
...| --> app events such as IMPRESSION, INTERACT, etc. may happen
| --> INTERACT --> one of the content is clicked
| --> START(type: "player") --> events generated by specific content
...|
...| --> in-content events such as ASSESS, INTERACT, IMPRESSION, LEVEL_SET etc.
...|
| --> END(type: "player")
| --> IMPRESSION - Returned back to mobile app for content player
...| --> app events such as IMPRESSION, INTERACT, etc. may happen
END(type: "session")
...| --> app events such as APP_UPDATE, FEEDBACK, etc may happen
END(type: "app")
```
### Web Portal Workflow
```
AUDIT (object: user) --> (Optional if a user is created for the first time)
START(type: "session") --> User session starts
...
| --> IMPRESSION - For the pages that the user visits
| --> INTERACT - For the interactions on the page
// there is no explicit logout/timeout
```
### Content Editor Workflow
```
START (type: "session") - User logs in
...
| --> IMPRESSION (Portal) - User visits content creation page (cdata session)
| --> INTERACT (Portal) - User initiates content creation
| --> AUDIT (Platform) - User creates a new content
| --> START (type: "editor", mode: "content")
...
| --> INTERACT (Editor) - In editor, user is loading the asset browser
| --> SEARCH (Platform) - In AT, user is searching for assets (cdata session, search result id)
| --> PLUGIN_LIFECYCLE (Editor) - User selects the asset for content (which search result was used)
| --> PLUGIN_LIFECYCLE (Editor) - User removes the asset from content
| --> INTERACT (Editor) - User clicks save in AT
| --> ACCESS (Platform) - Platform save API is called
| --> INTERACT (Editor) - User clicks on submit to review
| --> AUDIT (object: Content, state: "Review", prevstate: "Draft") - Platform sends the content to review state
| --> END (type: "editor", mode: "content") - User closes the editor and goes back to portal
```
### Backend-services Workflow
```
AUDIT (object: Service, state: "Ready") --> State transition to READY
...| --> ACCESS events for API requests
ACCESS
LOG --> Log events in the context of the incoming request (by request correlation ID)
...
METRICS --> Health/business metrics (e.g. number of jobs executed)
AUDIT (object: Service, state: "Stopped") --> State transition to STOPPED
```
### DIAL Code Consumption Workflow
```
AUDIT (object: Service, state: "Ready") --> State transition to READY
...| --> ACCESS events for API requests
ACCESS
LOG --> Log events in the context of the incoming request (by request correlation ID)
--> SEARCH (Platform) - In AT, user is searching for assets (cdata session, search result id)
...
SCAN --> Health/business metrics (e.g. number of jobs executed)
| --> INTERACT --> one of the content is clicked
| --> START(type: "player") --> events generated by specific content
...|
...| --> in-content events such as ASSESS, INTERACT, IMPRESSION, LEVEL_SET etc.
...|
AUDIT (object: Service, state: "Stopped") --> State transition to STOPPED
```