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.

Only the Initialization object is mandatory. Further detail 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

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".

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.

See Activity definition for more information.

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

See Initialization Options for Adaptive Assessments for more information.

object

The properties inside this object are used to configure options relating to the user experience and behavior of Items API.

Properties:
administration
Type: object

Enables a password protected panel of options administrators can use to change accessibility settings like color schemes and fontsize. The activity can also be exited from here.

Important Supported with rendering_type: "assess" only.
annotations
Type: boolean

When set to true, the Annotations API is enabled with all modules using default initialization options.

Important When using with rendering_type: "inline", the developer must provide a DOM hook to indicate which area of the page can be used to insert annotations. If no DOM hook is provided, body element will be used and is not recommended. The provided DOM should also have position: relative | absolute; style.

const itemsApp = LearnosityItems.init(initOptions, '#assessment-wrapper', eventsOptions);
annotations_api_init_options
Type: object

Provide custom initialization options to the Annotations API. This can be used to enable or disable specific modules, or customize their behavior. When present, this will override the default initialization options specified by annotations: true.

Important When using with rendering_type: "inline", the developer must provide a DOM hook to indicate which area of the page can be used to insert annotations. If no DOM hook is provided, body element will be used and is not recommended. The provided DOM should also have position: relative | absolute; style.
configuration
Type: object

Enables various customizations such as redirect URLs and reading time settings.

Important Supported with rendering_type: "assess" only.

"configuration": {
    "lazyload": false,
    "focus_on_player": false,
    "onsubmit_redirect_url": "https://www.learnosity.com",
    "onsave_redirect_url": false,
    "ondiscard_redirect_url": "https://reference.learnosity.com",
    "reading_mode": {
        "reading_time": 300,
        "warning_time": 60,
        "goto_first_item_on_reading_time_completion": true
    },
    "contrast": "black-on-white",
    "contrast": {
        "active": "Example 1",
        "custom_palettes": [
            {
                "name": "Example 1",
                "colors": {
                    "content-background": "#ffffff",
                    "content-color": "#000000",
                    "content-color-hover": "#cccccc"
                }
            },
            {
                "name": "Example 2",
                "colors": {
                    "content-background": "#ffffff",
                    "content-color": "#000000",
                    "content-color-hover": "#cccccc"
                }
            }
        ]
    },
    "fontsize": "normal",
    "idle_timeout": false,
    "events": false,
    "shuffle_items": false,
    "disable_item_workflow": false,
    "submit_criteria": {
        "type": "attempted",
        "threshold": 0.1
    },
    "submit_failed_options": {
        "mailto": false,
        "download": false
    },
    "auto_retry_failed_images": false
}
ignore_question_attributes
Type: Array[string]

Strips attributes from questions on the server before returning them to the browser for rendering.

Note Scoring in the browser is unavailable if "validation" is stripped, as is Check Answer functionality.
labelBundle

Object of labels and values can be passed to override default English labeling

Note The previousButtonLabel setting only interact with the button hover state.

Important Supported with rendering_type: "assess" only.
navigation
Type: object

Customize navigational attributes are available to the user interacting with the player.

Important Supported with rendering_type: "assess" only.

"navigation": {
    "auto_save": {
        "changed_responses_only": false,
        "save_interval_duration": 500,
        "ui": true,
    },
    "warning_on_change": {
        "disable_item_navigation": true
    },
    "warning_on_section_change": false,
    "skip_submit_confirmation": false,
    "show_intro": true,
    "resource_items": ["resource"],
    "intro_item": "Intro Item Reference 123",
    "show_outro": true,
    "outro_item": "Outro Item Reference 456",
    "show_acknowledgements": true,
    "scroll_to_top": true,
    "scroll_to_test": true,
    "exit_securebrowser": true
}
questions_api_init_options
Type: object
Used to define certain behavior which falls under the functionality provided under the hood by the Questions API, specifically concerning question rendering, and scoring behavior.
regions
Type: object

Regions allows you to create a personalized, fluid and extensible assessment UI. The assessment player layout is split into multiple regions which you can customize components of your choice.

Available regions:

  • "top-left"
  • "top-right"
  • "right"
  • "items"
  • "bottom-right"

Important Supported with rendering_type: "assess" only.

See Assess regions knowledge base article for more information. 

