Questions API Initialization

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

This method is the entry point to initializing and rendering Questions API, and it requires two key parameters, as per the example below.

Initialization object
Callbacks object

Only the Initialization object is mandatory.

Example

const initializationObject = {
    // Security
    "consumer_key" : "ts34Rdc45SWE34f",
    "signature": "22d26b3b582d5bca19b26784534b338381a0ac1bc737b071a971c5b7d0cf9721",
    "timestamp": "20110918-1820",
    "user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b",

    // Mandatory
    "id": "f0001",
    "name": "Intro Activity - French 101",
    "questions": [
         {
             "response_id": "60005",
             "type": "association",
             "stimulus": "Match the cities to the parent nation.",
             "stimulus_list": ["London", "Dublin", "Paris", "Sydney"],
             "possible_responses": ["Australia", "France", "Ireland", "England"
             ],
             "validation": {
                "valid_responses": [
                    ["England"],["Ireland"],["France"],["Australia"]
                ]
            },
            "instant_feedback": true
        }
    ],
    "session_id" : "f47ac10b-58cc-4372-a567-0e02b2c3d479",

    // Optional
    "captureOnResumeError": true,
    "math_renderer": "mathquill",
    "render_with_captured_questions": true,
    "renderSaveButton": true,
    "renderSubmitButton": true,
    "show_distractor_rationale": true,
    "state": "initial",
    "type": "submit_practice",
    "validateOnSubmit": true,

    // These are override parameters. These change the default behaviour of
    // Questions API. Only use if the specific override behaviour is desired.
    // "allow_negative_scores": true,
    // "fontsize": "normal",
    // "showCorrectAnswers": false,
    // "showInstructorStimulus": true,
    // "attribute_overrides": {
    //      "spellcheck": true,
    //      "instant_feedback": false
    // }
}

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);
    },
    /* example object
    {
        code:   10001,
        msg:    "JSON format error",
        detail: "Activity JSON Poorly formed. Incorrect activity type found: abcd",
    }
    */

    readyListener: function() {
        console.log("Learnosity Questions API is ready");
    },

    labelBundle: {
        loadingInfo: "Loading page...",
        play: "play",
        ...
    },

    saveSuccess: function(response_ids) {
        for(let i = 0; i < response_ids.length; i++) {
            console.log("Responses saved : ", response_ids[i]);
        }
    },

    saveError: function(e) {
        console.log("Save failed - error ", e);
    },

    saveProgress: function(progress) {
        console.log("Save progress - ", progress);
    }
};

const questionsApp = window.LearnosityApp.init(initializationObject, callbacks);

Initialization Object

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

It includes all the information needed for authentication, user identification, Question workflow, and UI elements such as save or submit buttons.

Properties

= mandatory property

consumer_key string
Provided by Learnosity as part of the consumer on-boarding process.
signature string
The HMAC SHA256 hash of a series of parameters plus the consumer_secret.
timestamp string
The current time in GMT/UTC using the format: YYYYMMDD-HHMM.
user_id string
User ID unique to the user that is creating/has created the responses.
allow_negative_scores 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.
attribute_overrides object
This allows activity level overrides to be specified in init options.
captureOnResumeError boolean
By default, when initializing an activity in the "resume" state, Questions API will trigger an error for any question's response_id not found within the Learnosity database.
custom_widget_options object
This allows the clients to pass configuration data to certain third-party custom Questions and Features.
disable_auto_link boolean
Sets whether URLs, entered by the user should automatically become clickable-links.
disable_spokenmath_user_inputs boolean
This allows the clients to disable spokenmath in math questions user input.
disable_spokenmath_distractors boolean
This allows the clients to disable spokenmath in question distractors.
enable_formula_keyboard_lazy_render 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.
features array[FeatureJson]
List of Feature JSON objects to use in the assessment.
fontsize string
The text font size used for rendering.
id string
The activity id which can be used to group assessment sessions from users.
labelBundle object
Specifies overrides for labels and text content shown in all Question types.
math_renderer string
This option allows you to overwrite the math_renderer option inside all questions.
mirror_visibility 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.
name string
Activity name, used when submitting and retrieving student responses via Learnosity's Reports API and Data API.
questions array[QuestionJson]
List of Question JSON objects to use in the assessment.
render_with_captured_questions boolean Deprecated
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.
question_source 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.
render_optimization object
Options for optimizing the rendering performance of Questions.
renderSaveButton boolean
If enabled, Questions API will render a save button, enabling users to save their current progress to the Learnosity database.
renderSubmitButton boolean
If enabled, Questions API will render a submit button.
session_id UUIDv4
The session_id is the reference to an user's attempt at an assessment.
show_distractor_rationale boolean | DistractorRationaleOptions
Options for controlling how distractor rationale are displayed based on the student's response.
showCorrectAnswers boolean
This flag has different behaviors based on the value provided for state.
showInstructorStimulus boolean
If enabled, the content stored inside the instructor_stimulus will be shown above the question's stimulus.
skip_highlight_animation boolean Deprecated
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.
skip_replay_animation boolean
Causes replay animations to be skipped for all Question types, when set to true.
state string
Sets the state of the activity.
type string
The activity type defines various behaviors around saving and submitting, such as where to store the assessment data and the availability of public methods around saving and submitting.
validateOnSubmit boolean
If enabled, Questions API will determine whether instant feedback should be provided when the users submit their assessment.

Callbacks

customUnload function
This function is called when the user attempts to close the browser window.
errorListener function
Function to be called on a Learnosity error event.
readyListener function
Function to be called when the API has been successfully initialized.
saveError function
Callback for use when calling save() or submit().
saveProgress function
Callback for use when calling save().
saveSuccess function
Callback for use when calling save() or submit().

HTML Hooks

Specific HTML tags must be placed in the page to indicate to the Questions API where it should render.

They are identified by the classes: learnosity-response and question-[response_id], where response_id matches one of the response_ids provided in the questions array of the Initialization Object.

<h2>Question 1</h2>
<span class="learnosity-response question-60001"></span>

<h2>Question 2</h2>
<span class="learnosity-response question-60002"></span>

<h2>Feature 1</h2>
<span class="learnosity-feature feature-70001"></span>