A quick guide to embedding the Items API (Inline Rendering Example). Please see our demos site for further examples.
1. Embedding the Script
The following script tag must be included in the page HTML.
It can be placed at any point within the page. Learnosity recommends the footer for optimum page load.
You must specify a LTS version, please refer to the API versioning article.
<script src="https://items.learnosity.com/?v2024.2.LTS"></script>
Code example 1: the script tag, which embeds Learnosity into your web page.
2. Initialization JSON
Define an initOptions
object to hold your Initialization options. You'll pass this object to Items API to configure its behaviour.
Some important points to note:
-
The
initOptions
object needs to be signed according to the Learnosity security pattern. The recommended approach is to use our SDK in your server-side application to generate the signed options packet.
Download the SDK for ASP.Net, Java, Node.js, PHP, Python or Ruby and follow the examples. For full details on the security pattern that the SDK covers for you, please see the Security & Authentication article. -
Use
request.rendering_type = "inline"
to initialise Items API in inline mode. Inline mode retrieves content from your Learnosity Item Bank and instantiates Questions API for rendering, interaction and state management. -
Use
request.items
to specify the list of Items to render. The relevant content will be retrieved from your Learnosity Item bank, and Items API will orchestrate Questions API to embed the Item content in your app.request.items
can be:- A list of Item references as strings. Example:
"items": ["Item_1", "Item_2"]
, or - A list of Item objects. Example:
"items": [{"id": "Ref", "reference": "Item_1"}]
- A list of Item references as strings. Example:
-
Use
initOptions.request.config.questions_api_init_options
to override Questions API initialization options * as desired. Items API will pass them to the Questions API instance.
* Note – you do not need to specifyinitOptions.request.config.questions_api_init_options.questions
, since Items API will construct it for you using the Item references that you provide.
<script>
var initOptions = {
"security": {
"consumer_key": "INSERT_CONSUMER_KEY_HERE",
"domain": "help.learnosity.com",
"timestamp": "20231119-2026",
"signature": "INSERT_GENERATED_SIGNATURE_HERE"
},
"request": {
"rendering_type": "inline",
"user_id": "12345678",
"session_id": "a472317d-9881-4200-8d3d-75342551af80",
"type": "submit_practice",
"activity_id": "emberDemo2013",
"name": "Items API demo - inline activity.",
"items": [
"classification_1",
"multiple_choice_1"
]
}
};
</script>
Code example 2: initialization options specified in the initOptions object.
3. HTML Hooks
Place span tags containing the class name learnosity-item
in your page to indicate where each Item should be rendered.
Add a data-reference
attribute to each span, specifying the Item to be rendered in that position. Depending on the way you set up the items
array in your initialization object, the value of these data-reference
attributes will be set up differently.
- If
items
is an array of Item reference strings, such as"items": ["multiple_choice_1", "classification_1"]
, then the value of thedata-reference
attribute will be theitem reference
.
<span class="learnosity-item" data-reference="multiple_choice_1"></span>
<span class="learnosity-item" data-reference="classification_1"></span>
Code example 3: HTML hook syntax.
- If
items
is an array of objects such as"items": [{"id": "item_1_id", "reference": "Item_1"}]
, then the value of thedata-reference
attribute will be theid
of the object.
<span class="learnosity-item" data-reference="item_1_id"></span>
4. API Initialization
Use JavaScript to initialize Items API. The init()
call must execute after <script src="https://items.learnosity.com/?v2024.2.LTS"></script>
has loaded and the initOptions
are defined.
A second argument can be passed to define some API behaviour through a Callbacks object. Further details on configuration options can be found here.
<script>
var itemsApp = LearnosityItems.init(initOptions);
</script>
</body>
</html>
Code example 5: initializing the API with an init() call.