Reports API 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.

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:

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.

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

    An array of configuration objects for each report being initialized.

  • configuration object

    An object containing custom configuration options for the Reports API.

  • label_bundle object

    An object containing custom labels to be used in the reports.

  • user_id string

    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.

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

  • errorListener function

    Function to be called on a Learnosity error event.

  • readyListener function

    Function to be called when the API has been successfully initialised.

  • dataListener function

    Function to be called when all report data has been loaded.

  • displayNameListener function

    Callback function used in some reports (notably, Large Group Report) to map raw names and identifiers in the report data to friendly display names at runtime.

  • scoreMutator function

    Callback function used in the item-scores-by-tag-by-user report to mutate scores shown in each cell of the report.