Get Started with xAPI, Part Two: How To Gather xAPI Learning Information

The Getting Started with xAPI in Storyline Tutorial Series, by Devlin Peck @devpeck, was originally published at devlinpeck.com. Check out Devlin at the LMSPulse Elearning Success Summit 2020.

In this tutorial, you’ll learn how to populate an xAPI statement with the learner’s name and email address, collected from a Storyline course. This let’s you tie learning data to a specific person, which is much better than tying it to a random name and email address. For example, this method allows you to track one person’s learning experience across multiple courses using their email address as a unique ID.

You do not need any coding knowledge coming into this tutorial. However, you should have completed Part 1 of this tutorial series before beginning this one, as you will be building on the file that you created during Part 1.

In this tutorial, you will:

1. Set up your Storyline xAPI project
2. Collect user input in JavaScript variables
3. Format the variables in xAPI format

Go grab the xapi-statement.js file from last time and let’s get started!

Set up your Storyline xAPI project

First, you need to program your Storyline file to collect user information using text inputs. To add a text input field in Storyline, complete the following steps:

1. Select the “Insert” tab in Storyline
2. Select the “Input” icon
3. Select “Text Entry Field” under the “Data Entry” subheading
4. Click and drag on the Storyline canvas to create the text input field

Don’t forget to label each field! You can also add a “Submit” button that brings the user to the next slide when they select it.

After creating a text input for the name and email fields, you’ll want to change the variable names to something more appropriate. Change the variable associated with the user’s name to “uName“, and change the variable associated with the user’s email address to “uEmail“. You can name these whatever you’d like, but you will need to re-write it exactly letter-for-letter in a future step. Note: these variables are case sensitive.

To change a Storyline variable’s name:

To see which variable is associated with which text input box, you can select the text input box on the Storyline slide then look at its trigger in the sidebar. If each text input box is labeled correctly and associated with the correct variable, then you’re ready to move on!

Important note: If data security is a concern, then it is best practice to validate your form data. This ensures that users cannot enter malicious code through the input field, and it also guarantees that the user-entered data is in the correct format to be read by the Learning Record Store (LRS) when it’s time to send the statement. Read more about validating email addresses here.

Collect user input in JavaScript variables

We need to use a few lines of JavaScipt to connect your Storyline text input variables to your xAPI statement. If you’re not familiar with JavaScript, don’t worry. We will take it piece by piece, just as we did in Part 1, to ensure that you understand the code you’re using.

Find and open the xapi-statement.js file that we created in Part 1 in your text editor of choice. Create a few line breaks above the opening curly bracket {, as we will not be modifying the xAPI JSON object yet. The first line of code you want to add is:

const player = GetPlayer();

The “const” keyword tells the computer that we are about to create a new, non-changing JavaScript variable, in this case titled “player”.

A note about the “const” keyword: In 2015, JavaScript was updated to define variables in two new ways. Namely, using the keywords “const” and “let.” You use const, short for constant, when you do not plan on changing your variable, and you use “let” when you expect to change your variable’s value at a later point in the code. You may also see the “var” keyword used to define variables in JavaScript. This syntax is now outdated and unnecessary, but using “var” instead of “const” will not break your code. Just remember, use “const” when you’re defining a variable that you do not plan on changing.

On the right side of the equal sign, we set the variable equal to a JavaScript function that targets your Storyline course (this function is defined by the Articulate developers). The semicolon tells the computer that the line of code is complete.

Now, due to the nature of JavaScript variables, you can access your Storyline course using JavaScript just by typing “player”.

We’ll make use of this in our next line of code:

const player = GetPlayer();
const uNamejs = player.GetVar("uName");

With this line of code, we create a new JavaScript variable titled “uNamejs”. On the right side of the equal sign, we first call on the Storyline course using the “player” variable, then we use another built-in Storyline function, “GetVar().” This function essentially gets the variable from the Storyline course (get it? GetVar). If we put the Storyline variable that we’d like to call within the GetVar() parenthesis (enclosed by quotation marks), then the JavaScript code effectively pulls the value of the Storyline variable.

Duplicate this line of code and modify it accordingly to set a new JavaScript variable, “uEmailjs”, to the value of the “uEmail” Storyline variable. Your code should now look like this:

const player = GetPlayer();
const uNamejs = player.GetVar("uName");
const uEmailjs = player.GetVar("uEmail");

Important note: Don’t forget the semicolons after each line of code, and remember that JavaScript is case sensitive!

Format the variables in xAPI format

Now it’s time to update the xAPI statement itself so that it includes the user’s name and email address. To do this, look at the Actor object, specifically. Change the “name” property’s value to uNamejs and the “mbox” property’s value to uEmailjs. You will need to add "mailto:" + before the uEmailjs variable, to indicate the LRS that it’s dealing with an email address. Also note that you do not put quotation marks around JavaScript variables, only around strings.

If you updated the code successfully, then your entire xapi-statement.js file should look like this:

const player = GetPlayer();
const uNamejs = player.GetVar("uName");
const uEmailjs = player.GetVar("uEmail");

{
  "actor": {
    "name": uNamejs,
    "mbox": "mailto:" + uEmailjs 
  },
  "verb": {
    "id":"http://activitystrea.ms/schema/1.0/complete",
    "display": { "en-US": "completed" }
  },
  "object": {
    "id": "http://www.devlinpeck.com/write-xapi-statement",
    "definition": {
      "name": { "en-US": "Write xAPI Statement Tutorial" }
    }
  }	
}

If your file has each of these elements (with the correct capitalization and punctuation), then you’re good to go. If you were to send this statement to an LRS, it would include whatever (valid) name and email address the user entered in the Storyline course.

Next steps

You’re oh-so-close to sending xAPI Statements — and not just any xAPI Statements, but xAPI statements that are tied to a specific user.

If you’re experiencing any technical difficulties, feel free to check out Devlin’s common xAPI and Storyline troubleshooting steps. You can also contact him if you’d like to hire me to help with your xAPI implementation project.