- Get Started
- Write Code
The main data structure used by xAPI to describe tracked experiences is called a statement. This structure is defined explicitly in the xAPI specification and explained for developers on the Statements 101 page. As a learning designer, you don’t need to know statements to the same level of detail as a developer, but you do need to understand the basics so that you can communicate with your developer effectively. You also need to know a process you can go through to design what data you want to track for each of your experiences.
Note that this tutorial assumes you’re creating a solution from scratch. If you’re using existing products that include xAPI tracking, those products will have already considered statement design so you may not need to.
Your first step in designing statements is to figure out what data about the learning experiences you’re designing you’ll need to capture. This needs to be a detailed list of every piece of data you’ll capture about each learning experience. At this stage, don’t worry so much about how you will get the data or even if getting that data is possible; work out what you’ll need in an ideal world.
The following questions will help you to compile that list:
Once you’ve determined what data you want to collect, you need to plan out how you will get that data and figure out what’s feasible within your budget. There are a few different approaches to collect data about experiences and the most appropriate approach will vary for different experiences and different contexts:
However you are tracking, there will be cost implications, and that cost will influence how you track. In some cases you may decide to go without a piece of data due to costs associated with obtaining it. Work with your technical team to figure out what is and isn’t feasible.
Having determined what data to capture and how to capture it, you can now think about how that data will be structured as xAPI statements. Your developer will dive into the details of statements, but as a learning designer, you need to understand the high level basics. The table below outlines the structure of a xAPI statements and the considerations you need to think about as a designer.
|Actor||An identity of the person who did the thing. People often have multiple identities e.g. personal and work email, Twitter etc. Only one is assigned to the experience.||Who is the person that the experience is about? See Who Did It?
Is the actor a single person or a group?
Which identity is most appropriate to use in this context? Are there any privacy issues? Will you need to associate multiple identifiers used to track different experiences?
|Verb||The action being done by the actor.||Work with your developer to choose the most appropriate verb identifier.
Will statements be displayed in multiple languages? If so, will verb translations be stored within statements or hosted elsewhere?
|Object||The thing the actor is acting on. This is normally an activity, but can also be a person, group or even another statement.||What information do you need to capture about the activity itself?
How will you create the activity id and ensure it’s unique? See Get the activity id right
|Result||The outcome of the experience e.g. success, completion, score etc.||What does ‘result’ look like in the context of the experience you are tracking? Does it fit with the concept of pass/fail and complete/incomplete or do you need to track different data points using extensions?|
|Context||The context of the experience, e.g. the larger learning activity this formed a part of, any other related activities, the instructor or team, the platform and language used in the experience.||What information about the context of the experience needs to be captured?
How does the concept of ‘attempts’ work in your learning solution? This may be represented within the context.
|Authority||The person or group that asserts that the thing happened.
The authority is set by the Learning Record Store based on the security credentials used.
|Authority allows you to mark the source of the data so you can make use of data from more and less reliable sources.
Consider how the authority of data will be represented in reporting and analytics.
|Timestamp||When the experience happened; not necessarily when the data was stored.||Will you need to store tracking data offline to be sent later?|
|Attachments||Files attached can be attached to the statement e.g. evidence of a learning activity.||Attachments can be useful, but consider data storage and performance implications.|
Recipes are a way of structuring statements for a particular type of activity, such as watching a video, attending an event or completing a course. It’s really important that you follow recipes when designing your statements. Recipes are particularly important for developers working with xAPI, and designers need to have an understanding too. Read more about recipes here.
Statement design can be tricky for beginners and we love to help!