Items API Initialization

This article details the properties that are passed as parameters to the window.LearnosityItems.init() method to initialize Items API.

This method is the starting point to initializing and rendering Items API, and as you can see in the example below, takes two key parameters:

The Initialization object is mandatory. Further details on getting started and initializing Items API can also be found in the Getting Started guide.

var initializationObject = {
    "security": {
        "consumer_key": "INSERT_CONSUMER_KEY_HERE",
        "domain": "my.domain.com",
        "timestamp": "20120202-1234",
        "signature": "SHA256-HASH - See Security"
    },
    "request": {
        "activity_id": "math.c2.u7",
        "name": "Math Chapter 2 – Unit 7",
        "rendering_type": "assess",
        "type": "submit_practice",
        "session_id": "0adc8ac1-d71f-494e-860b-378c2d75a926",
        "user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b",
        "items": [
            "Demo3",
            "Demo4",
            "accessibility_demo_6",
            "Demo6",
            "Demo7",
            "Demo8",
            "Demo9",
            "Demo10",
            "audioplayer-demo-1"
        ],
        "config": {
            "title": "Math Chapter 2 – Unit 7",
            "subtitle": "Multiplication",
            "regions": "main",
            "navigation": {
                "show_intro": true,
                "show_outro": true,
                "skip_submit_confirmation": false,
                "warning_on_change": false,
                "auto_save": {
                    "save_interval_duration": 500
                }
            },
            "annotations": true,
            "time": {
                "max_time": 1500,
                "limit_type": "soft",
                "warning_time": 120
            },
            "configuration": {
                "shuffle_items": false,
                "idle_timeout": {
                    "interval": 300,
                    "countdown_time": 60
                }
            }
        }
    }
};

var 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 Items API is ready");
    }
};

var itemsApp = window.LearnosityItems.init(initializationObject, callbacks);

Initialization Object

The Initialization object is a JSON object which is passed as the first parameter into the window.LearnosityItems.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 user & session identification, user interface look and feel, as well as which Items or Activities to load.

Only a few properties are mandatory, the rest provide a high level of customization to enable you to tailor the assessment experience to suit your needs.

Properties

= mandatory property

  • activity_id string

    Specifies a unique identifier for a group of sessions.

  • activity_template_id string

    The reference of an existing Activity stored in Learnosity's Item bank.

  • adaptive object

    Configuration for an adaptive assessment.

  • config object

    Configure options relating to the assessment player experience and behavior of Items API.

  • dynamic_items object

    The properties inside this object are used to configure options relating to Dynamic Content, a form of smart content which allows many variations of the same Question.

  • item_pool_id string

    Sets the default Item pool to retrieve content from, such as Activities and Items.

  • items array[strings] array[ItemObject]

    Defines the Items to be used in the current assessment.

  • name string

    Specifies a human-friendly name of the Activity that will be displayed in Reports API and Data API.

  • organisation_id number

    Sets the default Item bank to retrieve content from, such as Activities and Items that can be used in the assessment.

  • random object

    Configure options relating to a random Activity.

  • rendering_type string

    The rendering type dictates whether the Activity will be rendered using the Learnosity's assessment player, or within an Items container embedded in multiple different locations on the page.

  • retrieve_tags boolean

    Retrieves Tags for all Items when the assessment is loaded.

  • scoring_type string

    Override the scoring type of the Items loaded from the Item Bank.

  • sections array[SectionObjects]

    Sections allows you to split an Activity into separate groups of Items.

  • session_id string

    Uniquely identify the learner's assessment session.

  • session_metadata object

    Custom metadata to include for the learner's assessment session.

  • state string

    Sets the state of the Activity when the assessment is initialized.

  • subscores array[subscoreDefinition]

    Define which Items or Item Tags should be used to create subscore groups for further calculations and analysis.

  • type string

    Specifies the context for where the learner's responses are submitted and stored.

  • user_id string

    The ID of the learner that is attempting the assessment.

The Callbacks object contains optional callback functions that allow detection of the ready status of an Items 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 Items API. Most of the methods provided by the returned object from window.LearnosityItems.init() will not be fully available until after the readyListener callback has triggered.

Properties

  • customUnload function

    This function is called when the learner attempts to close the browser window.

  • errorListener function

    This function is called when one of the preset Learnosity API errors are thrown.

  • readyListener function

    This function is called when the API has been successfully initialized.