xAPIWrapper

Wrapper to simplify communication to an LRS. Read more about the Experience API Spec here.

Check out the Reference Documentation Here

xapiwrapper.js

Javascript Experience API wrapper.
This javascript file can be included to web based xAPI clients to simplify the process of connecting and communicating to an LRS. It is enclosed in an ADL object like the ADL xAPI Verbs project, allowing a single object to contain both the ADL verbs and the ADL xapiwrapper.

This wrapper has two version identifiers within the code. One, xapiVersion is the version of the Experience API Specification for which it was built, and can be used to determine if the wrapper is compatible with an LRS implementing a specific xAPI Specification version. The second is the build date in the header of the minified file, which can be used to tell if you're using the latest version.

Dependencies

The wrapper relies on external dependencies to perform some actions. Make sure you include our compilation of the necessary CryptoJS components in your pages if you're not using xapiwrapper.min.js.

<script type="text/javascript" src="./lib/cryptojs_v3.1.2.js"></script>

In the past we used the below libraries for the same purpose. You may continue to use them for current systems, but the CryptoJS compilation is recommended.

base64.js - https://code.google.com/p/javascriptbase64/downloads/list
2.5.3-crypto-sha1.js - https://code.google.com/p/crypto-js/downloads/detail?name=2.5.3-crypto-sha1.js&can=4&q=

For IE/Edge support you will need to include a TextEncoder and TextDecoder shim if you're not using xapiwrapper.min.js

<script type="text/javascript" src="./lib/utf8-text-encoding.js"></script>

Installing

Using this wrapper could either be done by downloading the latest release or cloning the project.

Downloading the latest release version

The minified wrapper is self-contained. It includes all required dependencies in addition to the ADL Verbs and the XAPIStatement module. For production sites, this version of the wrapper is recommended.

Download the latest release

Follow the instructions for including the wrapper in your source files.

Cloning and building the project

You can optionally clone and use the dist/xapiwrapper.min.js:

git clone https://github.com/adlnet/xAPIWrapper/

Building the project

Compiling the minified version is easy. Install Node.js and NPM if you don't already have them (download them here) or

$ sudo apt-get install nodejs
$ sudo apt-get install npm

$ sudo ln -s /usr/bin/nodejs /usr/bin/node

Then install the build system, Grunt. This may require root/admin privileges on your system.

$ cd xAPIWrapper

$ sudo npm install -g grunt

Install the xAPIWrapper dependencies:

$ sudo npm install

Then execute the build script:

$ grunt

This will overwrite dist/xapiwrapper.min.js with the minifed versions of the wrapper and all its dependencies.

Including in your Software.

Include the wrapper file, and optionally the dependencies.

<script type="text/javascript" src="./lib/cryptojs_v3.1.2.js"></script>
<script type="text/javascript" src="./lib/utf8-text-encoding.js"></script>
<script type="text/javascript" src="./src/activitytypes.js"></script>
<script type="text/javascript" src="./src/verbs.js"></script>
<script type="text/javascript" src="./src/xapiwrapper.js"></script>
<script type="text/javascript" src="./src/xapistatement.js"></script>
<script type="text/javascript" src="./src/xapi-util.js"></script>
<script type="text/javascript" src="./src/xapi-launch.js"></script>

Alternatively, use the minified version:

<script type="text/javascript" src="./dist/xapiwrapper.min.js"></script>

Configuration

The wrapper at a minimum needs to know the url of the LRS, though most cases will also require the authorization information as well.

This wrapper provides two options for configuration. You may:

Edit the configuration object (Config) in the xapiwrapper.js file

var Config = function()
{
    var conf = {};
    conf['endpoint'] = "http://localhost:8000/xapi/";
    try
    {
        conf['auth'] = "Basic " + toBase64('tom:1234');
    }
    catch (e)
    {
        log("Exception in Config trying to encode auth: " + e);
    }

    // Statement defaults [optional configuration]
    // conf["actor"] = {"mbox":"default@example.com"};
    // conf["registration"] =  ruuid();
    // conf["grouping"] = {"id":"ctxact:default/grouping"};
    // conf["activity_platform"] = "default platform";

    // Behavior defaults
    // conf["strictCallbacks"] = false; // Strict error-first callbacks
    return conf
}();

Create your own configuration object and pass it to the xapiwrapper object