"regions": {
    "top-left": [
        {
            "type": "title_element"
        }
    ],
    "top-right": [
        {
            "type": "pause_button",
            "position": "right"
        },
        {
            "type": "timer_element"                },
        {
            "type": "itemcount_element"
        }
    ],
    "right": [
        {
            "type": "save_button"
        },
        {
            "type": "fullscreen_button"
        },
        {
            "type": "separator_element"
        },
        {
            "type": "accessibility_button"
        },
        {
            "type": "calculator_button"
        },
        {
            "type": "verticaltoc_element"
        },
        {
            "type": "masking_button"
        },
        {
            "type": "next_button"
        },
        {
            "type": "previous_button"
        }
    ],
    "items": [
        {
            "type": "slider_element",
            "scrollable_option": false,
            "warning_on_change_option": false //will be deprecated soon
        },
        {
            "type": "progress_element"
        }
    ],
    "bottom-right": [
        {
            "type": "next_button"
        },
        {
            "type": "previous_button"
        }
    ]
}
subtitle
Type: string

Sets the subtitle of the activity.

Important Supported with rendering_type: "assess" only.

Default: ""

time
Type: object

Used to define time parameters including countdown and expiry settings.

This configuration can also be set inside each sections to define the time parameters of each sections.

Note When using sections and a time configuration has been set in any section, the global time configuration will be ignored.

Important Supported with rendering_type: "assess" only.

"time": {
    "max_time": 600,
    "limit_type": "hard",
    "warning_time": 60,
    "countdown_option": true
}
title
Type: string

Sets the title of the activity.

Important Supported with rendering_type: "assess" only.

Default: ""

object

Enables a password protected panel of options administrators can use to change accessibility settings like color schemes and fontsize. The activity can also be exited from here.

Important Supported with rendering_type: "assess" only.

Properties:
options
Type: object
Available options for the administration panel.
pwd
Type: string

Makes the administration panel password-protected. The user must provide the correct password to gain access.

Important The supplied value must be a SHA256 hash of the intended password.
object
Available options for the administration panel.
Properties:
show_exit
Type: boolean
Enables the Discard & exit button.

Default: true

show_extend
Type: boolean
Enables the option to add extra time allowed to complete the session.

Default: true

show_save
Type: boolean
Enables the Save & exit button.

Default: true

show_submit
Type: boolean
Enables the Submit & exit button.

Default: true

object

Provide custom initialization options to the Annotations API. This can be used to enable or disable specific modules, or customize their behavior. When present, this will override the default initialization options specified by annotations: true.

Important When using with rendering_type: "inline", the developer must provide a DOM hook to indicate which area of the page can be used to insert annotations. If no DOM hook is provided, body element will be used and is not recommended. The provided DOM should also have position: relative | absolute; style.

Properties:
modules
Type: object

Define which modules are enabled and provide module initialization options.

Note Each module can be configured individually. See the Annotations API initialization options documentation for more information.
object

Enables various customizations such as redirect URLs and reading time settings.

Important Supported with rendering_type: "assess" only.

Properties:
auto_retry_failed_images
Type: boolean

If enabled, Learnosity's assessment player will attempt to try to reload any failed images for the given session using a Full Jitter exponential backoff algorithm.

Default: false

contrast

Define the active color scheme.

Note See the accessibility panel knowledge base article for more information on how to create and register a palette.
disable_item_workflow
Type: boolean

Disable the Items workflow from being executed. This feature is useful for editing Items without needing to wait for the full Action builder workflow to complete.

Note Visit the Items workflow knowledge base article for more information on this feature.

Default: false

events
Type: boolean
Whether to enable Events API for publishing/subscribing realtime events for the session.

Note Events API must be enabled on your consumer for this to work.

Default: false

focus_on_player
Type: boolean

Set the focus to the Start button when there is an intro page, or to the first item when there is no intro page.

To prevent the Assessment Player to control the focus of the page, set this option to false.

Default: true

fontsize
Type: string
The font size used to render text content inside Assessment Player. See our knowledge base article on this topic.
Possible values:
  • "small"
  • "normal"
  • "large"
  • "xlarge"
  • "xxlarge"

Default: "normal"

idle_timeout

When enabled, a dialog box will be shown after a number of seconds of inactivity. Once shown, the user has limited time to close the dialog to continue with the session.

Failing to close the dialog in time, the current progress will be saved and the session will be exited.

Note The default inactivity interval is 300 seconds and the default dialog count down time is 60 seconds.

Default: false

lazyload
Type: boolean
Enables lazy loading of items from the Item Bank to improve loading time during API initialization.

Default: false

onsave_redirect_url

Default: "/" (redirects to the home page)

Example: "https://reference.learnosity.com"
onsubmit_redirect_url

Default: "/" (redirects to the home page)

Example: "https://reference.learnosity.com"
questionsApiVersion
Type: string

