Warning Warning! This is a lower-level API. Lower-level APIs are not recommended for most projects, and may not be available on all plans. See our page on recommended deployment patterns for more information.

Initialization

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

This method is the starting point to initializing and rendering Assess API, and as you can see in the example below, takes three key parameters.

Only the Initialization object is mandatory.

const initializationObject = {
    "items": [
        {
            "content": "<span class='learnosity-response question-demoscience1234'></span>",
            "response_ids": [
                "demoscience1234"
            ],
            "workflow": "",
            "reference": "question-demoscience1"
       },
       {
           "content": "<span class='learnosity-response question-demoscience5678'></span>",
           "response_ids": [
               "demoscience5678"
           ],
           "workflow": "",
           "reference": "question-demoscience2"
       }
    ],
    "questionsApiActivity": {
        "consumer_key": "INSERT_CONSUMER_KEY_HERE",
        "timestamp": "INSERT_CURRENT_TIMESTAMP_HERE",
        "signature": "INSERT_GENERATED SIGNATURE HERE",
        "user_id": "demo_student",
        "type": "submit_practice",
        "state": "initial",
        "id": "assessdemo",
        "name": "Assess API - Demo",
        "questions": [
             {
                "response_id": "demoscience1234",
                "type": "sortlist",
                "description": "In this question, the student needs to sort the events, chronologically earliest to latest.",
                "list": ["Russian Revolution", "Discovery of the Americas", "Storming of the Bastille", "Battle of Plataea", "Founding of Rome", "First Crusade"],
                "instant_feedback": true,
                "feedback_attempts": 2,
                "validation": {
                    "valid_response": [4, 3, 5, 1, 2, 0],
                    "valid_score": 1,
                    "partial_scoring": true,
                    "penalty_score": -1
                }
            },
            {
                "response_id": "demoscience5678",
                "type": "highlight",
                "description": "The student needs to mark one of the flower's anthers in the image.",
                "img_src": "http://www.learnosity.com/static/img/flower.jpg",
                "line_color": "rgb(255, 20, 0)",
                "line_width": "4"
            }
        ]
    }
};

const 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 Questions API is ready");
    }
};

const assessApp = window.LearnosityAssess.init(initializationObject, "learnosity_assess", callbacks);
        

The Initialization object is a JSON object which is passed as the first parameter into the window.LearnosityAssess.init() method.

It includes all the information needed for Authentication, User Identification, Action Builder, and UI elements such as Table of Contents or various buttons. Only a few attributes 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

object

Enables an administration panel with various control options.

Note See the configuration panel knowledge base article for detailed information on the control options.

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.

The supplied value must be a SHA256 hash of the intended password.

"administration": {
     "pwd": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
     "options": {
         "show_save": true,
         "show_submit": true,
         "show_exit": true,
         "show_extend": true
     }
}
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

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

Properties:
auto_retry_failed_images
Type: boolean

If enabled, the Assess API will attempt to try to reload any failed images.

Default: false
contrast

Define the active color scheme.

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

disable_item_workflow
Type: boolean

Disable to items workflow from being executed. This feature is useful for editing items without needing to wait out the full workflow.

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 Assess API 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 Assess API.
Possible values:
  • "small"
  • "normal"
  • "large"
  • "xlarge"
Default: "normal"
idle_timeout

When enabled, a dialog box will be shown afer a number of seconds of inactivity. Once shown, the user has limited time to close the 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 discarded.

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
Load the activity using the specified version of Questions API.
Default: "v2"
Example: "v2"

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.

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 opposed to true which gives a different order per session.

Note Visit the shuffling items documentation 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, Assess API 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.

"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
    },
    "questionsApiVersion": "v2",
    "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": true
    },
    "auto_retry_failed_images": false
}
object | string

Define the active color scheme.

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

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 assessibility palettes. This assessibility scheme will be loaded by default.

boolean | object

When enabled, a dialog box will be shown afer a number of seconds of inactivity. Once shown, the user has limited time to close the 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 discarded.

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
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 opposed to true which gives a different order per session.

Note Visit the shuffling items documentation 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, Assess API 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.

Properties:
download
Type: boolean
Enables the option to download session responses to file.
Default: true
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 recipent email address.
cc
Type: string
CC email address.
bcc
Type: string
BCC email address.
subject
Type: string
Email subject.
Default: false
boolean

By default, Assess API uses the value of the activity state inside questionsApiActivity to determine whether current session is a new session, or is an existing session. When set, this flag will override the default logic.

If true, Assess API will treat the current session as an existing session. Setting to false will force Assess API to treat the current session as a new session.

Note For new sessions, Assess API applies additional logic to the session such as showing the intro item, etc.

Array[Item]

Array of Item objects. Each Item represents a single page within the assess screens, containing questions and contents within.

"items": [
    {
        "content": "<span class=\"learnosity-response question-widget1234\"></span>",
        "response_ids": [
            "widget1234"
        ],
        "feature_ids": [
            "feature1234"
        ],
        "workflow": "",
        "reference": "ccore_ccs_rabbit",
        "metadata": {
            "display_name": "CC Card Item"
        }
    }, {
      //...
    }
]
object

Contains information related to the current session, such as:

  • current time
  • current item

Note This data is mostly used by Items API in resume mode.

