From Clicks to Context: Crafting Smarter xAPI Statements

A Learning Experience Designer’s guide to writing xAPI statements that actually make sense—and make impact.

Originally posted on Substack

We’ve gone over xAPI and how simple the statements are: actor, verb, object. The syntax is simple, but it unlocks power that is anything but.

Whether you’re a tech-savvy LxD professional or working with your IT department, understanding how xAPI works behind the scenes makes all of us better storytellers and more intentional designers.

So let’s go behind the curtain and look at how we can craft smarter, scalable xAPI statements.

1. Understand the Anatomy of a Statement

At its core, an xAPI statement follows this structure:

{
  "actor": {"name": "Jordan", "mbox": "<mailto:jordan@company.com>"},
  "verb": {"id": "<http://adlnet.gov/expapi/verbs/completed>", "display": {"en-US": "completed"}},
  "object": {"id": "<http://company.com/learning/Module1>", "definition": {"name": {"en-US": "Module 1: Introduction"}}}
}

That’s the minimum viable sentence. But you can add:

• Result (score, success, response)

• Context (parent activity, platform)

• Timestamp

• Attachments (e.g., file uploads or screenshots)

Each field adds clarity and nuance to what the learner did.

2. Choose Your Verbs Wisely

“Experienced,” “completed,” “answered,” “interacted.”

The verb defines the action, and verbs should be consistent and meaningful. Use standard verbs from cmi5 when possible. Custom verbs are allowed, but let’s think long term. Will this make sense in reports? Will someone else understand what it means?

Example: Avoid vague verbs like “used.” Instead, try:

• “launched” for opening a tool,

• “attempted” for a simulation,

• “shared” for peer content

3. Keep Your Object IDs Unique and Persistent

The object is what the learner interacts with. The id should be a permanent, unique URL-like string (even if it’s not a real page). It identifies the learning object across time.

Example: Use http://company.com/learning/quiz_intro rather than intro_quiz_v2

This consistency means you can track engagement across versions or cohorts.

4. When and How to Send

Statements are typically sent via HTTP POST to your LRS’s /statements endpoint. If using JavaScript, the fetch()method is your friend.

Example:

fetch("<https://mylrs.com/xapi/statements>", {
  method: "POST",
  headers: {
    "Authorization": "Basic ...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(xapiStatement)
});

Authentication matters. Use LRS-issued keys. And don’t hardcode credentials in public code.

5. Batch and Buffer Wisely

For high-volume or mobile use, consider:

• Batching: Send multiple statements in one call.

• Buffering: Store statements offline and send when reconnected.

Libraries like TinCanJS or Learning Locker's client tools can handle this elegantly.

6. Debugging Your Statements

Use your LRS dashboard to monitor live incoming data. Check:

• Are verbs and objects readable?

• Are timestamps accurate?

• Are you capturing the right data, or just noise?

Run statements through a validator (like ADL’s xAPI statement viewer) to catch structural errors.

7. Collaborate Across Roles

LxDs define what should be tracked. Developers decide how to track it. The magic happens when both sides understand each other’s language. So sit down together, map the experience, and co-author your data story.

From Clicks to Context

Every xAPI statement is a sentence in your learner’s story. And like any story, it needs a clear voice, consistent tone, and meaningful plot points.

Get the tech right, and the insights will follow.

---

This concludes our 6-part series on xAPI for LxD professionals. Stay tuned for visual walkthroughs, toolkit templates, and next-level data strategy guides coming soon.