Deprecated - Items API automatically sets the correct Questions or Assess API versions.

Load the activity using the specified version of Questions API. The Questions API is used under the hood by the Items API for the purposes of rendering questions and capturing student responses.

If not set, this uses the specific paired minor version as defined in Items API release logs.

Default: paired minor release of Questions API

See Questions API release logs for more information.

question_indexing
Type: boolean

Adds indentation and sequential numbering to all questions in the activity. Numbers reset to 1 when a new section is started.

Default: false

reading_mode
Type: object

Allocate a reading time period where the users can browse and read questions. During this time period, attempts at answering questions, pausing or submitting the test will be disabled.

Important The idle_timeout feature is disabled during reading time and this feature is not available in the "review" state.
section_options
Type: object

Enables various customizations for sections Assessment.
shuffle_items

Enables shuffling of items based on a given seed.

Important The string value will provide same ordering of items for all sessions, as oppose to true which gives a different order per session.

Important If shuffle_items is set within a section it overrides the root level default behaviour.

Note See the article on randomizing Item content for more.

Default: false

submit_criteria
Type: object

Define the criteria the user needs to meet in order to successfully submit their session.

Note By default, the assessment player imposes no criteria to submit the assessment.
submit_failed_options
Type: object

Set the options for the user to manually retrieve and send their session responses in the event of a network failure or server issues preventing submissions.

Note See the failed submit options knowledge base article for an in-depth coverage.

Note The "View encoded string" is displayed by default and there is no available option to hide it when instantiating the Items API. 

"configuration": {
    "lazyload": false,
    "focus_on_player": false,
    "onsubmit_redirect_url": "https://www.learnosity.com",
    "onsave_redirect_url": false,
    "ondiscard_redirect_url": "https://reference.learnosity.com",
    "reading_mode": {
        "reading_time": 300,
        "warning_time": 60,
        "goto_first_item_on_reading_time_completion": true
    },
    "contrast": "black-on-white",
    "contrast": {
        "active": "Example 1",
        "custom_palettes": [
            {
                "name": "Example 1",
                "colors": {
                    "content-background": "#ffffff",
                    "content-color": "#000000",
                    "content-color-hover": "#cccccc"
                }
            },
            {
                "name": "Example 2",
                "colors": {
                    "content-background": "#ffffff",
                    "content-color": "#000000",
                    "content-color-hover": "#cccccc"
                }
            }
        ]
    },
    "fontsize": "normal",
    "idle_timeout": false,
    "events": false,
    "shuffle_items": false,
    "disable_item_workflow": false,
    "submit_criteria": {
        "type": "attempted",
        "threshold": 0.1
    },
    "submit_failed_options": {
        "mailto": false,
        "download": false
    },
    "auto_retry_failed_images": false
}
object | string

Define the active color scheme.

Note See the accessibility panel knowledge base article for more information on how to create and register a palette.

Types
object
Properties:
active
Type: string

Contains the name of a palette to use as the active palette. This name will be used to find the palette settings inside the custom_palettes.
custom_palettes
Type: Array[string |AccessibilityPalette]
Define all the available custom palettes.
string

A valid URL to a custom CSS file containing the accessibility palettes. This accessibility scheme will be loaded by default.
boolean | object

When enabled, a dialog box will be shown after a number of seconds of inactivity. Once shown, the user has limited time to close the dialog to continue with the session.

Failing to close the dialog in time, the current progress will be saved and the session will be exited.

Note The default inactivity interval is 300 seconds and the default dialog count down time is 60 seconds.

Types
boolean

Set to true to enable the idle timeout feature with the default timing values.
object
Properties:
countdown_time
Type: number
The dialog count down time in seconds before the session will be saved and discarded.
interval
Type: number
The inactivity time period in seconds.

Default: false

boolean | string
Types
boolean
Set to false to prevent any redirect.
string

Automatically redirect to the supplied URL when the user choose to exit after finished saving an activity.

Note It is assumed that the supplied URL is valid. There will be no validation on this field.

Default: "/" (redirects to the home page)

Example: "https://reference.learnosity.com"
boolean | string
Types
boolean
Set to false to prevent any redirect.
string

Automatically redirect to the supplied URL when the user closes the activity after submitting.

Note It is assumed that the supplied URL is valid. There will be no validation on this field.

Default: "/" (redirects to the home page)

Example: "https://reference.learnosity.com"
object

Allocate a reading time period where the users can browse and read questions. During this time period, attempts at answering questions, pausing or submitting the test will be disabled.

