Devlin Peck
Welcome to the Getting Started with xAPI Tutorial Series.
In this tutorial, you'll learn how to write 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, you should not copy or paste any of the code enclosed (instead, write it yourself!).
You do not need any coding knowledge coming into this tutorial. However, you will need a text editor, such as Sublime Text or Notepad++.
Feel free to ask for help in the ID Community (free for mailing list subscribers).
At its core, an xAPI statement is a JSON object (JSON = JavaScript Object Notation). 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".
With your new .js file open, create a JSON object by typing a curly bracket {, skipping a line, and closing the curly bracket }. It should look like this:
{% c-block language="js" %}
{
}
{% c-block-end %}
Voila! You've officially created the framework for a JSON object. Now we're going to need to populate it with something. If you've spent time researching xAPI, then you probably know that a statement includes an Actor, Verb, and Object. A statement can include other properties, but these three are essential.
To add a property to a JSON object, it helps to know how they work. 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 properties (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 1 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:
{% c-block language="js" %}
{
"actor": ,
"verb": ,
"object":
}
{% c-block-end %}
If you're not familiar with code, then 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.
{% c-block language="js" %}
{
"actor": {
},
"verb": {
},
"object": {
}
}
{% c-block-end %}
Great! With this framework in place, you're ready to begin defining each property by adding keys and values to the objects. We'll take it one property at a time.
The actor's value tells us who is completing the action. It consists of an object with two 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.
In the next tutorial, I explain how to collect this information from the user in a Storyline course. But 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:
{% c-block language="js" %}
{
"actor": {
"name": "Devlin",
"mbox": "mailto:devlinpeck@gmail.com"
},
"verb": {
},
"object": {
}
}
{% c-block-end %}
Excellent work! Now we're ready to move on to the "verb" object's properties.
The "verb" object's value consists of an object with two properties: "id" and "display". This information tells us what action the learner is performing.
The id's value is a unique identifier (URI), usually in the form of a URL that others can access to learn about the verb you choose. I recommend using ADL's xAPI Vocab Server to find the URI for your preferred verb.
Important note: You can use any URL that you'd like for the verb's 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: "http://adlnet.gov/expapi/verbs/completed". Therefore, you can add the following key / value pair to your verb object:
{% c-block language="js" %}
"id":"http://adlnet.gov/expapi/verbs/completed"
{% c-block-end %}
The second property of the verb object is "display". This is where you include the verb in a simple, human-readable format.
However, the "display" 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. You should add the following line of code beneath the verb's "id" property:
{% c-block language="js" %}
"display": { "en-US": "completed" }
{% c-block-end %}
And that's it for defining the verb! However, make sure that you add a comma after defining the verb's id. Your statement so far should look like this:
{% c-block language="js" %}
{
"actor": {
"name": "Devlin",
"mbox": "mailto:devlinpeck@gmail.com"
},
"verb": {
"id":"http://adlnet.gov/expapi/verbs/completed",
"display": { "en-US": "completed" }
},
"object": {
}
}
{% c-block-end %}
Perfect! All we have left to do is define the "object" property.
The "object" property consists of an object with two core properties: "id" and "definition". For most xAPI statements, 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: "https://www.devlinpeck.com/tutorials/write-xapi-statement". Again, the URI does not have to lead to a public-facing webpage, but it should consistently identify a unique object.
The object's "definition" value includes another object called "name". Similar to the "display" property of the verb object, the "name" property's value is an object that includes a language code as the key and a human-readable word / phrase for the activity as the value. In all, the object property looks like this:
{% c-block language="js" %}
"object": {
"id": "https://www.devlinpeck.com/tutorials/write-xapi-statement",
"definition": {
"name": { "en-US": "Write xAPI Statement Tutorial" }
}
}
{% c-block-end %}
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:
{% c-block language="js" %}
{
"actor": {
"name": "Devlin",
"mbox": "mailto:devlinpeck@gmail.com"
},
"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 %}
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.
The next tutorial in this series teaches you how to collect the user's name and email address from a Storyline course to populate your statement, and the third tutorial teaches you how to finally send an xAPI statement from a Storyline course.
If you'd like to explore the additional properties of an xAPI statement beyond actor, verb, and object, you can do so on the xAPI Statements 101 webpage.
