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

Properties
activity_id

string

The ID of the Activity that will be used in Learnosity's Reports API and Data API to group all unique user sessions together. Should not exceed 36 characters. Recommended to be a UUID.

Use a value that represents different end users attempting the same "test" blueprint, as you can then request reports for all sessions that share the same activity_id.

Note Can be ommited for non-Adaptive activities with type: "local_practice".
activity_template_id

string

The reference of an existing Activity stored in Learnosity's Item bank. This Activity acts as a template which has a default set of properties for the Activity, without needing to define the same properties each time the same Activity is created. Some of these properties can then be overridden if required, by providing them in this request object.

E.g. a "base" Activity may use a custom regions configuration that should be applied to all Assessments, and further overrides can be made such as changing the selected Items, changing the title of the assessment, etc.

Activity references (called activity_template_id when you initialize an assessment) are limited to 150 characters.

See Activity definition for more information.

adaptive

object

Configuration for an adaptive assessment. Learnosity offers several forms including; Item Adaptive Testing, Item Branching and Testlet Adaptive.

Important Only supported with rendering_type: "assess" and supersedes items

To configure this option, see the complete list of all Initialization Options for Adaptive Assessments.
config

object

The properties inside this object are used to configure options relating to the user 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.

See What is Dynamic Content? for more information. 

"dynamic_items": {
    "data_table_seed": "SOME_SEED",
    "try_again": {
        "max_attempts": 5,
        "random": true
    }
}
events

boolean

Enables the use of Events API.

Important Your Learnosity consumer must have Events API enabled for this option to take effect. See Events API for more information.

Default: false

item_pool_id

string

Sets the default Item Pool to retrieve content (Activity template and Items) from.

See Data API Pools for more information.

items

array[string |ItemObject]

Sets the content to be shown in the session. Can be an array of unique string Item references, or an array of Item objects for advanced usage.

Important This is a mandatory property unless adaptive or sections are configured, or using an activity_template_id with items in it.

Note The items property has priority over activity_template_id, if they are passed simultaneously.

Note The items and sections can not be used at the same time in a request object.
name

string

Name of the activity that will be displayed in Learnosity's Reports API and Data API.

Important Required only if submitting responses to Learnosity.
organisation_id

string

Sets the default Item Bank to retrieve content (Activity template and Items) from.

See Multiple Activity template and Item sources for more information.

rendering_type

string

The rendering type dictates whether the activity will be rendered using the Learnosity's assessment player, or Items embedded in multiple different locations.
Possible values:
  • "assess"
  • "inline"
retrieve_tags

boolean

Brings the Item tags along with the assessment content. Used for content debugging in test environments or other advanced use-cases.

Default: false

scoring_type

string

Override the scoring type of the items loaded from the Item Bank (unless otherwise overridden per item, which takes precedence).

See Item Scoring tutorial for more information.

sections

array[object]

Sections allow split a single activity into discrete buckets of items, with the ability to have different title and subtitle per section.

Important Once students progress to a new section, they cannot navigate back (unless allow_backward_navigation is enabled).

Note The sections and items can not be used at the same time in a request object.
session_id

string

This ID is used to uniquely identify the users assessment session.

Important Must be a valid UUID Version 4. e.g: f47ac10b-58cc-4372-a567-0e02b2c3d479
session_metadata

object

Custom metadata to include for the user's assessment session. This metadata is stored when the session is saved or submitted.
state

string

Sets the state of the activity. State controls the startup modes of the API, to allow for different behaviors during an assessment. For example, the initial state is applied when students first access the assessment, and a new session is created. Similarly, resume state is used when a student is coming back to an assessment, but they have accessed it before, so we resume the same session that they started earlier. You can also specify the preview state, which allows learners to view Learnosity Items without being able to answer questions or submit the assessment. For more detail, see the Help article on this topic.

In the submit_practice session type, Items API always checks if the session exists to decide if the state should be initial or resume and adjusts it accordingly. This means you only really need to set the state when you want to initialize with either the review or preview states.

Possible values:
  • "initial"
  • "resume"
  • "review"
  • "preview"

Default: "initial"

See Switching Between Testing and Reviewing With States for more information.

subscores

array[]

Subscores are a breakdown of a total score achieved for an activity. They allow you to extract groups of Items, and focus on scoring them separately.

See Activity Subscores for more information.

type

string

Defines the session context, including whether student responses are to be submitted and stored or remain available locally only.
Possible values:
  • "local_practice" - assessment is rendered, but the responses will not be stored in Learnosity's servers
  • "submit_practice" - assessment is rendered and responses are stored in Learnosity's servers, allowing for grading and review of the session
  • "feedback" - the assessment is aimed at capturing teacher's feedback. More information

Default: "submit_practice"

user_id

string

The ID of the user that is attempting the assessment. Should not exceed 50 characters, nor contain any personally identifiable information. Recommended to be a UUID.

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

Properties
customUnload

callback

This function is called when the user attempts to close the browser window. You would use this to display a custom error notification or dialog in order to warn the user that they may lose their progress if they don't save.

errorListener

function

Function to be called on a Learnosity error event. Receives an Error object.

See troubleshooting for more information.

readyListener

function

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