Important The idle_timeout feature is disabled during reading time and this feature is not available in the "review" state.

Properties:
goto_first_item_on_reading_time_completion
Type: boolean
Automatically navigate to the first question in the activity once the reading time is over.

Default: false

reading_time
Type: number
Allocate a number of seconds as the reading time period.

Default: 0

warning_time
Type: number
Display a visual warning when n number of seconds left for the reading time.

Default: 0

object

Enables various customizations for sections Assessment.

Version added: v2021.2.LTS

Properties:
allow_backward_navigation
Type: boolean
When using sections and this is set true the user will be able to navigate backward to previous sections.

Default: false

display_total_item_count
Type: boolean
When using sections and this is set true the Item counter will display the total combined item count for all sections.

Default: false

reset_itemcount_per_section
Type: boolean

When using sections and this is set true, the Item count and progress in assessments will be reset, so that it only reflects the number of Items within the current section, rather than all sections.

Note that this attribute will be ignored if allow_backward_navigation or display_total_item_count is set to true

Default: false

boolean | string

Enables shuffling of items based on a given seed.

Important The string value will provide same ordering of items for all sessions, as oppose to true which gives a different order per session.

Important If shuffle_items is set within a section it overrides the root level default behaviour.

Note See the article on randomizing Item content for more.

Types
boolean
Randomize items using the session_id as the seed.
string
Randomize items using the supplied value as the seed.

Default: false

object

Define the criteria the user needs to meet in order to successfully submit their session.

Note By default, the assessment player imposes no criteria to submit the assessment.

Properties:
threshold
Type: number
The percentage of questions meeting the type criteria. Must be a integer, between 0 and 100 inclusive.

Default: 0

Example: 50
type
Type: string
The type of action the user performed on each question.
Possible values:
  • "attempted"
  • "valid"

Default: "attempted"

object

Set the options for the user to manually retrieve and send their session responses in the event of a network failure or server issues preventing submissions.

Note See the failed submit options knowledge base article for an in-depth coverage.

Note The "View encoded string" is displayed by default and there is no available option to hide it when instantiating the Items API.

Properties:
download
Type: boolean
Enables the option to download session responses to file.

Default: false

mailto

When enabled, the default mailto URI is { "to": "", "cc": "", "bcc": "", "subject": "Raw assessment responses" }

Important Not available in Microsoft-based browsers due to mailto URI length limit in IE

Default: false

boolean | object

When enabled, the default mailto URI is { "to": "", "cc": "", "bcc": "", "subject": "Raw assessment responses" }

Important Not available in Microsoft-based browsers due to mailto URI length limit in IE

Types
boolean
Enabling sending out emails with the default mailto options.
object
Properties:
to
Type: string
Main recipient email address.
cc
Type: string
CC email address.
bcc
Type: string
BCC email address.
subject
Type: string
Email subject.

Default: false

object

Customize navigational attributes are available to the user interacting with the player.

Important Supported with rendering_type: "assess" only.

Properties:
auto_save

Enable automatic saving of session responses during assessment.

Note By default, this feature will check every 300 seconds for changes to the session responses, and silently save the responses.

Default: false

warning_on_change

When navigating to the next Item, provide a warning message if the current Item has any Questions that do not yet have a response or do not achieve the minimum requirements.

Default: false

warning_on_section_change
Type: boolean

When navigating to the next section, provide a confirmation message that explains, if users navigate to the next section, they will not be able to go back.

Default: false

enable_arrowkey_item_change
Type: boolean
Enable the arrow keys for navigating forward and backward through Items.

Default: false

exit_securebrowser
Type: boolean

Deprecated

Enable to exit the secure browser once the session is finished.

Default: true

resource_items
Type: array

The item provided, will show in a panel after clicking the resource button in the player.

Important Items with questions should not be used.

Note You can upload files and images in resource item.
intro_item
Type: string

The intro item reference, which the Items API will render at the beginning of the session.
outro_item
Type: string

The outro item reference, which the Item API renders after the session has been completed.
scrolling_indicator
Type: boolean

When enabled, shows a scrolling indicator at the bottom of the horizontal-fixed layout.

Note See the article on User Interface Regions for more.

Default: false

scroll_to_test

When enabled, this allows Items API to scroll the page to the top of its assessment container when the session starts.

Note This feature is useful for long pages where the user may scroll past the assessment container, moving it out of focus.

Default: true

scroll_to_top

When enabled, this allows Items API to scroll to the top of the container when the user navigates to the next or previous item.

Note This feature has the same behavior as scroll_to_test, but triggers every time the user navigates between items.

