Follow

Items API Quick Start Guide

Overview

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.

This quick start's server side code is written in PHP, but multiple languages are supported, such as Java, .net, Python and more.

  • Basic PHP, JavaScript and HTML knowledge.
  • A PHP-enabled web server, installed on your local machine. (To set up a simple test environment, follow our environment setup FAQ.)

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 quickstart-examples-php/www as its document root directory. We'll assume that your web server is available at http://localhost:8000.

Download Quickstart Examples.zip 

The quick start example package includes:

  • The Learnosity Software Development Kit (LearnositySDK).
  • The quick start example files.

Once set up, you can load the examples index page at http://localhost:8000/index.html.

Quickstart Examples Screenshot

Now view the 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 assess player. You can answer the questions in this demo assessment to experience the types of Questions that can be provided.

Workflow for running an Assessment

Let's look at the code for this standalone assessment example. The source file is located here and is included in the quick start examples at www/assessment/standalone-assessment.php.

The first section of code is PHP and is executed server-side. It constructs a set of configuration options for Item API, and securely signs them using the consumer key. The second section is HTML and Javascript and is executed client-side, once the page is loaded in the browser. It renders and runs the assessment functionality.

We start by including some LearnositySDK helpers - they'll make it easy to generate and sign the config options.

<?php
    require_once __DIR__ . '/../../src/vendor/autoload.php';
    use LearnositySdk\Request\Init as LearnosityInit;
    use LearnositySdk\Utils\Uuid as LearnosityUuid;

Then we declare the config 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.

  • user_id: Unique student identifier.
  • 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.
  • activity_id: Used in data retrieval and reporting to compare results with other users submitting the same assessment.
    $request = [
        'rendering_type' => 'assess',
        'type'           => 'submit_practice',
        'name'           => 'Items API Quickstart',
        'user_id'        => 'student_00012',
        'activity_template_id' => 'quickstart_examples_activity_template_001',
        'session_id'     => LearnosityUuid::generate(),
        'activity_id'    => 'quickstart_examples_activity_001'
    ];

Next, we declare the Learnosity consumer credentials we'll use to authorize this request. These keys grant access to Learnosity's public demos account. Once Learnosity provides your own consumer credentials, your Item bank and assessment data will be tied to your consumer key.

    $consumerKey = 'yis0TYCu7U9V4o7M';
    $consumerSecret = '74c5fd430cf1242a527f6223aebd42d30464be22';

We construct security settings that ensure the report is initialized on the intended domain.

    $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 $security and $consumerSecret parameters. $init->generate() returns us a JSON blob of signed config params.

    $init = new LearnosityInit(
        'items',
        $security,
        $consumerSecret,
        $request);
    $initOptions = $init->generate();
?>

We've got our set of signed configuration parameters, so now we can start outputting our page content. The page can be as simple or as complex as needed, using arbitrary HTML, JavaScript and your frameworks of choice to render the desired product experience.

This example uses a plain HTML page for simplicity, but the important parts are:

  • div with id="learnosity_assess". This is where the Learnosity assess player will be rendered to deliver the assessment.
  • The <script src="https://items.learnosity.com/"></script> tag, which includes Learnosity's Items API on the page and makes the global LearnosityItems object available.
  • The call to LearnosityItems.init(), which initiates Items API to inject the assess player into the page.
  • In our case, we use PHP to dynamically echo the contents of our signed JSON blob of $initOptions into the JavaScript so it can be passed to init().
<!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/"></script>
        <script>
            var itemsApp = LearnosityItems.init(
                <?php echo $initOptions; ?>
            );
        </script>
    </body>
</html>

The call to init() returns an instance of the ItemsApp, which we can use to programmatically drive the assessment using its methods.

From here, try modifying the example files and take a look at some more in-depth options and tutorials for using Learnosity assessment functionality.

Tutorials for assessment functionality

For lengthy discussion of assessment concepts, refer to Learnosity tutorials. Start with the Items API tutorial.

Assessment features

To learn more about the assessment feature set, see the Learnosity features page for assessment.

Assessment demos

View interactive assessment demos in the Items API demos.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments