How to Generate a Random Actor for xAPI Statements

You can use custom xAPI statements to track how people interact with your eLearning, websites, and apps, but sometimes, you don’t need to know exactly who that user is.

You may not care what their name and email address is — you only want to know whether it’s the same user who accessed the course yesterday, last week, or even last month.

This approach shows you how to generate a random username for each user that accesses your xAPI-enabled experience. The experience will then cache that username, so if the same user returns, then they have the same username.

This allows you to track an individual’s experiences across a single (or multiple) learning experiences, all while respecting their privacy and anonymity.

The approach works best for HTML experiences that are hosted on the open web. If you are hosting the learning experience on an LMS, then you should likely identify your users with their real information (which the LMS makes available to you).

Finally, if you’re viewing this tutorial, then you’re likely somewhat familiar with sending custom xAPI statements. If you are not, then you should review the How to Write an xAPI Statement tutorial before continuing here.

Write the JavaScript Code

The first thing that we need to do is write the JavaScript code that handles generating and caching the random username.

If you’re following my xAPI + Articulate Storyline tutorials, then you should put this code at the top of your xapi-statement.js file. If you are not, then you should use whatever method you’d like to execute this code whenever your course loads.

Generate the Random User

We’ll use the Math.random JavaScript method to generate a random decimal (0.576378746378…), then we’ll add 10000000 and round it down with Math.floor to make it a whole 8-digit number (57637874).

After that, add it to “user” and set that equal to a variable called courseUser.

In short, the code below creates the courseUser variable and sets it equal to “user” plus a random 8 digit number (for example, “user57637874”).

{% c-block language="js" %}
var courseUser = "user" + Math.floor(Math.random() * 89999999 + 10000000)
{% c-block-end %}

Check the Cache

Now, before we decide to use this randomly generated user as the actor in the xAPI statement, we must check our cache (or local storage) to determine whether a random username has already been generated for this user.

The code below checks the cache for the “courseRandomUsername” property. If the property is not there, then it creates a “courseRandomUsername” property in the cache and sets it equal to the random username that we generated in the previous step.

{% c-block language="js" %}
if(!("courseRandomUsername" in localStorage)) {
   localStorage.setItem("courseRandomUsername", courseUser);
}
{% c-block-end %}

Define the Variables

Now that we cache the random user (only when a username is not already cached), we can create variables that hold the actor’s name and email address. We will use these variables later to populate the xAPI statement.

First, let’s create the actor variable. This variable checks the cache for the “courseRandomUsername” property. If that property does not exist (for example, if the user has caching disabled), then it sets it equal to the courseUser variable that we created earlier.

Next, we create the actorMbox property. It adds the “mailto:” string required for xAPI statements, it adds the username, and then it adds the domain to create a fictitious email address.

You should replace “yourdomain.com” with a domain that you control. You could also use something like “example.com” to make it clear that you’re using these email addresses for testing purposes.

{% c-block language="js" %}
var actor = localStorage.getItem("courseRandomUsername") || courseUser;
var actorMbox = "mailto:" + actor + "@yourdomain.com";
{% c-block-end %}

In all, the code that you use to generate the random username, cache the username, and create the needed variables looks like this:

{% c-block language="js" %}
var courseUser = "user" + Math.floor(Math.random() * 89999999 + 10000000)

if(!("courseRandomUsername" in localStorage)) {
   localStorage.setItem("courseRandomUsername", courseUser);
}

var actor = localStorage.getItem("courseRandomUsername") || courseUser;
var actorMbox = "mailto:" + actor + "@yourdomain.com";
{% c-block-end %}

Modify the xAPI Statement Object

With the variables defined, all that’s left to do is add them to the xAPI statement object. Find the “actor” object in your xAPI statement, then:

1. Add the actor variable as the value for the “name” property.
2. Add the actorMbox variable as the value for the “mbox” property.

{% c-block language="js" %}
"actor": {
 "objectType": "Agent",
 "name": actor,
 "mbox": actorMbox
}
{% c-block-end %}

Conclusion

And that’s a wrap! By following the steps in this tutorial, you’ve effectively generated a random username, cached that username (if it’s not cached already), and populated that username in an xAPI statement.

Whenever the user returns to one of your websites or eLearning experiences with the same browser, the experience will identify them from their previous session(s). This helps you analyze individual journeys through your eLearning experiences without having to identify them via their personal information.

If you have any questions or need a hand with this tutorial, then feel free to join the ID community. Access is free for all mailing list subscribers.