Default: true

show_acknowledgements
Type: boolean

Enable to show any acknowledgement of assets used in the test for copyright purposes.

Note This information will be shown inside the outro item.

Default: false

show_intro
Type: boolean

Enable to show an introduction page. If intro_item is not set, the default intro Item will be used instead.

Note The introduction page won’t load if a session is in resume or review mode after it exits.

Default: true

show_outro
Type: boolean
Enable to show an outro page. If outro_item is not set, the default outro Item will be used instead.

Default: true

skip_submit_confirmation
Type: boolean
Enable to prevent any user interaction after clicking Finish/Submit test. The test will be submitted and the page will automatically be redirected (if enabled).

Default: false 

"navigation": {
    "auto_save": {
        "changed_responses_only": false,
        "save_interval_duration": 500,
        "ui": true,
    },
    "warning_on_change": {
        "disable_item_navigation": true
    },
    "warning_on_section_change": false,
    "skip_submit_confirmation": false,
    "show_intro": true,
    "resource_items": ["resource"],
    "intro_item": "Intro Item Reference 123",
    "show_outro": true,
    "outro_item": "Outro Item Reference 456",
    "show_acknowledgements": true,
    "scroll_to_top": true,
    "scroll_to_test": true,
    "exit_securebrowser": true
}
boolean | object

Enable automatic saving of session responses during assessment.

Note By default, this feature will check every 300 seconds for changes to the session responses, and silently save the responses.

Types
boolean

Enables auto saving with the default behavior.

Note this auto save feature will be paused if there is any active video or audio recording and will be resumed once the recording is stopped/completed - a paused recording is considered an active recording.
object
Properties:
changed_responses_only
Type: boolean

Only auto-save when there are changes to responses.

Note Set to false to have the auto save feature triggers periodically regardless of changes to responses.

Default: true

save_interval_duration
Type: number
The number of seconds between each auto-save check.

Default: 300

ui
Type: boolean
Enable a UI indicator.

Default: false

disable_force_save_on_quit
Type: boolean

Enable this to ignore the force save when quitting, unloading or when navigating away from the page.

By default it's set to false which will always allow the force save on quit.

Default: false

Default: false

boolean | object

When navigating to the next Item, provide a warning message if the current Item has any Questions that do not yet have a response or do not achieve the minimum requirements.

Types
boolean
Shows a warning message with the default behavior, which still allows users to navigate to the next Item.
object
Properties:
disable_item_navigation
Type: boolean

Setting this to true will hide the continue button from the warning dialog, and prevent Item navigation.

Default: false

Default: false

boolean | object

When enabled, this allows Items API to scroll the page to the top of its assessment container when the session starts.

Note This feature is useful for long pages where the user may scroll past the assessment container, moving it out of focus.

Types
boolean
Enable scrolling to the top of the assessment container without any additional offset.
object
Properties:
offset_top
Type: string

Enable scrolling above top of the assessment container based on the offset. Value in px.

Note This setting is useful when having a custom header above the assessment container.

Example: "10px"

Default: true

boolean | object

When enabled, this allows Items API to scroll to the top of the container when the user navigates to the next or previous item.

Note This feature has the same behavior as scroll_to_test, but triggers every time the user navigates between items.

Types
boolean
Enable scrolling to the top of the assessment container without any additional offset.
object
Properties:
offset_top
Type: string

Enable scrolling above top of the assessment container based on the offset. Value in px.

Note This setting is useful when having a custom header above the assessment container.

Example: "10px"

Default: true

object
Used to define certain behavior which falls under the functionality provided under the hood by the Questions API, specifically concerning question rendering, and scoring behavior.
Properties:
allow_negative_scores
Type: boolean

When set to true, this feature will allow questions to have negative scores, which will penalize the user by negating from the total score if the answer is incorrect.

When set (to either true or false), this flag takes precedence over the same setting in individual questions.

When omitted, the default behavior is to normalize any negative scores to zero. Individual questions can still override that behavior by specifying their own value for allow_negative_scores.

attribute_overrides
Type: object

This allows activity level overrides to be specified in init options.

If an attribute is specified as true, then it will override this attribute to true in question JSON for all questions which support this attribute in the activity.

If an attribute is specified as false, then it will override this attribute to false in question JSON for all questions which support this attribute in the activity.

If an attribute is unspecified, the behaviour specified by the question JSON will apply.

Possible values:
  • "instant_feedback" will toggle visibility of the Check Answer Button in the question.
  • "spellcheck" will turn the browser spellcheck on or off.
captureOnResumeError
Type: boolean

