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.
If you want to learn how to take full advantage of xAPI in Articulate Storyline, then you’re in the right place.
Essentially, this resource can serve as your personal learning path towards competency. No prior coding knowledge is required, and you do not need to be a Storyline expert.
After completing all of these tutorials, you should feel much more comfortable with JavaScript, JSON objects, and xAPI Statements.
Most importantly, you will have the power to collect rich data about how your learners are experiencing your elearning courses and performing on your assessments.
Let’s get started!
How to write an xAPI Statement from scratch
In this tutorial, you’ll learn how to create an xAPI statement from start to finish.
Many people jump into xAPI by copying and pasting pre-made code, but writing the statement yourself, step-by-step, provides a great foundation for future application. Therefore, to get the most out of this tutorial, I encourage you not to copy or paste any of the code enclosed. Write it yourself!
You do not need any coding knowledge coming into this tutorial. However, you will need a text editor. Pick a free, Open Source one here or here.
Create the Statement Framework
At its core, an xAPI statement is coded in JSON, a flexible and widely accepted object notation syntax. This means that to create an xAPI statement from scratch, you’re going to need to know how to create a JSON object. If you don’t have coding experience, don’t worry! JSON is super human-readable and easy to understand.
First thing’s first – open a new file in your text editor of choice and save it as “xapi-statement.js“. Inside your new .js file, create a JSON object by typing a curly bracket {, skipping a line, and closing the curly bracket }. It should look like this:
{
}Voila! You’ve officially created a JSON object. Now we’re going to need to populate it.
If you’ve spent time researching xAPI, then you probably know that a statement includes an Actor, a Verb, and an Object. Statements can include other properties, but these three are essential.
A JSON object holds multiple “Key / Value pairs.” You can think of the keys as words, like in a dictionary, and the values as their definitions.
So, let’s add the most important “Keys”: Actor, Verb, and Object. First, you type the name of the property in quotation marks, add a colon right after that, then define the property. If there is more than one property, you add a comma between each one.
Since we don’t yet know how to define each property, we will leave the values blank. Your code should now look like this:
{
"actor": ,
"verb": ,
"object":
}If you’re not familiar with code, this is where things start to look a bit more complex. The properties of your JSON object can contain objects of their own. When it comes to xAPI statements, the actor, verb, and object properties are defined by objects. Using what you’ve learned about creating JSON objects, update your code accordingly.
{
"actor": {
},
"verb": {
},
"object": {
}
}Great! With this framework in place, you’re ready to begin defining each property by adding keys and values. We’ll take it one property at a time.
Define the ‘Actor’
The “Actor” value tells us who is completing the action. It consists of an object with two keys (or properties): “name” and “mbox“. As you can imagine, the “name” property is paired with the user’s name, and the “mbox” property is paired with the user’s email address. For now, you can include any name or email address that you’d like.
Important note: Since we’re adding strings as values, we need to put quotation marks around them. If we were using a number or variable instead, we would not put quotation marks around the values.
Another important note: When adding an email address, you need to add “mailto:” to the beginning of it. This tells the LRS what type of data it’s dealing with.
Your code should now look like this:
{
"actor": {
"name": "Devlin",
"mbox": "mailto:[email protected]"
},
"verb": {
},
"object": {
}
}Excellent work! Now we’re ready to move on to the verb object’s properties.
Define the ‘Verb’
The “Verb” value consists of an object with two keys: “id” and “display“. This tells us what action the learner is performing.
The id‘s value is a Unique or Uniform Resource Identifier (URI), usually a URL (a type or URI) that others can access to learn about the verb you chose. I recommend using the ADL xAPI Vocab Server or the xAPI Registry (Proprietary) to find the URI for your preferred verb.
Important note: You can use any URL that you’d like for the Verb id, but it is not recommended that you do so. For example, many people use “http://www.example.com/nameOfVerb“, which does not bring you to a real, public-facing website.
Feel free to choose whichever verb you’d like, but for the purpose of this tutorial we will use “completed.” The URI for this verb is: “https://w3id.org/xapi/dod-isd/verbs/completed“. Therefore, you can add it to the id of your Verb object:
{
"actor": {
"name": "Devlin",
"mbox": "mailto:[email protected]"
},
"verb": {
"id":"https://w3id.org/xapi/dod-isd/verbs/completed"
},
"object": {
}
}The second property of the verb object is display. This is where you include the verb in a simple, human-readable format. However, this property includes its own key / value pair to make it clear what language the verb is in. The key is the Language Code, and the value is the name of the verb. If your application is in American English, you should add the "en-us" key and the corresponding word in the language:
{
"actor": {
"name": "Devlin",
"mbox": "mailto:[email protected]"
},
"verb": {
"id":"https://w3id.org/xapi/dod-isd/verbs/completed",
"display": { "en-US": "completed" }
},
"object": {
}
}And that’s it for defining the verb! Make sure that you remembered to add a comma after defining the Verb id.
Perfect! All we have left to do is define the Object property.
Define the ‘Object’
The Object value consists of two core properties: id and definition. Most often, the Object includes information about the activity that the user is completing.
Similar to the “id” of the verb, the id of the object is a URI. You can use your own domain, but ensure that you use a different URI for each unique activity. For example, if we want to refer to this tutorial as the object, we can use its URL: "http://www.devlinpeck.com/write-xapi-statement". Again, the URI does not have to lead to a public-facing webpage. We can use “http://www.devlin.com/xapi-statement-tutorial” if we’d like, but the key is to keep it consistent and unique. You can also use the Activity Types from the xAPI Vocab Server.
The Object definition value includes another object called “name“. Similar to the “display” property of the Verb object, the name property includes a language code as the key and a human-readable word or phrase for the activity as a value. In all, the object property looks like this:
"object": {
"id": "http://www.devlinpeck.com/write-xapi-statement",
"definition": {
"name": { "en-US": "Write xAPI Statement Tutorial" }
}
}Ta da! Once you’ve added these pieces to the statement, it’s ready to fire. You can save your file and congratulate yourself on a job well done. If you’d like to see the statement in all its glory, I’ve included it below:
{
"actor": {
"name": "Devlin",
"mbox": "mailto:[email protected]"
},
"verb": {
"id":"https://w3id.org/xapi/dod-isd/verbs/completed",
"display": { "en-US": "completed" }
},
"object": {
"id": "http://www.devlinpeck.com/write-xapi-statement",
"definition": {
"name": { "en-US": "Write xAPI Statement Tutorial" }
}
}
}Next steps
On its own, a static statement like this doesn’t do much. However, if you’ve followed along with this tutorial and wrote your own statement, then you’re in an excellent position to dive deeper into xAPI. Part Two in this series teaches you how to collect the user’s name and email address from a Storyline course to populate your statement.
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.
2 Responses