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

Welcome back to the Getting Started with xAPI Tutorial Series

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.

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

Select variable manager in the sidebar

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.

Name and email text inputs in Storyline

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 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. Hint: these variables are case sensitive.

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

  1. Open to 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

Select variable manager in the sidebar

Change a variable's name in Storyline

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!

Storyline text input field associated with correct trigger

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:

var player = GetPlayer();

The "var" keyword tells the computer that we are about to create a new JavaScript variable, in this case titled "player". We then 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:

var 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:

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

Important note: Don't forget the semicolons after each line of code, and 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. However, you will 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 (only strings).

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

var player = GetPlayer();
var uNamejs = player.GetVar("uName");
var 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 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.

Leave any questions or feedback in the comments below, and please share this tutorial on Twitter or LinkedIn to help spread the xAPI love.