By default, when initializing an activity in the "resume" state, Items API will trigger an error for any question's response_id not found within the Learnosity database.

If enabled, Items API will suppress the above error, effectively applying the same behavior as the "initial" state for those questions.

This only applies to activities initialized with "submit_practice" type.

Important As of Items API v1.76, this functionality is deprecated due to changes in state management.

Default: false

custom_widget_options
Type: object

This allows the clients to pass configuration data to certain third-party custom questions/features.

This is helpful when the third-party custom questions/features need to authenticate the current user.
Type: boolean

Sets whether URLs, entered by the user should automatically become clickable-links.

The property disable_auto_link will be considered true if either initialization object's disable_auto_link (at the Activity level), or questions's disable_auto_link (at the Question level) is set to true.

Default: false

disable_spokenmath_user_inputs
Type: boolean

This allows the clients to disable spokenmath in math questions user input. Spokenmath auto generates assistive text strings of the math for accessible users.

Default: false

disable_spokenmath_distractors
Type: boolean

This allows the clients to disable spokenmath in question distractors. Spokenmath is used to auto generate assistive text strings of math contained in answer options of Question types like MCQ.

Default: false

enable_formula_keyboard_lazy_render
Type: boolean

Sets whether formula and chemistry keyboards should render once an input is first focussed, rather than in the background when all other UI elements are first being rendered. This might contribute to an optimization in rendering times when there are a lot of formula or chemistry questions being rendered at once.

Default: false

fontsize
Type: string

The text font size used for rendering.

Important Supported with rendering_type: "inline" only.

Possible values:
  • "small"
  • "normal"
  • "large"
  • "xlarge"
  • "xxlarge"

Default: "normal"

math_renderer
Type: string

This option allows you to overwrite the math_renderer option inside all questions.

Possible values:
  • "mathjax"
  • "mathquill"

Default: "mathjax"

mirror_visibility
Type: boolean

If enabled, the visibility of floating elements such as the Calculator or Image Tool will mirror that of the question or feature to which they belong.

When a Question or Feature element is hidden with display: none, any associated floating elements will remain visible because they are not descendants of the Question or Feature element. Setting mirror_visibility: true will ensure floating elements are hidden when their associated Question or Feature element is hidden, and shown again when the Question or Feature element becomes visible.

In addition to hiding floating elements, media elements such as Video Player or Audio Player features will be paused.

Default: false

renderSaveButton
Type: boolean

If enabled, Items API will render a save button, enabling users to save their current progress to the Learnosity database.

Note For more information, see the advanced save and submit handling knowledge base article.

Important Supported with rendering_type: "inline" only.

Default: false

renderSubmitButton
Type: boolean

If enabled, Items API will render a submit button.

Note For more information, see the advanced save and submit handling knowledge base article.

Important Supported with rendering_type: "inline" only.

Default: false

showCorrectAnswers
Type: boolean

This flag has different behaviors based on the value provided for state.

In "initial" or "resume" state:

  • When set to true, the correct answer will be shown when the user choose to check answers.
  • When set to false, the correct answer will not be shown.
  • When omitted, the correct answer will not be shown.

In "review" state:

  • When set to true, the correct answers will be shown together with the user answers.
  • When set to false, the correct answers will be hidden.
  • When omitted, the correct answers will be shown together with the user answers.

Note This flag has no behavioral changes in the "preview" state.

show_distractor_rationale

Options for controlling how distractor rationale are displayed based on the student's response.

In "initial" and "resume" state, distractor rationale are displayed when the Check Answer button is clicked, or when the validate() method is called. In "review" state, distractor rationale are displayed immediately.

Boolean values can be used as shorthand for the following:

  • When set to true, this will have the same effect as a DistractorRationaleOptions object with "per_question": "incorrect" and "per_response": "always".
  • When set to false, this will have the same effect as a DistractorRationaleOptions object with "per_question": "never" and "per_response": "never".

Note For more information, see the DistractorRationaleOptions object definition.

Default: false

showInstructorStimulus
Type: boolean

If enabled, the content stored inside the instructor_stimulus will be shown above the question's stimulus.

Note This can be used to show additional information to the administrators but not the users taking the assessment.

Default: false

skip_highlight_animation Deprecated
Type: boolean

This property skip_highlight_animation is superseded by skip_replay_animation which can be used for general usage to skip animations for all question types. Please refer to and use skip_replay_animation.

Default: false

skip_replay_animation
Type: boolean

Causes replay animations to be skipped for all Question types, when set to true.

