How to Collect a User's Name & Email from a Storyline Course

‍Welcome back to the Getting Started with xAPI Tutorial Series

• Part 1: Write an xAPI Statement from Scratch
• Part 2: Collect a User's Name and Email from a Storyline Course (You are here)
• Part 3: Send an xAPI Statement from a Storyline Course

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.

Feel free to ask for help in the eLearning Development space in the ID community (free for mailing list subscribers).

Setting Up Your Storyline Project

First, you need to program your Storyline file to collect the user's name and email address 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. These variables are case sensitive.

To change a Storyline variable's name, complete the following steps:

1. Open the variable manager
2. Select the variable whose name you'd like to change
3. Select the "Edit" icon
4. Type a new name for the variable
5. Select the blue "OK" button

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 LRS when it's time to send the statement. Read more about validating email addresses here.

Assigning your Storyline Variables to 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.

First, open up 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:

{% c-block language="js" %}
const player = GetPlayer();
{% c-block-end %}

The "const" keyword tells the computer that we are about to create a new, nonchanging 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.

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, as follows:

{% c-block language="js" %}
const uNamejs = player.GetVar("uName");
{% c-block-end %}

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:

{% c-block language="js" %}
const player = GetPlayer();
const uNamejs = player.GetVar("uName");
const uEmailjs = player.GetVar("uEmail");
{% c-block-end %}

Important note: Remember that JavaScript is case sensitive!

Modifying the xAPI statement

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 also need to add '"mailto" +' before the uEmailjs variable. This tells the LRS that it's dealing with an email address. Also note that you do not put quotation marks around JavaScript variables (you only put quotation marks around strings).

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

{% c-block language="js" %}
const player = GetPlayer();
const uNamejs = player.GetVar("uName");
const uEmailjs = player.GetVar("uEmail");

{
"actor": {
  "name": uNamejs,
  "mbox": "mailto:" + uEmailjs
},
"verb": {
  "id":"http://adlnet.gov/expapi/verbs/completed",
  "display": { "en-US": "completed" }
},
"object": {
  "id": "https://www.devlinpeck.com/tutorials/write-xapi-statement",
  "definition": {
    "name": { "en-US": "Write xAPI Statement Tutorial" }
  }
}
}
{% c-block-end %}

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 from Storyline - and not just any xAPI Statements, but xAPI statements that are tied to a specific user. In the third and final part of this tutorial series, you will learn how to take the final steps necessary to send custom xAPI statements from a Storyline course.