How to Write an xAPI Statement from Scratch

Welcome to the Getting Started with xAPI Tutorial Series.

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, 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++.

Creating the Statement Framework

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:

{

}

Voila! You've officially created 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:

{
  "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.

Defining the Actor

The actor's 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. In a later tutorial, I will 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:

{
  "actor": {
    "name": "Devlin",
    "mbox": "mailto:devlinpeck@gmail.com" 
  },
  "verb": {

  },
  "object": {

  }	
}

Excellent work! Now we're ready to move on to the verb object's properties.

Defining the Verb

The verb's value consists of an object with two keys (or properties): "id" and "display". This 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 the xAPI Registry 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://activitystrea.ms/schema/1.0/complete". Therefore, you can add the following key / value pair to your verb object:

"id":"http://activitystrea.ms/schema/1.0/complete"

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. You should add the following line of code beneath the verb's "id" property:

"display": { "en-US": "completed" }

And that's it for defining the verb! However, make sure that you remembered to add a comma after defining the verb's id. Your statement so far should look like this:

{
  "actor": {
    "name": "Devlin",
    "mbox": "mailto:devlinpeck@gmail.com" 
  },
  "verb": {
    "id":"http://activitystrea.ms/schema/1.0/complete",
    "display": { "en-US": "completed" }
  },
  "object": {

  }	
}

Perfect! All we have left to do is define the object property.

Defining the Object

The object's 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. (The xAPI Registry includes a standard list of activity types).

The object's "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 / 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:devlinpeck@gmail.com" 
  },
  "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" }
    }
  }	
}

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. 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 final 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.

As always, if you have any questions, feel free to leave them in the comments below. Also feel free to share this tutorial on Twitter to help spread the xAPI love.