If this property is enabled in the "review" state, Question types that support replay animations won't show the replay animation (such as image highlight and drawing Question types).

The property skip_replay_animation will be considered true if either skip_replay_animation or skip_highlight_animation is set to true.

This property supersedes the skip_highlight_animation property, which has been deprecated.

Default: false

validateOnSubmit
Type: boolean

If enabled, Items API will determine whether instant feedback should be provided when the users submit their assessment.

Not all questions support this feature. Incompatible questions will be ignored.

Note When enabled, all supported questions will be validated regardless of the setting of instant_feedback inside each question.

Important Each question may define its own maximum number of validation attempts through feedback_attempts. Once reached, the question will not be validated again.

Important Supported with rendering_type: "inline" only.

Default: false

question_source
Type: string

If set, Questions API will attempt to render questions using saved data within the Learnosity database, instead of the values passed in the questions array.

Note This behavior only affect activities initializing in "resume" or "review" states.

Possible values:
  • "original" retrieves the Question JSON captured on init. This is always the original Question as seen by the student.
  • "scorable" retrieves the version of the Question currently used for backend scoring. Unless modified via the rescoring process, this will be the same as the original Question seen by the student.
  • "raw" uses the latest/raw JSON definitions loaded by Items API from the Itembank.

Default: raw

object

Used to define time parameters including countdown and expiry settings.

This configuration can also be set inside each sections to define the time parameters of each sections.

Note When using sections and a time configuration has been set in any section, the global time configuration will be ignored.

Important Supported with rendering_type: "assess" only.

Properties:
countdown
Type: number
Count down time in seconds shown to the student in a modal window, if an administrator ends their session via remote control.

Default: 10

countdown_option
Type: boolean
By default, the timer in the player counts up from zero. Setting this option to true will enable the timer to count down from max_time.

Default: false

limit_type
Type: string
Specify the action when the time limit (max_time) expires. A hard limit forces a dialog for the student to submit the test, a soft limit has no action.
Possible values:
  • "soft"
  • "hard"

Default: "soft"

max_time
Type: number

The length of test session, in seconds.

Note The setting can be extended by proctor in live report type

Default: 1500

warning_time
Type: number
If set, the assessment player will show a visual cue (red background) in the timer element when the session has warning_time seconds left.
 
"time": {
    "max_time": 600,
    "limit_type": "hard",
    "warning_time": 60,
    "countdown_option": true
}
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.

Properties:
data_table_seed
Type: string

A randomising seed that will be used to generate a sequence of data rows given to students clicking Try Again.

Default: If not defined, the random seed will use the value of the current session_id + item's reference / id.

data_table_index
Type: int

A configuration parameter that will be used to specify a single row in the dynamic content dataset to serve at runtime. It will be applied to all Items which have dynamic content. This is zero-based, so a value of 0 will return the first row.

Note data_table_index will override data_table_seed if they are passed simultaneously.

Important try_again will ignore data_table_index. Do not use them at the same time.
try_again
Type: object

Allows students to ask for another set of data for the Question they are attempting.

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

Allows students to ask for another set of data for the Question they are attempting.

Properties:
max_attempts
Type: integer

A number from 1 to 10 that sets the amount of times the user can click Try Again. Dataset rows are processed sequentially by default.

Default: If the number of dataset rows is less than the defined max_attempts, then that Item will will use the number of rows available.

random
Type: boolean

Changes the initial loading of data rows from the original author dataset to be random (when true). This controls how the data from the dataset is captured and brought down to the page.

Default: false

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

See Data API Pools for more information.

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.

Types
string
ItemObject

Item objects can be used in place of Item references when Items from multiple Item banks or Item pools need to be used within the same Activity.
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.

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

See Multiple Activity template and Item sources for more information.

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"
boolean
Brings the Item tags along with the assessment content. Used for content debugging in test environments or other advanced use-cases.

Default: false

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.

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.

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

Properties:
config
Type: array[object]
You can override initial configuration by passing properties such as:
  • regions e.g. allowing assessments to be broken up into sections for delivery, with some sections having specific tools (e.g. calculator) and others without tools.
  • title
  • subtitle
  • configuration
items
Type: array[object]
This works exactly like items in a normal activity.

See items definition for more information.

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

object

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

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.

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

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

Default: "initial"

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.

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"

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

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.

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

See troubleshooting for more information.

Parameters
error
Type: Error
Function to be called when the API has been successfully initialized.

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

