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.LearnosityApp.init() 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.

Only the Initialization object is mandatory.

const initializationObject = {
    // Security
    "consumer_key" : "ts34Rdc45SWE34f",
    "signature": "22d26b3b582d5bca19b26784534b338381a0ac1bc737b071a971c5b7d0cf9721",
    "timestamp": "20110918-1820",
    "user_id": "12345678",

    // 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",
    "prevent_flash": false,
    "render_with_captured_questions": true,
    "renderSaveButton": true,
    "renderSubmitButton": 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
}

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);

The Initialization object is a JSON object which is passed as the first parameter to 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

string

Provided by Learnosity as part of the consumer on-boarding process. The consumer_key and consumer_secret pair is your identify to Learnosity APIs.

string

The SHA256 hash of a series of parameters plus the consumer_secret.

Important Never expose your consumer_secret.

See security and authentication for more information.

string

The current time in GMT/UTC using the format: YYYYMMDD-HHMM.

string

User ID unique to the user that is creating/has created the responses.

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.

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.

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

Important This only apply to activities initialized with "submit_practice" type.

Default: false
string

The text font size used for rendering.

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

The activity id which can be used to group assessment sessions from users. Must not exceed 36 characters.

Note For more information, usages, limitations and suggestions from Learnosity, visit the activity id knowledge base article.

object

A JavaScript object containing labels and values, that can be passed to override the default English labeling.

Note For more information, see the I18n section.

Properties:
[key]
Type: string
string

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

Possible values:
  • "mathjax"
  • "mathquill"
Default: "mathjax"
string

Activity name, used when submitting and retrieving student responses via Learnosity's Reports API and Data API.

array[QuestionJson | FeatureJson]

List of questions and/or features.

"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
    }
]
boolean

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 with "resume" or "review" state.

Default: false
boolean

If enabled, Questions 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.

Default: false
boolean

If enabled, Questions API will render a submit button.

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

Default: false
UUIDv4

The session_id is the reference to an user's attempt at an assessment. This value will be used to obtain any saved progress for the requested user when initializing Questions API in "resume" or "review" state.

Once the assessment has been submitted and processed, the session_id can be used to obtain the session data in Data API or to show graphical reports within Reports API

Note For more information, see the Learnosity SDK session_id generation.

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.

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
boolean

If enabled and in "review" state, the Image Highlight Question Type instances won't show the initial animation.

Default: false
string

The activity state to tell Questions API to initialize.

The "initial" state is to denote a new assessment session, whereas the "resume" state denotes an existing session that the user has partly attempted.

The "review" state is generally used to show the assessment with user answers, and the "preview" state is for the test administrator to preview their contents.

Possible values:
  • "initial"
  • "preview"
  • "resume"
  • "review"
Default: "initial"
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.

Possible values:
  • "local_practice"
  • "submit_practice"
Default: "local_practice"
boolean

If enabled, Questions 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.

Default: false

Function to be called on a Learnosity error event.

Note For more information, see the troubleshooting section.

Parameters
error
Type: Error
object

Declaring labelBundle in this way has been deprecated. Please declare labelBundle through initOptions.labelBundle instead.

A JavaScript object containing labels and values, that can be passed to override the default English labeling.

Note For more information, see the I18n section.

Properties:
[key]
Type: string

Function to be called when the API has been successfully initialized.

Callback for use when calling save() or submit().

Note For more information, see the troubleshooting section.

Parameters
error
Type: Error

Callback for use when calling save().

Parameters
progress
Type: object
Properties:
bytesTotal
Type: number
bytesUploaded
Type: number
percentage
Type: number
state
Type: string

Callback for use when calling save() or submit().

Parameters
response_ids
Type: Array[string]

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>

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:
code
Type: number
detail
Type: string
msg
Type: string