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.
Example
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:
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 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
Note
Can be ommited for non-Adaptive activities with |
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 Activity references (called 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
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.
|
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: |
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
Important
This is a mandatory property unless adaptive or sections are configured, or using an
Note
The
Note
The |
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:
|
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: |
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
Important
Once students progress to a new section, they cannot navigate back (unless
Note
The |
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
In the
Possible values:
Default: 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:
Default: |
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.
|
Callbacks
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. |