object
Properties:
colors
name
Type: string
A name that describes the palette.
object
Properties:
button-background
Type: string
Hex or RGB color code.
button-background-highlight
Type: string
Hex or RGB color code.
button-background-highlight-hover
Type: string
Hex or RGB color code.
button-background-hover
Type: string
Hex or RGB color code.
button-color
Type: string
Hex or RGB color code.
button-color-highlight
Type: string
Hex or RGB color code.
content-background
Type: string
Hex or RGB color code.
content-background-correct
Type: string
Hex or RGB color code.
content-background-highlight
Type: string
Hex or RGB color code.
content-background-highlight-hover
Type: string
Hex or RGB color code.
content-background-incorrect
Type: string
Hex or RGB color code.
content-background-selected
Type: string
Hex or RGB color code.
content-border
Type: string
Hex or RGB color code.
content-border-correct
Type: string
Hex or RGB color code.
content-border-focus
Type: string
Hex or RGB color code.
content-border-incorrect
Type: string
Hex or RGB color code.
content-color
Type: string
Hex or RGB color code.
content-color-active
Type: string
Hex or RGB color code.
content-color-hover
Type: string
Hex or RGB color code.
Type: string
Hex or RGB color code.
Type: string
Hex or RGB color code.
Type: string
Hex or RGB color code.
content-color-neutral
Type: string
Hex or RGB color code.
content-color-subheading
Type: string
Hex or RGB color code.
content-color-toolbar
Type: string
Hex or RGB color code.
content-color-widget
Type: string
Hex or RGB color code.
progress-background
Type: string
Hex or RGB color code.
progress-color
Type: string
Hex or RGB color code.
well-background
Type: string
Hex or RGB color code.
well-background-toolbar
Type: string
Hex or RGB color code.
well-background-grayed
Type: string
Hex or RGB color code.
well-background-highlight
Type: string
Hex or RGB color code.
well-background-warning
Type: string
Hex or RGB color code.
well-color
Type: string
Hex or RGB color code.
well-color-grayed
Type: string
Hex or RGB color code.
well-color-highlight
Type: string
Hex or RGB color code.
well-color-toolbar
Type: string
Hex or RGB color code.
well-color-warning
Type: string
Hex or RGB color code.
widget-background
Type: string
Hex or RGB color code.
widget-background-active
Type: string
Hex or RGB color code.
widget-background-hover
Type: string
Hex or RGB color code.
widget-background-toolbar
Type: string
Hex or RGB color code.
object
Properties:
per_question
Type: string

Determines when question-level distractor rationale are displayed. Question-level distractor rationale content is defined for each question in metadata.distractor_rationale.

Possible values:
  • "always" will display question-level distractor rationale for any response.
  • "never" will never display question-level distractor rationale.
  • "correct" will only display question-level distractor rationale when the response is correct.
  • "incorrect" will only display question-level distractor rationale when the response is incorrect.

Default: "incorrect"

per_response
Type: string

Determines when response-level distractor rationale are displayed. Response-level distractor rationale content is defined for each question in metadata.distractor_rationale_response_level.

Note This only applies to Question types that support the metadata.distractor_rationale_response_level property. See Question Types for further information.

Possible values:
  • "always" will display distractor rationale for every checked response or non-empty response container.
  • "never" will never display response-level distractor rationale.

Default: "always"

object

Item objects can be used in place of Item references when Items from multiple Item banks or Item pools need to be used within the same Activity.

See Using Multiple Item Bank Sources in the Items API for more information.

Properties:
id
Type: string
A host-page supplied unique identifier (which can be the same as the Item reference).
Note When using a different value than the reference, some data from Reports API might be affected.

See Multiple Item source requirements for more information.

item_pool_id
Type: string
Sets or override the Item Pool to retrieve Item from.

See Data API Pools for more information.

organisation_id
Type: string
Sets or override the Item Bank to retrieve Item from.

See Multiple Item sources for more information.

reference
Type: string
The Item reference to retrieve
scoring_type
Type: string
The scoring type specified in the Item Bank can be overriden for each Item. If desired, it can also be overridden for the entire Activity. If both an Item-level and an Activity-level scoring types are specified, the Item-level configuration takes precedence.
data_table_row
Type: string
A configuration parameter that will be used to specify the key of a single row in the dynamic content dataset to serve at runtime.
Important It must be a valid UUID.
Note It has priority over data_table_index in itemObject.
Note It has priority over data_table_index value in dynamic_items.
data_table_index
Type: int
A configuration parameter that will be used to specify the index of a single row in the dynamic content dataset to serve at runtime.
Note It will override the data_table_index value in dynamic_items.
object

See troubleshooting for more information.

Properties:
code
Type: number
msg
Type: string
detail
Type: string