"metadata": {
    // Per item metadata
    "items": [
        {
            "reference": "ccore_ccs_rabbit",
            // Define default display name of the item in TOC
            "display_name": "CC Card Item"
        }
    ],
    // Current test time
    "current_time": 660,

    // Remaining reading time
    "current_reading_time": 50,

    // Current sheet index
    "current_sheet_position": 5,
    //...
}
string

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

Important Mandatory if submitting responses to Learnosity.

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

Enable automatic saving of responses during assessment sessions.

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

Default: true
Type: boolean
Enable to exit the secure browser once the session is finished.
Default: true
Type: array

The resource item will show in the resource panel, after clicking the resource button in the right expanded menu.

Note You can upload files and images to the resource item.

Example: resource_items: ["resource"]
Type: object

The intro item, which the Assess API will render at the beginning of the session.

Note You can use this feature to present any introductory notes to the users.

Example: intro_item: { content: "Hello world..." }
Type: object

The outro item, which the Assess API renders after the session has been completed.

Note You can use this feature to present any final notes to the users.

Example: outro_item: { content: "Goodbye"}

When enabled, this allows Assess 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

When enabled, this allows Assess API to scroll to the top of the container when the user naviagtes 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
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
Type: boolean
Enable to show an introduction page. If intro_item is not set, the default intro Item will be used instead.
Default: true
Type: boolean
Enable to show an outro page. If outro_item is not set, the default outro Item will be used instead.
Default: true
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,
    },
    "skip_submit_confirmation": false,
    "show_intro": true,
    "resource_items": ["resource"],
    "intro_item": {
        "content": "Hello world..."
    },
    "show_outro": true,
    "outro_item": {
        "content": "Goodbye!"
    },
    "show_acknowledgements": true,
    "scroll_to_top": true,
    "scroll_to_test": true,
    "exit_securebrowser": true
}
boolean | object

Enable automatic saving of responses during assessment sessions.

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

Types
Enables auto saving with the default behavior.
Properties:
Type: boolean

Only auto-save when there are changes to reponses.

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

Default: true
Type: number
The number of seconds between each auto-save check.
Default: 300
Type: boolean
Enable a UI indicator.
Default: false
Default: true
boolean | object

When enabled, this allows Assess 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
Enable scrolling to the top of the assessment container without any additional offset.
Properties:
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 Assess API to scroll to the top of the container when the user naviagtes 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
Enable srolling to the top of the assessment container without any additional offset.
Properties:
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
Data from this object is passed to the Learnosity Questions API during initialization.

See Questions API Activity documentation for more information.

"questionsApiActivity": {
    "consumer_key": "yis0TYCu7U9V4o7M",
    "timestamp": "20131125-1709",
    "signature": "ea52a6b687b916e415ab9b90a120ac0265222ecf07...",
    "user_id": "demo_student",
    "state": "initial",
    "type": "submit_practice",
    "math_renderer": "mathjax",
    "questions": [
        {
            //...
        }
    ],
    "features": [
        {
            "feature_id": "feature1234",
            "type": "imagetool",
            "image": "protractor"
        }
    ]
}
object

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

Available regions:

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

Note See the assess regions knowledge base article for additional configuration options.

"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
        },
        {
            "type": "progress_element"
        }
    ],
    "bottom-right": [
        {
            "type": "next_button"
        },
        {
            "type": "previous_button"
        }
    ]
}
string
An optional test subtitle, which appears underneath the title in the player UI.
object
Used to define time parameters including countdown and expiry settings.
Properties:
countdown
Type: number
Count down time in seconds shown in administrator remote control modal - integer.
Default: 10
countdown_option
Type: boolean
Enable the count down timer.
Default: false
limit_type
Type: string
Specify the action when the time limit expires. A hard limit forces a test submit, a soft limit has no action.
Possible values:
  • "soft"
  • "hard"
Default: "soft"
max_time
Type: number
The length of test session, in seconds - integer.
Default: 1500
warning_time
Type: number
If set, the Assess API will show a visual dialog when the session has warning_time seconds left - integer.
"time": {
    "max_time": 0,
    "limit_type": "soft",
    "warning_time": 60,
    "countdown_option": true,
    "countdown": 10
}
string
Optional test title which overrides the name property.

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

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

The second parameter passed to window.LearnosityAssess.init() is a string, containing either an id or a full CSS selector to an element on the HTML page. Each example below could be a valid value:

learnosity_assess  // just an id
#learnosity_assess // CSS selector based on id of an element
.learnosity_assess // CSS selector based on a class of an element

This value tells Assess API where to render itself on the page.

Note If the HTML element selector is not provided, Assess API will attempt to look for the element with id "learnosity_assess".

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

Properties

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

In the Initialization 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.

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:
content
Type: string
Content should contain a span element for each response_id in that item, as well as any additional description or content
response_ids
Type: Array[string]
Response Ids should be provided in the "QuestionApiActivity" to match the responses and features ,and spans provided
Example: [ "widget1234" ]
feature_ids
Type: Array[string]
Feature Ids should be provided in the "QuestionApiActivity" to match the responses and features, and spans provided
workflow
Type: string
A Workflow can be added to allow for triggered events on certain actions. This can be seen in the workflow section.
reference
Type: string
Reference should be a unique name to identify each item.
metadata
Type: object
Contains various item metadata information such as default display name of the item in TOC.
Example: metadata: { display_name: "CC Card Item" }
object

See troubleshooting for more information.

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