Your Source for Learning
Technology, Strategy, and News
ARTICLES       RSS feed RSS feed


email print

Ten Steps to Plan & Communicate Your xAPI Design to a Web Developer


by Craig Wiggins, Peter Berking, Steve Foreman

October 13, 2014

“Thinking about what patterns emerge from interaction with your designs enables you to improve your students’ learning experiences, workplace performance, and, ultimately, contribution to the organization’s well-being. Additionally, it allows you as a learning professional to articulate the return on investment for your interventions.”

If you are an instructional designer beginning to work with the Experience API (xAPI), you may be wondering how to go about designing and developing an xAPI solution. Some of the authoring tools you use may support the xAPI. But the only activities some of these tools track are the same bookmarking, scoring, and completion data that SCORM handles.

To realize the full activity-tracking potential of the xAPI in your design, you will need to collaborate with a web developer who knows how to program and who can manually code the xAPI statements. This article outlines 10 steps you can take to plan and communicate your xAPI design to a web developer.

Step 1: Make sure that your technical partners understand the Experience API

The first step is to provide your web-development partner with information on how to develop xAPI statements. Point your partner to our companion article, Five Things a Web Developer Needs to Know About the xAPI, which provides a technical briefing on what the xAPI is and how it works as well as more detailed information about the syntax along with some tools and examples. (Editor’s Note: We also recommend The eLearning Guild’s research report The Experience API—Liberating Learning Design, which provides an in-depth exploration of the xAPI’s potential.)

One of the nice things about xAPI statements is that they are formatted in JavaScript Object Notation (JSON). Your development partner will need to know how JSON works, but all you need to know is that it is a human-readable programming method—that is, a non-programmer should not have much trouble designing xAPI statements.

Step 2: Make sure you have the required technology in place

First, thoroughly examine the kind of data that your instructional design calls for, and then see if you have the right technology to pull it off. You and your developer must answer the following questions:

  • Does your LMS support the xAPI?

    If your LMS does not support the xAPI, check with your LMS vendor to find out whether you can upgrade to a version with xAPI support. If not, then next time your organization upgrades its LMS, make sure xAPI support is on your requirements list. Meanwhile, you can acquire a third-party Learning Record Store (LRS). The addition of an LRS will enable you to implement your xAPI solution. (Editor’s Note: You can find information about some of the third-party LRS solutions by opening this link.)

  • What types of reporting and analytics will you need?

    Define your reporting and analytics requirements and check your LMS or LRS to make sure it provides the reporting or analytics you have designed for your xAPI solution.

  • Are there any IT policies or constraints that impact your design?

    Communicate with your IT department to ensure that your design aligns with security policies and standards related to the use of devices (especially if you plan to support smartphones or tablets.)

Step 3: Develop a communication method for your course’s data tracking needs

The sub-steps are as follows:

  1. Meet with your web developer to discuss overall goals. While you know best what you are trying to accomplish through your design, your web developer may have ideas on how to implement the xAPI statements. There are many ways to formulate statements and one xAPI verb may have advantages over another. By approaching the xAPI part of your design collaboratively, your developer will become better acclimated to your goals and may have some great ideas on how to make them happen.
  2. Meet with your developer to agree on a method and format for documenting and communicating your design. Table 1 below is recommended. It is an example from the eLearning Guild Research Report, The Experience API — Liberating Learning Design.

    Table 1: (Example) Documenting and formatting an xAPI design

    The Situation column can be used to describe the learner action that triggers the xAPI statement. The Purpose column describes what is being tracked and why. The Actor, Verb, and Object columns are the three components that make up an xAPI statement. This table format will document your design and provide the information your web developer will need to code the JSON version of the statement, place it in the proper location, and ensure the right information is being recorded.

  3. Try communicating a sample of your tracking statements using this method. Hand it off to your developer and verify that he or she understands your intent and can develop the code to implement it.

As you design your xAPI statements, be consistent. It is best to use the same verbs to record similar activities. Establish and document your statement conventions. Using a format like the table above is an important step in maintaining and applying conventions consistently. As you develop more xAPI solutions, your organization may benefit from a “data dictionary” that documents your xAPI standards. This may seem like a lot of effort, but it may be worth it if you or your enterprise will be creating many more learning experiences like this one.

