Using the Learnosity SDK
The first step in interacting with any Learnosity API is to authenticate the client and securely sign the API server request. This ensures that a valid client is accessing the API, and also protects the data from outside manipulation. In short, this security allows both Learnosity and our customers to know that no data has been changed en route between client and server.
To simplify the security process, Learnosity offers an easy to use SDK to handle the signing of each server request. The SDK is available in a number of languages, and these tutorials will use the PHP version.
If you want to build this tutorial from scratch, download the SDK of your choice, rename the folder “learnosity-sdk” and place it into a parent directory you plan to use for these files. If you prefer to just follow along, you can download the completed tutorial files. Once you're ready to begin, we’ll cover the minimum code required for secure signing, and tuck these tasks into a config file for efficient reuse.
The Config File
Lines 3 and 4 of config.php start things off with the consumer key and consumer secret—two components of customer credentials supplied by Learnosity. The consumer key is a public key, and the consumer secret is a private key known only by the client and Learnosity. The consumer secret should never be exposed by sending it to the browser or across the network such as in email or a support ticket.
Note: This tutorial uses demo values for the consumer key and secret. In production, you must use your own consumer key and secret.
Code example 1: code for secure signing in config.php
1 <?php 2 3 $consumer_key = "yis0TYCu7U9V4o7M"; 4 $consumer_secret = "74c5fd430cf1242a527f6223aebd42d30464be22"; 5 6 $domain = $_SERVER["SERVER_NAME"]; 7 8 $security = array( 9 "consumer_key" => $consumer_key, 10 "domain" => $domain 11 ); 12 13 include_once "learnosity-sdk/src/LearnositySdk/autoload.php"; 14 15 ?>
location.hostnameof the client system and, during the authentication process, the server will check to make sure that each domain is one of the customer’s authorized domains. For testing purposes, “localhost” will always work.
Lines 8 through 11 create the security object, including the consumer key, and domain. Immediately prior to initializing an API, the SDK will use the SHA256 hashing algorithm to combine all of these values, along with the request object we’ll discuss in a moment, to create a signature. Learnosity will perform the same operation on the server side, and the signatures must match to proceed.
The last line of the config file, line 13, references an autoloader to simplify including dependencies and reduce related errors. The autoloader will attempt to load any class or interface which hasn't yet been defined, before throwing an error.
Using Config and Autoloader
Now that the config file is complete, we can include it at the top of the main tutorial file, tutorial_102.php. We’ll also create aliases, in lines 5 and 6, to the SDK’s
Uuid classes, preventing the need to use their fully qualified paths.
1 <?php 2 3 include_once 'config.php'; 4 5 use LearnositySdk\Request\Init; 6 use LearnositySdk\Utils\Uuid
Code example 2: creating aliases for the Init and Uuid classes.
Building the Assessment
Now that we’ve got the security out of the way, we’re ready to create the request object, which includes student and session information, and the items that will be displayed in the assessment, and properties that control the assessment’s appearance and behavior.
The student ID shown in line 9 links a student to submitted results. It’s typically the same student ID as used in the host system but can be anything you choose, as long as it's unique. Similarly, a unique session ID allows reports to be run on a specific session that any student may have submitted. This session ID value should be stored by the customer so it can be used when requesting reports in the future. For this tutorial, a unique session id is generated by the SDK’s
Uuid class in line 10.
8 $request = array( 9 "user_id" => "student_1234", 10 "session_id" => Uuid::generate(), 11 "items" => array("Tut002_Item1", "Tut002_Item2", "Tut002_Item3"), 12 "rendering_type" => "inline", 13 "type" => "local_practice" 14 );
As stated in our security policy, Personal Identifiable Information should not be used as a
user_id. We recommend using a hashing function (e.g. SHA256, bcrypt etc) to generate a unique identifier (and, optionally, prepending a user type such as 'student', 'teacher' or 'admin'). Identifiers such as 'firstname.surname', or email addresses should not be used as user_ids.
Line 11 holds the array of items displayed. Line 12 specifies the rendering type of the assessment. Items can be rendered into DOM elements that match the names of the item references, allowing the customer full control over placement (“inline”), or can be collected into a single DOM element, complete with navigation (“assess”). The request object and accompanying HTML in this segment of this tutorial will be rendered inline. In a few moments, we’ll look at the collected, or assess, rendering method.
Line 13 sets the items. By default, no state has to be defined. At different stages of the assessment process, other states may be “preview” (to audition an item, for example) or “review” (after validation). Finally, line 14 sets the assessment type as a “local_practice” type. This is ideal for questions that have been configured with a Check Answers button. Local practice allows the student to see validated results locally without submitting to the server. Using “submit_practice” will instead submit the assessment to the server, typically without using the Check Answers feature, leaving the decisions if, when, and how session reports are shown to the host environment.Note If you plan to use specific questions in multiple contexts, using the Author site to add a Check Answers button at the question level increases flexibility. You can use the feature for instant feedback, or suppress it for submitted graded assessments. We'll look at both options in this tutorial.
Signing the Request
The final step in the security and authentication process is to initialize and sign the request. The SDK’s
Init class in line 30 accepts the array of items to be shown in the assessment, the security object, the consumer secret, and the request object as parameters. The
Note: We’ve left a gap in line numbers simply to make the numbering consistent across multiple examples in this tutorial.
30 $Init = new Init("items", $security, $consumer_secret, $request); 31 $signedRequest = $Init->generate(); 32 33 ?>
Code example 4: initializing and signing the request.
This wraps up the PHP required, and next we need to create a minimal HTML page to display the assessment.
Creating the Host Page
The following block of HTML shows a basic page skeleton, but the most important thing to note are the
<span> elements in lines 44-46. The
data-reference attributes contain the item reference for each item displayed. The customer is in complete control of the layout of the assessment. While it’s not typically a best practice to use inline styles, line 42 of this stripped down example demonstrates, in an unobtrusive way, that items will automatically fill their containers.
35 <!DOCTYPE html> 36 <html lang="en"> 37 <head> 38 <meta charset="utf-8"> 39 <title>How Color Works</title> 40 </head> 41 <body> 42 <div style="width:750px;"> 43 <h3 class="item-title">The Color Wheel</h3> 44 <span class="learnosity-item" data-reference="Tut002_Item1"></span> 45 <span class="learnosity-item" data-reference="Tut002_Item2"></span> 46 <span class="learnosity-item" data-reference="Tut002_Item3"></span> 47 48 </div>
50 <script src="//items.learnosity.com?[VERSION]"></script> 51 <script> 52 var itemsApp = LearnosityItems.init(<?php echo $signedRequest; ?>); 53 </script> 54 </body> 55 </html>
The Rendered Assessment
The output of this tutorial is a simple HTML page with three questions rendered inline. Each question was configured with a Check Answer button for immediate feedback, and the assessment operates in local practice mode. This can be useful for sample questions preceding graded material, study questions, or classroom discussion.
Figure 1: Using rendering_type "inline".
We’ll now modify this example in a couple of simple ways to show the flexibility of the Items API. Multiple source files have been included in the downloadable archive to represent each of these options.
Submitting the Assessment
The first change we’ll look at is enabling the assessment to submit results so reports can be run on the session at a later time. To do this, we need to make a few changes to the request object, and HTML page.
In the PHP portion of the code, we need to use the “submit_practice” type (instead of “local_practice”) in the request object, and add a configuration object to render a submit button and suppress instant feedback. We also need two additional properties to submit activities.
- activity_id: This is a unique reference to the activity, and should be the same for all students submitting results from this activity. It is used for reporting and comparison.
- name: This is a descriptive name for this activity which is displayed in reports.
Note: An activity is the assessment delivered to the student and can be created dynamically, as in this tutorial, or in the Learnosity Author site.
Lines 14 through 23 in the edited request object address the changes described above. In particular, lines 18 through 20 cover the
config option. Line 19 will render a submit button into the HTML DOM element we'll create in a moment, and lines 20 through 22 will suppress the instant feedback provided via the question-level Check Answers button.
8 $request = array( 9 'user_id' => 'student_1234', 10 'session_id' => Uuid::generate(), 11 'items' => array('Tut002_Item1', 'Tut002_Item2', 'Tut002_Item3'), 12 'rendering_type' => ‘inline’, 14 'type' => 'submit_practice', 15 'activity_id' => 'demo_activity', 16 'name' => 'The Color Wheel', 17 'config' => array( 18 'renderSubmitButton' => true, 19 "ignore_question_attributes" => array( 20 "instant_feedback" 21 ) 22 ) 23 );
Code example 7: adding an element for a submit button.
Rendering Using Assess
The second option we’ll look at is rendering all the items in a single DOM element, complete with navigation. This is accomplished by using the Learnosity Assess API to render the items, and requires a few changes to the request object and host HTML. We’ll look at using the assess rendering style for both local practice and submit practice use.
Changing the Request Object for Local Practice
The first change we need to make is to switch the assessment rendering type from “inline” to “assess” in line 12 of the request object. We’ll also apply two settings to the configuration of the Assess API, which is responsible for the rendering in assess mode. In line 16, we’ll use the “horizontal” UI style to place the navigation bar at the bottom of the assessment. This allows the items to fill more horizontal space in the container. And, because this is local practice, we’ll tell the Assess API not to render a submit button at the end of the assessment. We do this via the navigation object in lines 17 through 19. Additional documentation about the Assess API configuration and navigation features are available in the Assess API initialization options section of the Learnosity documentation site.
8 $request = [ 9 'user_id' => 'student_1234', 10 'session_id' => Uuid::generate(), 11 'items' => ['Tut002_Item1', 'Tut002_Item2', 'Tut002_Item3'], 12 'rendering_type' => 'assess', 14 'type' => 'local_practice', 15 'config' => [ 16 'ui_style' => 'horizontal', 17 'navigation' => [ 18 'show_submit' => false 19 ] 20 ] 21 ];
Changing the Page Markup
The change required in the HTML is actually a simplification. We just need to remove the item-specific DOM elements and replace them with one DOM element for the assess engine. This element must be a
<div> with the ID “learnosity_assess”.
42 <div style="width:750px;"> 43 <h3 class="item-title">The Color Wheel</h3> 44 <div id="learnosity_assess"></div> 45 46 47 48 </div>
Code example 9: replacing item-specific DOM elements with one DOM element for the assess engine.
Changing the Request Object for Submit Practice
Using the assess rendering type for submit practice requires no further changes to the HTML, but a few changes to the PHP request object. As with inline submit practice, we need to update the
type, and add the
name properties, in lines 14-16.
falsefor this value, and the Close button will do nothing.
8 $request = [ 9 'user_id' => 'student_1234', 10 'session_id' => Uuid::generate(), 11 'items' => ['Tut002_Item 1', 'Tut002_Item2', 'Tut002_Item3'], 12 'rendering_type' => 'assess', 14 'type' => 'submit_practice', 15 'activity_id' => 'demo_activity', 16 'name' => 'The Color Wheel', 17 'config' => [ 18 'ui_style' => 'horizontal', 19 'ignore_question_attributes' => [ 20 'instant_feedback' 21 ], 22 'configuration' => [ 23 'onsubmit_redirect_url' => 'index.html' 24 ] 25 ] 26 ];
The assess engine renders the items one at a time, with a navigation bar to allow students to move forward and (optionally) backward through the assessment.
Figure 2: Using rendering_type "assess".
What you learned
In this tutorial we learned how to create a basic assessment using Learnosity's Items API. We learned how to render the assessment in a single, navigable engine, as well as in item-specific containers for maximum control over page design. We also learned how to create an assessment that could be used for low stakes study, or submit to a server for scoring and reporting. Additional tasks are available for review in the Additional Resources section of this tutorial, including how to listen for an assessment’s Ready event, and how to add a save button.
Where to Next?
Up next in Displaying a Session Detail Report, we’ll discuss how to run reports on submitted results.