Initialization

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.

• Initialization object
• Callbacks object

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
• Request object

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:

• .NET
• Java
• Node.JS
• PHP
• Python
• Ruby

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

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

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;
}

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

{
    "id": "report-01",
    "type": "session-detail-by-item",
    "session_id": "123e4567-e89b-12d3-a456-426655440000",
    "user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b"
}