Step 4: Discuss verbs you will need

It is important for you to consider the verbs and their relationship to objects as you use them in your xAPI statements. Statements that convey context are easier to interpret and analyze in reports than statements that have none. For example, within an exam taken using a web form, statements like “Jane selected radio button 4” are difficult to interpret. A more meaningful statement would be “Jane chose assessment option d” because the type of object is an assessment as opposed to a generic form.

To add even more meaning, you can enter information into the statement’s context property as in “Jane chose assessment option d (PH), on question 3 (What is a measure of the acidity or basicity of an aqueous solution?) as a part of Chemistry 101 Quiz #1.” When you run LRS reports, you cannot see the labels for the text fields or radio buttons so embedding context makes your statements easier to interpret.

As you decide how to build meaning into your statements, it is important to define and document your verbs and make sure they are not ambiguous. For instance, the verb “fired” may mean “dismissed someone from employment” or “launched a projectile.” You and your web developer should agree on how you will use and define the verbs you use in your xAPI statements.

Step 5: Pilot test a selection of xAPI calls

Use the table you created in Step 3 to conduct some preliminary testing of the communication between your xAPI solution and the LRS. Trigger some of the events that send xAPI calls and look at the resulting statements that the LRS has stored. Don’t wait until the entire solution is developed. Ask your web developer to create a quick prototype for testing.

This preliminary testing will answer some critical questions. Did the triggers work? Was the data recorded properly in the LRS? Will you be able to use the LRS data to generate the reports and analytics you need? Early testing helps ensure that your LRS configuration is working properly and the design of your xAPI statements is effective so that you won’t risk having to backtrack when something goes wrong.

Step 6: Design activity size and flow of your learning experience

Finally, it’s time to sit down and design the full range of xAPI statements. There are now several key areas for you and your developer to explore.

Activity granularity and hierarchy

Deciding on the level of granularity is important. You must consider the entire context of each activity. Take, for example, the activity of cooking French toast, which consists of several sub-activities: Understanding a recipe, dry versus wet ingredients, beating an egg, dipping the bread, cooking techniques, serving sizes, etc. Is it important to track each sub-activity in the process or just the final milestone? Think about your reporting needs. Will it be useful to report on other activities that require the same sub-activity (beating an egg) such as making eggnog, scrambled eggs, and egg salad?  If the answer is yes, then you may need to track each sub-activity in the process.

xAPI statements can include an optional context property to help tie together higher-level activities with the more granular activities that comprise them. Statements can use context in many ways, but the most useful is to reference related activities. Using context within statements allows your LRS reporting and visualization services to build an “activity tree” of the activities you are recording. For example, the “beating an egg” activity may be used in thousands of recipes, but by setting its context to reference the “parent” activity, “Cooking French Toast,” the entire activity of cooking French toast could be pulled in a report, along with its associated sub-activities.

Granularity and context can work together to move further up the chain. Let’s say this French toast activity was a part of Cooking 101 at The Culinary Academy. Let’s also say a particular student is in the Fall 2014, Session 3 of this class. Creating a specific activity for Cooking 101, Fall 2014, Session 3 may be useful to find all statements within that particular class, but it would be harder to look across all French toast activities at The Culinary Academy. It is important to think about your reporting requirements as you make decisions about granularity and context.

Does your design require branching?

Clearly, you can use xAPI statements to collect data about activities the learner performs. Another way you can use xAPI statements is to trigger adaptive behavior such as branching to elaborate or remediate. Using xAPI statements this way may require two-way communication between your solution and the LRS. In other words, your solution may need to retrieve information from the LRS to control branching, such as learner responses to the last few questions. To plan for adaptive use of xAPI statements, consider working with your web developer to create flow charts like Figure 1 below.

Figure 1:
This flow chart is an example of one that would help an instructional designer communicate with a web developer when planning for adaptive use of xAPI statements

Does your design require personalization?

