<commit_before>xAPIWrapper
===========

Wrapper to simplify communication to an LRS. [Read more about the Experience API Spec here.](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md)

Check out the [Reference Documentation Here](http://adlnet.github.io/xAPIWrapper/)

### 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](https://github.com/adlnet/xAPIVerbs), 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](https://code.google.com/p/crypto-js/) components
in your pages if you're not using `xapiwrapper.min.js`

``` html
<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=

## Installing

Using this wrapper could either be done by downloading the [latest release](https://github.com/adlnet/xAPIWrapper#downloading-the-latest-release-version) or [cloning the project](https://github.com/adlnet/xAPIWrapper#cloning-and-building-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](https://github.com/adlnet/xAPIWrapper/releases)

Follow the [instructions](https://github.com/adlnet/xAPIWrapper#including-in-your-software) for including the wrapper in your source files.

### Cloning and building the project

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

```bash
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](http://nodejs.org/download/)). Then install the build system, Grunt. This
may require root/admin privileges on your system.

```bash
$ sudo npm install -g grunt
```

Install the xAPIWrapper dependencies:

```bash
$ npm install
```

Then execute the build script:

```bash
$ 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.

``` html
<script type="text/javascript" src="./lib/cryptojs_v3.1.2.js"></script>
<script type="text/javascript" src="./src/verbs.js"></script>
<script type="text/javascript" src="./src/xapistatement.js"></script>
<script type="text/javascript" src="./src/xapiwrapper.js"></script>
```

Alternatively, use the minified version:

``` html
<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

```JavaScript
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":"<EMAIL>"};
    // conf["registration"] =  ruuid();
    // conf["grouping"] = {"id":"ctxact:default/grouping"};
    // conf["activity_platform"] = "default platform";
    return conf
}();
```  
* Create your own configuration object and pass it to the xapiwrapper object

```JavaScript
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:  

```JavaScript
var conf = {
  "endpoint" : "https://lrs.adlnet.gov/xapi/",
  "user" : "tom",
  "password" : "<PASSWORD>",
};
ADL.XAPIWrapper.changeConfig(conf);
```  
or  

```JavaScript
var creds = {
  "user" : "tom",
  "password" : "<PASSWORD>",
};
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.

``` shell
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:<EMAIL>"}`  
(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 now supports [ADL's xAPI Launch](https://github.com/adlnet/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](https://github.com/adlnet/xapi-launch#using-the-xapi-launch-library) for
more details.  

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

``` html
<script type="text/javascript" src="./lib/cryptojs_v3.1.2.js"></script>
<script type="text/javascript" src="./src/verbs.js"></script>
<script type="text/javascript" src="./src/xapistatement.js"></script>
<script type="text/javascript" src="./src/xapiwrapper.js"></script>
```

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

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

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

``` javascript
var wrapper;
ADL.launch(function(err, launchdata, xAPIWrapper) {
    if (!err) {
        wrapper = xAPIWrapper;
        console.log("--- content launched via xAPI Launch ---\n", wrapper.lrs, "\n", launchdata);<commit_msg>whoops, actually adding xapi-launch <script><commit_after>xAPIWrapper
===========

Wrapper to simplify communication to an LRS. [Read more about the Experience API Spec here.](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md)

Check out the [Reference Documentation Here](http://adlnet.github.io/xAPIWrapper/)

### 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](https://github.com/adlnet/xAPIVerbs), 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](https://code.google.com/p/crypto-js/) components
in your pages if you're not using `xapiwrapper.min.js`

``` html
<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=

## Installing

Using this wrapper could either be done by downloading the [latest release](https://github.com/adlnet/xAPIWrapper#downloading-the-latest-release-version) or [cloning the project](https://github.com/adlnet/xAPIWrapper#cloning-and-building-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](https://github.com/adlnet/xAPIWrapper/releases)

Follow the [instructions](https://github.com/adlnet/xAPIWrapper#including-in-your-software) for including the wrapper in your source files.

### Cloning and building the project

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

```bash
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](http://nodejs.org/download/)). Then install the build system, Grunt. This
may require root/admin privileges on your system.

```bash
$ sudo npm install -g grunt
```

Install the xAPIWrapper dependencies:

```bash
$ npm install
```

Then execute the build script:

```bash
$ 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.

``` html
<script type="text/javascript" src="./lib/cryptojs_v3.1.2.js"></script>
<script type="text/javascript" src="./src/verbs.js"></script>
<script type="text/javascript" src="./src/xapistatement.js"></script>
<script type="text/javascript" src="./src/xapiwrapper.js"></script>
```

Alternatively, use the minified version:

``` html
<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

```JavaScript
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":"<EMAIL>"};
    // conf["registration"] =  ruuid();
    // conf["grouping"] = {"id":"ctxact:default/grouping"};
    // conf["activity_platform"] = "default platform";
    return conf
}();
```  
* Create your own configuration object and pass it to the xapiwrapper object

```JavaScript
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:  

```JavaScript
var conf = {
  "endpoint" : "https://lrs.adlnet.gov/xapi/",
  "user" : "tom",
  "password" : "<PASSWORD>",
};
ADL.XAPIWrapper.changeConfig(conf);
```  
or  

```JavaScript
var creds = {
  "user" : "tom",
  "password" : "<PASSWORD>",
};
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.

``` shell
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:<EMAIL>"}`  
(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 now supports [ADL's xAPI Launch](https://github.com/adlnet/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](https://github.com/adlnet/xapi-launch#using-the-xapi-launch-library) for
more details.  

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

``` html
<script type="text/javascript" src="./lib/cryptojs_v3.1.2.js"></script>
<script type="text/javascript" src="./src/verbs.js"></script>
<script type="text/javascript" src="./src/xapi-launch.js"></script>
<script type="text/javascript" src="./src/xapistatement.js"></script>
<script type="text/javascript" src="./src/xapiwrapper.js"></script>
```

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

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

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

``` javascript
var wrapper;
ADL.launch(function(err, launchdata, xAPIWrapper) {
    if (!err) {
        wrapper = xAPIWrapper;
        console.log("--- content launched via xAPI Launch ---\n", wrapper.lrs, "\n", launchdata);
{'fraction_non_alphanumeric': 0.12229458588250773, 'fraction_numerical': 0.005525952239984212, 'mean_word_length': 4.472282217422606, 'pattern_counts': {'":': 6, '<': 58, '<?xml version=': 0, '>': 62, 'https://': 28, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 16, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7669959', 'n_tokens_mistral': 4612, 'n_tokens_neox': 4377, 'n_words': 1580}