var conf = {
  "endpoint" : "https://lrs.adlnet.gov/xapi/",
  "auth" : "Basic " + toBase64('tom:1234'),
};
ADL.XAPIWrapper.changeConfig(conf);

Optionally, auth credentials can be updated by user and password properties on the configuration object:

var conf = {
  "endpoint" : "https://lrs.adlnet.gov/xapi/",
  "user" : "tom",
  "password" : "1234",
};
ADL.XAPIWrapper.changeConfig(conf);

var creds = {
  "user" : "tom",
  "password" : "1234",
};
ADL.XAPIWrapper.updateAuth(ADL.XAPIWrapper.lrs, creds.user, creds.password);

The script automatically runs, creating or adding to an ADL object an instantiated xAPI Wrapper object. The object is created using the configuration object inside the xapiwrapper.js file. If you modified this object with your configuration, then xAPI Wrapper object is ready to use.

ADL.XAPIWrapper.testConfig();
>> true

Launch Parameters

The configuration will also look for url query parameters and use those name - value pairs in the XAPIWrapper's internal configuration. That means that http://localhost:8000/content/example.html?actor={"mbox":"mailto:tom@example.com"}
(not url encoded for illustrative purposes) would be parsed for an actor, which would automatically be included in the wrapper configuration.
NOTE: endpoint, auth, actor, registration, activity_id, grouping, and activity_platform are keywords that if found are used in send statement requests. See below for usage examples.

Logging

The wrapper comes with a logging function (ADL.XAPIWrapper.log(message)) which attempts to write a message to console.log. This can be configured to not write messages by setting log.debug = false;.

xAPI Launch support

The xAPI Wrapper supports ADL's xAPI Launch. This allows configuration - agent info, lrs endpoint info - to be sent to the wrapper, instead of using hard-coded configurations. See Using the xAPI-Launch library for more details.

If you are using the src files, include xapi-launch.js.

<script type="text/javascript" src="./lib/cryptojs_v3.1.2.js"></script>
<script type="text/javascript" src="./lib/utf8-text-encoding.js"></script>
<script type="text/javascript" src="./src/activitytypes.js"></script>
<script type="text/javascript" src="./src/verbs.js"></script>
<script type="text/javascript" src="./src/xapiwrapper.js"></script>
<script type="text/javascript" src="./src/xapistatement.js"></script>
<script type="text/javascript" src="./src/xapi-util.js"></script>
<script type="text/javascript" src="./src/xapi-launch.js"></script>

Alternatively, use the minified xapiwrapper version, which includes xapi-launch:

<script type="text/javascript" src="./dist/xapiwrapper.min.js"></script>

To use, construct and ADL.launch object passing in a callback.

var wrapper;
ADL.launch(function(err, launchdata, xAPIWrapper) {
    if (!err) {
        wrapper = xAPIWrapper;
        console.log("--- content launched via xAPI Launch ---\n", wrapper.lrs, "\n", launchdata);
    } else {
        wrapper = ADL.XAPIWrapper;
        wrapper.changeConfig({
            endpoint: "https://lrs.adlnet.gov/xapi/",
            user: 'tom',
            password: '1234'
        });
        console.log("--- content statically configured ---\n", wrapper.lrs);
    }
    $('#endpoint').text(wrapper.lrs.endpoint);
}, true);

Use

Statements

Statement Object (xapistatement.js)

new ADL.XAPIStatement(actor, verb, object)
new ADL.XAPIStatement.Agent(identifier, name)
new ADL.XAPIStatement.Group(identifier, members, name)
new ADL.XAPIStatement.Verb(id, description)
new ADL.XAPIStatement.Activity(id, name, description)
new ADL.XAPIStatement.StatementRef(uuid)
new ADL.XAPIStatement.SubStatement(actor, verb, object)

This sub-API makes it easier to author valid xAPI statements by adding constructors and encouraging best practices. All objects in this API are fully JSON-compatible, so anything expecting an xAPI statement can take an improved statement and vice versa.

In addition to the above forms, each constructor can instead take as an argument another instance of the object or the equivalent plain object. So you can convert a plain xAPI statement to an improved one by calling new XAPIStatement(plain_obj).

Building a Simple "I Did This"

Passing in strings produces a default form:

XAPIWrapper

Install / Use

README