This guide describes the simplest way to embed an assessment into your application using Learnosity's Items API.
We'll set up a simple example page that demonstrates a standalone assessment activity, then look at the code in detail.
Time to complete: 10 minutes.
- A PHP-enabled web server, installed on your local machine. (To set this up, follow our environment setup guide.)
Note: this quick start's server side code is written in PHP, but you can access this same tutorial for other languages; Python, Node.js, ASP.net, Java and Ruby.
Download the quick start examples
If you haven’t done so already, download the Learnosity quick start examples using the link below, unzip them and configure your web server to use
docs/quickstart as its document root directory. We'll assume that your web server is available at
The quick start example package includes:
- The Learnosity Software Development Kit (LearnositySDK).
- The quick start example code files.
Note: There are some additional configuration steps in our README guide, follow the instructions there relating to your installation method.
Once set up, you can load the examples index page at http://localhost:8000/index.html.
View the standalone assessment example
Now view the standalone assessment example at http://localhost:8000/assessment/standalone-assessment.php (or select the Standalone assessment example from the index page).
This page is a basic example of an assessment delivered by Learnosity's embeddable assessment player. You can answer the questions in this demo assessment to experience the types of Questions that can be provided.
How it works
Let's walk through the code for this standalone assessment example. The source file is included under the quickstart folder, in this location:
We start by including some LearnositySDK helpers - they'll make it easy to generate and sign the config options, and unique user and session IDs.
<?php require_once __DIR__ . '/../../../../bootstrap.php'; use LearnositySdk\Request\Init; use LearnositySdk\Utils\Uuid; $user_id = Uuid::generate(); $session_id = Uuid::generate();
Now we'll declare the configuration options for Items API. These specify which assessment content should be rendered, how it should be displayed, which user is taking this assessment and how their responses should be stored.
$request = [ 'user_id' => $user_id, 'activity_template_id' => 'quickstart_examples_activity_template_001', 'session_id' => $session_id, 'activity_id' => 'quickstart_examples_activity_001' 'rendering_type' => 'assess', 'type' => 'submit_practice', 'name' => 'Items API Quickstart', ];
user_id: unique student identifier. Note: we never send or save student's names or other personally identifiable information in these requests. The unique identifier should be used to look up the entry in a database of students accessible within your system only. Learn more.
activity_template_id: reference of the Activity to retrieve from the Item bank. The Activity defines which Items will be served in this assessment.
session_id: uniquely identifies this specific assessment attempt for save/resume, data retrieval and reporting purposes. Here, we're using the
Uuidhelper to auto-generate a unique session id.
activity_id: a string you define, used solely for analytics to allow you run reporting and compare results of users submitting the same assessment.
rendering_type: selects a rendering mode,
assessmode is a "standalone" mode (loading a complete assessment player for navigation, as opposed to
inlinefor embedding without).
type: selects the context for the student response storage.
submit_practicemode means the student responses will be stored in the Learnosity cloud, allowing for grading and review.
name: human-friendly display name to be shown in reporting, via Reports API and Data API.
Note: you can submit the configuration options either as a PHP array as shown above, or a JSON string.
Next, we declare the Learnosity consumer credentials we'll use to authorize this request. The consumer key and consumer secret in this example are for Learnosity's public "demos" account. Once Learnosity provides your own consumer credentials, your Item bank and assessment data will be tied to your own consumer key and secret.
$consumerKey = 'yis0TYCu7U9V4o7M'; $consumerSecret = '74c5fd430cf1242a527f6223aebd42d30464be22';
(of course, you should never normally check passwords into version control)
Here, we construct security settings that ensure the report is initialized on the intended domain. The value provided to the domain property must match the domain from which the file is actually served.
$security = [ 'domain' => $_SERVER['SERVER_NAME'], 'consumer_key' => $consumerKey ];
Now we call LearnositySDK's
Init() helper to construct our Items API configuration parameters, and sign them securely with the
$init->generate() returns us a JSON blob of signed configuration parameters.
$init = new Init( 'items', $security, $consumerSecret, $request); $initOptions = $init->generate(); ?>
Web page content
This example uses plain HTML on a PHP page for simplicity. The following example HTML can be found at the bottom of the
<!DOCTYPE html> <html> <head><link rel="stylesheet" type="text/css" href="../css/style.css"></head> <body> <h1>Standalone Assessment Example</h1> <div id="learnosity_assess"></div> <script src="https://items.learnosity.com/?v2022.1.LTS"></script> <script> var itemsApp = LearnosityItems.init( <?php echo $initOptions; ?> ); </script> </body> </html>
The important parts to be aware of in this HTML are:
- A div with
id="learnosity_assess". This is where the Learnosity assessment player will be rendered to deliver the assessment.
<script src="https://items.learnosity.com/?v2022.1.LTS"></script>tag, which includes Learnosity's Items API on the page and makes the global
LearnosityItemsobject available. The version specified as
v2022.1.LTSwill retrieve that specific Long Term Support (LTS) version. In production, you should always pin to a specific LTS version to ensure version compatibility.
- The call to
LearnosityItems.init(), which initiates Items API to inject the assessment player into the page.
The call to
init() returns an instance of the ItemsApp, which we can use to programmatically drive the assessment using its methods.
This marks the end of the quick start guide. From here, try modifying the example files yourself, you are welcome to use this code as a basis for your own projects.
Take a look at some more in-depth options and tutorials on using Learnosity assessment functionality below.
Next steps: additional documentation
See a more detailed breakdown of all the SDK features and examples of how to use more advanced or specialised features on the SDK reference page.
Additional quick start guides
There are more quick start guides, going beyond the initial quick start topic of loading an assessment, these further tutorials show how to set up authoring and analytics:
- Authoring Items quick start guide (Author API) - create and edit new Questions and Items for your Item bank, then group your assessment Items into Activities, and
- Analytics / student reporting quick start guide (Reports API) - view the results and scores from an assessment Activity.
Learnosity demos repository
On our demo site, browse through many examples of Learnosity API integration. You can also download the entire demo site source code, the code for any single demo, or browse the codebase directly on GitHub.
Learnosity reference documentation
See the full documentation for Learnosity API init options, methods and events on the Learnosity reference site.
Technical use-cases documentation
Find guidance on how to select a development pattern and arrange the architecture of your application with Learnosity, in the Technical Use-Cases Overview.
Deciding what to build or integrate
Get help deciding what application functionality to build yourself, or integrate off-the-shelf with the Learnosity "Golden Path" documentation.
Key Learnosity concepts
Want more general information about how apps on Learnosity actually work? Take a look at our Key Learnosity Concepts page.
Need an explanation for the unique Learnosity meanings for Item, Activity and Item bank? See our Glossary of Learnosity-specific terms.
The Learnosity PHP SDK is licensed under an Apache 2.0 license. Read more.
Our SDKs include code to track the following information by adding it to the request being signed:
- SDK version
- SDK language
- SDK language version
- Host platform (OS)
- Platform version
We use this data to enable better support and feature planning.
Thanks for reading to the end! Find more information about developing an app with Learnosity on our documentation sites:
- help.learnosity.com -- general help portal and tutorials,
- reference.learnosity.com -- developer reference site, and
- authorguide.learnosity.com -- authoring documentation for content creators.