Initialization
This article details the properties that are passed as parameters to the window.LearnosityReports.init() method to initialize Reports API.
This method is the starting point to initializing and rendering Reports API, and as you can see in the example below, takes two key parameters.
Only the Initialization object is mandatory. Further detail on getting started and initializing Reports API can also be found in the Quick Start guide.
Example
const initializationObject = {
"security": {
"consumer_key": "INSERT_CONSUMER_KEY_HERE",
"domain": "my.domain.com",
"timestamp": "20120202-1234",
"signature": "SHA256-HASH - See Security",
"user_id": "Optional - Needed for Live Activity reports"
},
"request": {
"user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b",
"reports": [
{
...
},
{
....
}
],
"label_bundle": {
"activity": "Activity",
},
"configuration": {
"questionsApiVersion": "v2", // use a specific version of Questions API
"itemsApiVersion": "v1" // use a specific version of Items API
}
}
}
const callbacks = {
errorListener: function (e) {
// Adds a listener to all error codes.
console.log("Error Code ", e.code);
console.log("Error Message ", e.msg);
console.log("Error Detail ", e.detail);
},
readyListener: function () {
console.log("Learnosity Reports API is ready");
}
};
const reportsApp = window.LearnosityReports.init(initializationObject, callbacks);
Initialization Object
The Initialization object is a JSON object which is passed as the first parameter into the window.LearnosityReports.init() method. It includes all the information needed to initialize the API.
It contains the following two top-level properties:
Security Object
The Security object is a property generated by the Learnosity serverside SDKs to ensure that any of the APIs are only initialized from a secured, allowed source, using your consumer key and secret.
This is handled by our SDKs in:
For other languages, please see our Security & Authentication page on how to sign your requests.
Request Object
The Request object contains all of the configuration properties for which reports to load, where to load them, and any optional configuration properties
Only a few properties are mandatory, the rest provide a high level of customization to enable you to tailor the reporting experience to suit your needs.
Properties
= mandatory property
reports
Array[Report]An object containing custom configuration options for the Reports API.
Properties: | |
---|---|
questionsApiVersion |
Type:
string Deprecated Reports API automatically sets the required Questions API version. No longer has any effect. Originally, this option specified a version of Questions API to use for reports that rendered Questions, before LTS versions were introduced.
Example: "v2"
|
itemsApiVersion |
Type:
string Deprecated Reports API automatically sets the required Items API version. No longer has any effect. Originally, this option specified a version of Items API to use for reports that rendered Items, before LTS versions were introduced.
Example: "v1"
|
Properties: | |
---|---|
a_problem_occured |
Type:
string
Default: |
activity |
Type:
string
Default: |
attempted |
Type:
string
Default: |
not_attempted |
Type:
string
Default: |
not_marked |
Type:
string
Default: |
partial |
Type:
string
Default: |
correct |
Type:
string
Default: |
incorrect |
Type:
string
Default: |
incomplete |
Type:
string
Default: |
seen |
Type:
string
Default: |
date |
Type:
string
Default: |
items |
Type:
string
Default: |
total_n_of_items |
Type:
string
Default: |
last_item_n |
Type:
string
Default: |
n_of_items_correct |
Type:
string
Default: |
n_of_items_incorrect |
Type:
string
Default: |
n_of_items_skipped |
Type:
string
Default: |
n_of_items_not_marked |
Type:
string
Default: |
of_items_have_been_seen |
Type:
string
Default: |
of_items_were_answered_correctly |
Type:
string
Default: |
of_items_were_attempted |
Type:
string
Default: |
of_score_was_answered_correctly |
Type:
string
Default: |
of_questions_have_been_seen |
Type:
string
Default: |
total_n_of_questions |
Type:
string
Default: |
n_of_questions_correct |
Type:
string
Default: |
n_of_questions_incorrect |
Type:
string
Default: |
n_of_questions_skipped |
Type:
string
Default: |
n_of_questions_not_marked |
Type:
string
Default: |
of_questions_were_answered_correctly |
Type:
string
Default: |
of_questions_were_attempted |
Type:
string
Default: |
time_spent |
Type:
string
Default: |
total_time_spent |
Type:
string
Default: |
total |
Type:
string
Default: |
progress |
Type:
string
Default: |
question |
Type:
string
Default: |
item |
Type:
string
Default: |
score |
Type:
string
Default: |
items_correct |
Type:
string
Default: |
user |
Type:
string
Default: |
users |
Type:
string
Default: |
paused |
Type:
string
Default: |
completed |
Type:
string
Default: |
in_progress |
Type:
string
Default: |
not_started |
Type:
string
Default: |
saved |
Type:
string
Default: |
suspended |
Type:
string
Default: |
discarded |
Type:
string
Default: |
msg_no_data |
Type:
string
Default: |
status |
Type:
string
Default: |
active |
Type:
string
Default: |
focuse |
Type:
string
Default: |
unfocused |
Type:
string
Default: |
pause |
Type:
string
Default: |
pause_confirmation |
Type:
string
Default: |
unpause |
Type:
string
Default: |
unpause_confirmation |
Type:
string
Default: |
extend_time |
Type:
string
Default: |
extend_time_confirmation |
Type:
string
Default: |
save_quit |
Type:
string
Default: |
save_quit_confirmation |
Type:
string
Default: |
exit_discard |
Type:
string
Default: |
exit_discard_confirmation |
Type:
string
Default: |
confirm |
Type:
string
Default: |
continue |
Type:
string
Default: |
confirmation_heading_action |
Type:
string
Default: |
cancel |
Type:
string
Default: |
group_name |
Type:
string
Default: |
group_count |
Type:
string
Default: |
lowest_score |
Type:
string
Default: |
highest_score |
Type:
string
Default: |
mean_seen_activities |
Type:
string
Default: |
mean_attempted_percent |
Type:
string
Default: |
mean_score |
Type:
string
Default: |
median_score |
Type:
string
Default: |
stddev_score |
Type:
string
Default: |
lowest_percent |
Type:
string
Default: |
highest_percent |
Type:
string
Default: |
mean_percent |
Type:
string
Default: |
median_percent |
Type:
string
Default: |
stddev_percent |
Type:
string
Default: |
population |
Type:
string
Default: |
hour |
Type:
string
Default: |
minute |
Type:
string
Default: |
second |
Type:
string
Default: |
hr |
Type:
string
Default: |
min |
Type:
string
Default: |
sec |
Type:
string
Default: |
A default user ID to apply to each report in the reports
array that does not specify
a user ID, when the type of report expects a user ID to be specified.
Callbacks
The Callbacks object contains optional callback functions that allow detection of the 'ready' status of an Reports API instance and any errors encountered.
An example of how to construct this object can be seen above.
The readyListener callback in particular is very important for the correct functioning of Reports API. most of the methods provided by the returned object from window.LearnosityReports.init()
will not be fully available until after the readyListener callback has triggered.
Properties
See troubleshooting for more information.
Parameters | |
---|---|
error |
Type:
Error |
Parameters | |
---|---|
data |
Type:
array[reportDataObject] |
Callback function used in some reports (notably, aggregate reports) to map raw names and identifiers in the report data to friendly display names at runtime.
This function is called whenever there are 1 or more raw values used in the report that can be replaced, with the list of raw values (in no particular order) given as the only argument. The return value should be an array of replacement names corresponding to each raw value.
Parameters | |
---|---|
originalNames |
Type:
array[String] A list of raw names/values in the report that can be remapped for display using this callback; e.g. |
displayNameListener: function (originalNames) {
// A sample mapping of possible raw data values from the report and their corresponding display names.
// This example is for an aggregate report, where the group names from the dataset may match the keys below:
var displayNameMap = {
"us": "United States",
"cn": "China",
"gb": "Great Britain",
"au": "Australia",
"us-ma": "Massachusetts",
"cn-11": "Beijing Municipality",
"gb-eng": "England",
"au-nsw": "New South Wales",
"school_1": "Massachusetts Institute of Technology",
"school_2": "Peking University",
"school_3": "University of Oxford",
"school_4": "University of New South Wales"
// Include as many display name associations as desired
// ...
};
var displayNames = [];
for (var i = 0; i < originalNames.length; i++) {
var originalName = originalNames[i];
if (originalName in displayNameMap) {
// The mapped value is what will be displayed instead of the corresponding original name
displayNames.push(displayNameMap[originalName]);
} else {
displayNames.push(originalName);
}
}
return displayNames;
}
Callback function used in the item-scores-by-tag-by-user
report to mutate scores shown in each cell of the report.
This function is called before scores are rendered in the report. The scores
argument passed to the function is an array of score mutator objects. The score can be mutated using these methods. The return value of scoreMutator
is ignored.
Parameters | |
---|---|
scores |
Type:
array[scoreMutatorObject] An array of objects, each corresponding to a single cell in the report. Each object exposes methods for mutating the score shown in the report. See scoreMutatorObject definition for details of each method. |
scoreMutator: function (scores) {
for (var i = 0; i < scores.length; i++) {
// apply a custom business rule to treat unattempted questions as incorrect
var unattempted = scores[i].unattempted();
var incorrect = scores[i].incorrect();
scores[i].unattempted(0);
scores[i].incorrect(incorrect + unattempted);
}
}
Object Definitions
In the Initialization object and Callback sections above, there are some object definitions which are complex enough to document separately. These are listed below, and linked from the relevant documentation above.
Objects
A configuration object used for the initialization of an individual report. An object of this type must conform to the object definition of one of the available Learnosity report types.
See Report Types reference for more information.
Properties: | |
---|---|
id |
Type:
string A host-page supplied unique identifier for this report. Used to render the report into a DOM hook on the host page. |
type |
Type:
string The type of report. Must be a valid report type.
|
{
"id": "report-01",
"type": "session-detail-by-item",
"session_id": "123e4567-e89b-12d3-a456-426655440000",
"user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b"
}
See troubleshooting for more information.
Properties: | |
---|---|
code |
Type:
number |
msg |
Type:
string |
detail |
Type:
string |
Properties: | |
---|---|
id |
Type:
string A host-page supplied unique identifier for this report. Used to render the report into a DOM hook on the host page. |
data |
Type:
object an object containing the raw data packet used to generate the report. |
An object containing methods to mutate a score, as well as assign HTML data attributes to certain elements to make them accessible for design and behavioural changes. The individual correct, incorrect, unattempted and unmarked components of the score are exposed as getters, and each component can be overridden using the corresponding setter methods. The components of the score will be used to render score percentages, score bars and tooltips.
Additional countSeen()
and percentScore()
methods are also available.
Properties: | |
---|---|
countSeen() |
Type:
function() Returns the number of items from which this score is calculated, ie. the number of Items presented to the user that meet the filters for this particular report (or cell within the report). |
correct() |
Type:
function() Returns the correct component of the score. |
domData(object) |
Type:
function() Used to store custom data attributes against this score's cell, for the purpose of custom logic or CSS selectors. Pass a map of key value pairs which will be stored on the DOM as custom data attributes. Each key will be added to the score's cell as a data attribute of the form data-custom_keyname="value" . The data attribute can then be used as a CSS selector for applying custom styles, or a DOM selector to hook your own custom logic to. See an example domData() customization at our Learnosity Demos Learning Outcomes - Class Demo |
correct(Number) |
Type:
function() Sets the correct component of the score. |
incorrect() |
Type:
function() Returns the incorrect component of the score. |
incorrect(Number) |
Type:
function() Sets the incorrect component of the score. |
unmarked() |
Type:
function() Returns the unmarked component of the score. |
unmarked(Number) |
Type:
function() Sets the unmarked component of the score. |
unattempted() |
Type:
function() Returns the unattempted component of the score. |
unattempted(Number) |
Type:
function() Sets the unattempted component of the score. |
percentScore(Number) |
Type:
function() Sets the overall percent score. Normally, Learnosity uses correct / maxScore to calculate the percentScore,
but this setter can be used to override the displayed percentage regardless of the values of the individual score components.
|