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.
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
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"
.
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.
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.
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 |
annotations |
Type:
boolean When set to
Important
When using with
|
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
Important
When using with |
configuration |
Type:
object Enables various customizations such as redirect URLs and reading time settings.
Important
Supported with
|
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 |
labelBundle |
Type:
Assess API Label Bundle Object of labels and values can be passed to override default English labeling
Note
The
Important
Supported with |
navigation |
Type:
object Customize navigational attributes are available to the user interacting with the player.
Important
Supported with
|
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:
Important
Supported with See Assess regions knowledge base article for more information.
|
subtitle |
Type:
string Sets the subtitle of the activity.
Important
Supported with
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
Note
When using
Important
Supported with
|
title |
Type:
string Sets the title of the activity.
Important
Supported with
Default: |
configadministration
objectEnables 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. |
configadministrationoptions
objectProperties: | |
---|---|
show_exit |
Type:
boolean Enables the Discard & exit button.
Default: |
show_extend |
Type:
boolean Enables the option to add extra time allowed to complete the session.
Default: |
show_save |
Type:
boolean Enables the Save & exit button.
Default: |
show_submit |
Type:
boolean Enables the Submit & exit button.
Default: |
configannotations_api_init_options
objectProvide 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. |
configconfiguration
objectEnables 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: |
contrast |
Type:
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. |
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: |
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: |
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
Default: |
fontsize |
Type:
string The font size used to render text content inside Assessment Player. See our knowledge base article on this topic.
Possible values:
Default: |
idle_timeout |
Type:
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
Default: |
lazyload |
Type:
boolean Enables lazy loading of items from the Item Bank to improve loading time during API initialization.
Default: |
onsave_redirect_url |
Type:
boolean | string
Default:
Example: "https://reference.learnosity.com"
|
onsubmit_redirect_url |
Type:
boolean | string
Default:
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: |
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 |
section_options |
Type:
object Enables various customizations for |
shuffle_items |
Type:
boolean | string Enables shuffling of items based on a given seed.
Important
The
Important
If Note See the article on randomizing Item content for more.
Default: |
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
}
configconfigurationcontrast
object | stringDefine 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 |
|
||||||
string | A valid URL to a custom CSS file containing the accessibility palettes. This accessibility scheme will be loaded by default. |
configconfigurationidle_timeout
boolean | objectWhen 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 |
||||||
object |
|
Default: false
configconfigurationonsave_redirect_url
boolean | stringTypes | |
---|---|
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)
"https://reference.learnosity.com"
configconfigurationonsubmit_redirect_url
boolean | stringTypes | |
---|---|
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)
"https://reference.learnosity.com"
configconfigurationreading_mode
objectAllocate 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: |
reading_time |
Type:
number Allocate a number of seconds as the reading time period.
Default: |
warning_time |
Type:
number Display a visual warning when n number of seconds left for the reading time.
Default: |
configconfigurationsection_options
objectEnables 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: |
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: |
reset_itemcount_per_section |
Type:
boolean When using Note that this attribute will be ignored if
Default: |
configconfigurationshuffle_items
boolean | stringEnables 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
configconfigurationsubmit_criteria
objectDefine 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:
Example: 50
|
type |
Type:
string The type of action the user performed on each question.
Possible values:
Default: |
configconfigurationsubmit_failed_options
objectSet 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: |
mailto |
Type:
boolean | object When enabled, the default mailto URI is Important Not available in Microsoft-based browsers due to mailto URI length limit in IE
Default: |
configconfigurationsubmit_failed_optionsmailto
boolean | objectWhen 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 |
|
Default: false
confignavigation
objectCustomize navigational attributes are available to the user interacting with the player.
Important
Supported with rendering_type: "assess"
only.
Properties: | |
---|---|
auto_save |
Type:
boolean | object Enable automatic saving of session responses during assessment.
Note
By default, this feature will check every
Default: |
warning_on_change |
Type:
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.
Default: |
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: |
enable_arrowkey_item_change |
Type:
boolean Enable the arrow keys for navigating forward and backward through Items.
Default: |
exit_securebrowser |
Type:
boolean Deprecated Enable to exit the secure browser once the session is finished.
Default: |
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: |
scroll_to_test |
Type:
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.
Default: |
scroll_to_top |
Type:
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
Default: |
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: |
show_intro |
Type:
boolean Enable to show an introduction page. If
Note
The introduction page won’t load if a session is in
Default: |
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: |
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: |
"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
}
confignavigationauto_save
boolean | objectEnable 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 |
||||||||||
object |
|
Default: false
confignavigationwarning_on_change
boolean | objectWhen 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 |
|
Default: false
confignavigationscroll_to_test
boolean | objectWhen 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 |
|
Default: true
confignavigationscroll_to_top
boolean | objectWhen 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 |
|
Default: true
configquestions_api_init_options
objectProperties: | |
---|---|
allow_negative_scores |
Type:
boolean
When set to
When set (to either
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 |
attribute_overrides |
Type:
object This allows activity level overrides to be specified in init options. If an attribute is specified as If an attribute is specified as If an attribute is unspecified, the behaviour specified by the question JSON will apply.
Possible values:
|
captureOnResumeError |
Type:
boolean
By default, when initializing an activity in the
If enabled, Items API will suppress the above error, effectively applying the same behavior as the
This only applies to activities initialized with Important As of Items API v1.76, this functionality is deprecated due to changes in state management.
Default: |
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. |
disable_auto_link |
Type:
boolean Sets whether URLs, entered by the user should automatically become clickable-links.
The property
Default: |
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: |
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: |
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: |
fontsize |
Type:
string The text font size used for rendering.
Important
Supported with
Possible values:
Default: |
math_renderer |
Type:
string
This option allows you to overwrite the
Possible values:
Default: |
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 In addition to hiding floating elements, media elements such as Video Player or Audio Player features will be paused.
Default: |
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
Default: |
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
Default: |
showCorrectAnswers |
Type:
boolean This flag has different behaviors based on the value provided for state.
In
In
Note
This flag has no behavioral changes in the |
show_distractor_rationale |
Type:
boolean | DistractorRationaleOptions Options for controlling how distractor rationale are displayed based on the student's response.
In Boolean values can be used as shorthand for the following:
Note For more information, see the DistractorRationaleOptions object definition.
Default: |
showInstructorStimulus |
Type:
boolean
If enabled, the content stored inside the Note This can be used to show additional information to the administrators but not the users taking the assessment.
Default: |
skip_highlight_animation
Deprecated
|
Type:
boolean
This property
Default: |
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
The property
This property supersedes the
Default: |
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
Important
Each question may define its own maximum number of validation attempts through
Important
Supported with
Default: |
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
Note
This behavior only affect activities initializing in
Possible values:
Default: |
configtime
objectUsed 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: |
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: |
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:
Default: |
max_time |
Type:
number The length of test session, in seconds.
Note
The setting can be extended by proctor in
Default: |
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
}
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 |
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
Note
Important
|
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
}
}
dynamic_itemstry_again
objectAllows 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: |
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.
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. |
Name of the activity that will be displayed in Learnosity's Reports API and Data API.
Important Required only if submitting responses to Learnosity.
See Multiple Activity template and Item sources for more information.
"assess"
"inline"
Default: false
See Item Scoring tutorial for more information.
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:
|
items |
Type:
array[object] This works exactly like items in a normal activity. See items definition for more information. |
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
Custom metadata to include for the user's assessment session. This metadata is stored when the session is saved or submitted.
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.
"initial"
"resume"
"review"
"preview"
Default: "initial"
See Activity Subscores for more information.
"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"
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
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.
See troubleshooting for more information.
Parameters | |
---|---|
error |
Type:
Error |
Object Definitions
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
Properties: | |
---|---|
colors |
|
name |
Type:
string A name that describes the palette. |
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. |
content-color-link |
Type:
string Hex or RGB color code. |
content-color-link-hover |
Type:
string Hex or RGB color code. |
content-color-link-visited |
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. |
Properties: | |
---|---|
per_question |
Type:
string
Determines when question-level distractor rationale are displayed. Question-level distractor rationale content is defined for each question in
Possible values:
Default: |
per_response |
Type:
string
Determines when response-level distractor rationale are displayed. Response-level distractor rationale content is defined for each question in
Note
This only applies to Question types that support the
Possible values:
Default: |
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. |
See troubleshooting for more information.
Properties: | |
---|---|
code |
Type:
number |
msg |
Type:
string |
detail |
Type:
string |