Your design may call for content personalization, for example to present cases or scenarios that are specifically relevant to the user’s role, function, or location. This may require retrieval of LRS information about the user’s profile so that you can adapt, personalize, or localize the solution. To do this, you will need to define “agents” in your statements. An agent is a user account in an LRS. The agent account allows you to collect and retrieve user-profile information on specific users. This information may be used to customize the learning experience for the individual user.

Step 7: Complete the learning-experience design

As you finish the remaining aspects of your design, you and your web developer should think about two key questions when deciding on the placement of xAPI statements:

  1. At what point in the learning process should the information and xAPI statement be generated? For example, some of your statements may be generated before the learning experience to collect agent information and recommend a specific path to the user. Some statements will clearly be generated during the learning experience to track the user’s learning results. Other statements may be generated after the learning experience to compare your performance to the performance of other users who have completed the learning activity.
  2. Who or what is generating the activity statement? Most of the time, the information will result from actions taken by the learner. It may also result from environmental factors such as your location, the retail season, or economic factors. Other actors such as a mentor, coach, or observer may also generate activity statements.

It is important to emphasize that, unlike SCORM, xAPI is not predicated on being used with asynchronous eLearning. xAPI-instrumented events can occur within the context of any type of learning experience. Any actor can generate them: a system, the learner (or a group of them), an instructor, a mentor, a training administrator, etc. For instance, many informal and constructivist learning scenarios rely on learners self-reporting their activities, and self-rating their progress. This can be done through a browser widget that learners use to record YouTube videos they have watched; an app that allows users to record that they have visited a certain location (as indicated to them by GPS location detection, for instance); a web form that allows mentors to record a successful mentoring session; and in other ways. The list of possibilities is endless. You and your programmer should work together to plan all relevant aspects of the learning experience to get the data you need.

Step 8: Develop the learning experience

Your developer should now be ready to start working on creating the solution, including xAPI calls, if he or she has not already. Once the solution is completed, be sure to fully test it before deployment.

Step 9: Deploy or implement the learning experience

Deploy the learning experience, including all of the necessary parts to make the xAPI elements work: LRS and associated dashboards, analytics engines, etc.

Step 10: Learning experience improvement

Congratulations! You have successfully created your solution. From a technical standpoint, you and your collaborators have achieved success. However, as an instructional designer your work is not done.

After you have implemented your design—either as an extension of pilot testing or in the “real world”—you will finally have data to analyze. What does detailed, aggregated learning-experience information regarding your course’s instructional video tell you about your design? Are learners watching the entire video? Are they re-watching a specific portion? If the video is embedded in a player (e.g., YouTube, Vimeo, etc.) are learners hitting the “Watch Later” button? Are they sharing the video?

Thinking about the patterns that emerge from interaction with your designs enables you to improve your students’ learning experiences, workplace performance, and, ultimately, contribute to the organization’s well-being. Additionally, it allows you as a learning professional to articulate the return on investment for your interventions.


At this point in the early life of the xAPI spec, there are not many tools that automate or de-skill the process of planning and creating xAPI calls, especially calls that go beyond scoring and completion data to realize its full activity-tracking potential. To take full advantage of the xAPI, you will need to work with a web developer who can write statements and embed them in your learning and performance support solutions. We hope that this document will help you and your web developer work together effectively to plan and communicate these coding requirements. This 10-step process will help you make important strategic decisions for using xAPI, putting you on the path towards a data-driven learning ecosystem.

From the Editor: Want more? Explore the xAPI at DevLearn!

At DevLearn 2014 later this month there will be two xAPI highlights. The first is xAPI Hyperdrive, a new competition designed to showcase the best examples of innovation using the Experience API; it takes place Tuesday, October 28 at 3:30 PM, the afternoon before the conference begins.

During the conference itself, October 29 – 31, we offer a brand-new featured track—xAPI in Practice—that is included with conference registration. The xAPI in Practice program consists of a group of sessions that run throughout the conference, offering you the chance to explore real-world case studies showing how xAPI is being used in organizations today. Learn about the business value of xAPI and the opportunities it presents to improve your practice.

Topics Covered

Appreciate this!

Login or subscribe to comment

Be the first to comment.

Related Articles