Instructor's Guide¶

Welcome to the Instructor's Guide for xAPI for Intelligent Textbooks. This guide explains every feature of the textbook, how to use it in your classroom or training program, and how to customize it for your students. No prior technical knowledge of xAPI is assumed — every technical term is defined before it is used.

This textbook is designed for software professionals (web developers, instructional technologists, learning engineers, and platform architects) who are building or extending Level 3 interactive intelligent textbooks and want to instrument them with xAPI for detailed learner analytics. As an instructor, you may be teaching this course in a graduate program, a corporate training cohort, a bootcamp, or as a self-paced study group.

About This Interactive Intelligent Textbook¶

What is an Intelligent Textbook?¶

An intelligent textbook is a digital textbook that goes beyond static text and images. It includes interactive simulations, self-grading quizzes, a searchable glossary, a structured map of how concepts relate to each other, and (in higher levels) adaptive content that responds to each learner. The goal is to give students a richer, more engaging learning experience than a traditional printed textbook.

In a delightful bit of recursion, this particular intelligent textbook is about the standard (xAPI) that turns intelligent textbooks into measurable, optimizable learning systems. Your students will learn to instrument the very kind of book they are reading.

The Five Levels of Intelligent Textbooks¶

Not all digital textbooks are created equal. We categorize intelligent textbooks into five levels based on how interactive and adaptive they are:

Level	Name	Description	Example Features
Level 1	Static Digital	A PDF or basic web version of a print textbook	Text and images only, no interactivity
Level 2	Interactive	Adds interactive elements like simulations, quizzes, and searchable glossaries	MicroSims, self-check quizzes, concept search
Level 3	Adaptive	Adjusts content based on student performance	Personalized learning paths, difficulty adjustment
Level 4	AI-Assisted	Includes an AI tutor that can answer student questions	Chatbot integration, automated feedback
Level 5	Fully Adaptive AI	Continuously learns from student interactions and optimizes the experience	Real-time content generation, predictive analytics

This textbook is currently a Level 2 Intelligent Textbook — every diagram, infographic, and MicroSim is interactive and gives the learner feedback. The xAPI instrumentation that students learn to build over the course of the book is the same technology that would move a textbook from Level 2 to Level 3 (and beyond), so the course is, in effect, a recipe for upgrading any intelligent textbook to the next level.

What Makes This Textbook Different¶

Every visual is interactive. There are no static decorative diagrams. Every chart, flowchart, timeline, and map invites the learner to hover, click, or manipulate something — and gives feedback when they do. This is a defining property of an intelligent textbook.
50+ MicroSims let students manipulate xAPI statements, LRS queries, bandwidth budgets, and pipeline architectures directly in their browser — no software installation required.
Critical thinking emphasis — every chapter helps students implement, debug, and validate xAPI instrumentation in production intelligent textbooks, with real-world failure modes called out by name (we call these "footguns" internally).
"Learning superpower" framing — a positive, empowering tone that treats xAPI knowledge as a new ability the learner is gaining, not a pile of trivia to memorize.
Learning graph — a visual map showing how all 250 concepts connect and build on each other.
Xavi the Octopus — a friendly mascot character (called a "pedagogical agent") who guides students through each chapter with tips, encouragement, and key insights. Xavi's catchphrase is "Every interaction tells a story!" — which is also, conveniently, the entire premise of xAPI.
Completely free and open source — licensed under Creative Commons for non-commercial use.

Using the Chapters¶

Chapter Structure¶

The textbook contains 14 chapters organized in a deliberate sequence. Each chapter builds on concepts from previous chapters, so students should work through them in order:

Chapters	Topic Area
1	Foundations and the broader learning standards ecosystem (SCORM, AICC, CMI5, IMS Caliper, LTI, xAPI)
2–3	The xAPI Statement Model — Actor/Verb/Object plus context, result, attachments, and advanced structure
4	Verb vocabulary design — picking, naming, and reusing canonical and custom verbs
5	Activities, Agents, and Identity — including the four Inverse Functional Identifiers (IFIs)
6–7	Learning Record Store (LRS) architecture, platforms (TRAX, Learning Locker, Ralph, Watershed), and authentication
8	Implementing xAPI inside an intelligent textbook end-to-end
9	Bandwidth optimization, batching, and offline support with service workers and IndexedDB
10	Monitoring and observability — DevTools, proxies, dashboards, and engagement heatmaps
11	Synthetic data generation with AI (Claude Code) for load testing and statistical realism
12	Conformance testing and competitive comparison (xAPI vs. Caliper vs. CMI5 vs. proprietary)
13	Production pipelines — emit-path topology, retry-with-backoff, and pseudonymization
14	Privacy and compliance — FERPA, COPPA, GDPR, and PII surface analysis

What Each Chapter Contains¶

Every chapter follows a consistent structure:

YAML front matter — Metadata at the top of each chapter file (title, description, reading level, status). Students don't see this; it's used by search engines and the website builder.
Summary — A brief overview of what the chapter covers and what new "superpower" students will gain.
Concepts covered — A list of the specific concepts addressed in the chapter, drawn from the learning graph.
Prerequisites — Links to prior chapters that should be completed first.
Welcome from Xavi — A mascot admonition that introduces the chapter topic in Xavi's friendly, technically-precise voice.
Main content — The core instructional material, written for technically literate professionals. Includes tables, real-world examples, and embedded MicroSims. Every diagram is interactive.
Mascot admonitions — Throughout the chapter, Xavi appears 5–6 times to highlight key insights (thinking), offer practical tips (tip), provide encouragement on harder concepts (encourage), and warn about common mistakes (warning).
Key takeaways — A numbered summary of the most important concepts, often preceded by a celebration from Xavi.
Critical thinking challenge — Expandable sections that train students to detect anti-patterns, "footguns," and silently-wrong behavior in real xAPI deployments.
Practice questions — Open-ended questions for discussion or written responses.

Each chapter also has its own Quiz page and Annotated References page in the navigation sidebar.

Suggested Classroom Use¶

Before class: Assign the chapter as reading homework. The MicroSims keep students engaged during independent reading and give them something concrete to discuss when they arrive.
During class: Use the MicroSims on a projector for whole-class demonstrations. Ask students to predict what an LRS query will return, or what happens to bandwidth when batching is disabled, before you change the slider. Then test their predictions.
After class: Assign the practice questions, the quiz, and the annotated references. The annotated references are excellent jumping-off points for term papers or implementation projects.
Pacing: Each chapter is designed for approximately one week of a graduate or professional course (roughly 3–6 hours of student work, including reading, MicroSim exploration, and the quiz). A 14-week semester maps cleanly to the 14 chapters; a shorter cohort can pair adjacent chapters.

Using the MicroSims¶

What is a MicroSim?¶

A MicroSim (short for "micro-simulation") is a small, interactive simulation that runs directly in a web browser. Students don't need to install any software — MicroSims work on any device with a modern web browser (Chrome, Firefox, Safari, Edge).

Each MicroSim lets students manipulate one or more variables (using sliders, buttons, dropdowns, or drag-and-drop) and immediately see how the model responds. This "learn by doing" approach helps students build intuition for abstract concepts like statement structure, network bandwidth, and authentication flows.

How MicroSims Are Embedded¶

MicroSims appear within chapter text as rectangular interactive areas. They are embedded using iframes — a web technology that displays one web page inside another. You don't need to understand how iframes work to use them in class; just know that the MicroSims load automatically when students view the chapter page.

Types of MicroSims¶

The textbook includes more than 50 MicroSims built with different visualization technologies:

Technology	What It's Good For	Example MicroSims
p5.js	Interactive animations with sliders and buttons	xAPI Statement Builder, Bandwidth Budget Calculator, Retry-With-Backoff State Machine
Mermaid	Flowcharts and architecture diagrams with clickable nodes	Full Pipeline Architecture, Voiding Lifecycle Flow, Service Worker Offline Queue Flow
vis-network	Network diagrams showing relationships between concepts	Learning Graph Viewer, Vocabulary Profile Architecture
vis-timeline	Historical and sequential views	A Timeline of Learning Interoperability Standards
HTML/CSS card grids	Comparative reference cards	LRS Platform Comparison Card Grid, Standards Comparison Card Grid

Tips for Using MicroSims in Class¶

Project them on a screen. MicroSims are designed to be visible on a projector. Have students call out predictions before you move a slider.
Let students explore independently. After a demonstration, give students 5–10 minutes to experiment on their own devices. The Bandwidth Budget Calculator and the Statement Builder reward open-ended exploration.
Use the "Reset" button. Most MicroSims have a reset button. Encourage students to reset and try different scenarios.
Connect each MicroSim to the text. Each MicroSim is placed near the concept it illustrates. After exploring the sim, have students re-read the surrounding text — it usually lands differently the second time.
Offline access. MicroSims require an internet connection unless you have built the site locally (see "Customizing Your Own Textbook" below).

Xavi's Tip: Embed MicroSims Anywhere!

You can add any MicroSim to any web page — a Google Site, a WordPress blog, an LMS like Canvas, Moodle, or Schoology, or even a plain HTML file. Just paste a single line of HTML:

<iframe src="https://dmccreary.github.io/xapi-course/sims/YOUR-MICROSIM-NAME/main.html"
    width="100%" height="450px"
    scrolling="no">
</iframe>

Replace YOUR-MICROSIM-NAME with the directory name of any MicroSim from the MicroSims list. That's it — one line of code and your students have an interactive simulation on any page you control. Every interaction tells a story!

MicroSim Specifications¶

Within each chapter, you'll find a collapsible details section near each MicroSim labeled with its name. Click to expand and see the full specification including:

Bloom's Taxonomy level — What cognitive level the MicroSim targets (Remember, Understand, Apply, Analyze, Evaluate, Create)
Learning objective — What students should be able to do after using the MicroSim
Interactive controls — What sliders, buttons, and inputs are available
Default parameters — The starting values when the MicroSim loads

These specifications are useful for lesson planning and for understanding the pedagogical intent behind each simulation.

Using the Glossary¶

What is the Glossary?¶

The glossary is an alphabetical list of all key terms used in the textbook, each with a precise, concise definition. Because xAPI introduces a lot of vocabulary in its first few chapters (Actor, Verb, Object, IFI, Activity Provider, LRS, statement, attachment, voiding, context activity, and so on), the glossary is one of the most valuable resources in the book.

How to Access the Glossary¶

Click "Glossary" in the left navigation sidebar from any page.
Use the browser's built-in search (Ctrl+F on Windows/Linux, Cmd+F on Mac) to find a specific term on the glossary page.
Use the site-wide search bar at the top of any page to search for a term across the entire textbook.

Tips for Using the Glossary in Class¶

Vocabulary preview — Before starting a new chapter, have students look up the key terms in the glossary to build familiarity. Chapter 2 (Statement Model) and Chapter 5 (Activities, Agents, Identity) especially benefit from this.
Definition matching — Create a warm-up activity where students match glossary definitions to terms from the current chapter.
Student-generated definitions — After reading a chapter, have students write their own definitions, then compare with the glossary.
Glossary quizzes — Use glossary terms for quick formative assessments (flash cards, quiz games, etc.).

Using the FAQ¶

If a Frequently Asked Questions page is generated for this textbook, it will appear in the navigation. The FAQ is a curated list of common questions students ask about xAPI, organized by topic. Each question includes a clear, concise answer written at the same level as the chapters.

Tips for Using the FAQ in Class¶

Discussion starters — Pick 2–3 FAQ questions at the start of class and have students discuss before revealing the answer.
Homework support — Point students to the FAQ when they have questions outside of class hours.
Extension reading — The FAQ often covers angles not addressed in the main chapter text, making it good supplementary material.
Test review — Students can use the FAQ as a study guide before assessments.

Using the Quizzes¶

What Are the Quizzes?¶

Each chapter has an accompanying Quiz page with multiple-choice questions designed for self-assessment. Quizzes test understanding of the concepts covered in that chapter and are aligned to specific items from the learning graph.

How Quizzes Work¶

Quizzes are accessed by clicking the "Quiz" link under each chapter in the left navigation.
Each quiz contains multiple-choice questions at varying Bloom's Taxonomy levels.
Questions are presented as expandable sections — students can click to reveal the answer and explanation after attempting the question.
Quizzes are not graded automatically — they are designed as formative self-check tools, not summative assessments.

Tips for Using Quizzes in Class¶

Exit tickets — Have students complete the quiz at the end of a class session as a quick check for understanding.
Pre-reading check — Assign the quiz before the chapter to see what students already know (diagnostic assessment).
Post-reading review — Use the quiz after reading to identify concepts that need re-teaching.
Collaborative quiz — Have students work in pairs to discuss each question before revealing the answer. xAPI questions about IFI selection or context activity buckets reward collaborative reasoning.
Custom assessments — Use the quiz questions as a bank to create your own tests. The questions are openly licensed (see "Understanding the License" below).

Bloom's Taxonomy Levels¶

Each quiz question is tagged with a Bloom's Taxonomy level. Bloom's Taxonomy is a framework that classifies thinking skills from simple to complex:

Level	Name	What It Means	Example Verb
L1	Remember	Recall facts and definitions	Define, list, name
L2	Understand	Explain concepts in your own words	Explain, describe, compare
L3	Apply	Use concepts to solve problems	Calculate, demonstrate, solve
L4	Analyze	Break down and examine relationships	Differentiate, organize, compare
L5	Evaluate	Make judgments based on criteria	Assess, argue, justify
L6	Create	Produce original work or solutions	Design, construct, propose

A well-balanced assessment includes questions across multiple levels. The quizzes in this textbook primarily target levels L1–L4, with the critical thinking challenges and capstone-style projects in the chapters targeting L5–L6.

Using the References¶

What Are the References?¶

Each chapter has an accompanying Annotated References page with a curated list of high-quality sources that students can use for further reading. References prioritize stable sources (Wikipedia, the ADL specification archive, IMS Global publications, and peer-reviewed papers) and include a brief annotation explaining why each source is relevant to the chapter.

How References Are Organized¶

Each reference includes:

Title — The name of the source.
URL — A clickable link to the source.
Relevance — A brief description of why this source is useful and how it connects to the chapter content.

A Note About Link Rot¶

Link rot is when a web link (URL) stops working because the page has been moved, renamed, or deleted. This is a common problem with any resource that links to external websites. While we prioritize sources with stable URLs, some links may become outdated over time — and the xAPI ecosystem itself has been through several governance transitions, so even canonical-looking ADL URLs occasionally move.

If you or your students encounter a broken link:

Try searching for the article title on the source website.
Use the Wayback Machine to find archived versions of the page.
Report the broken link using GitHub Issues (see "Feedback" below).

Feedback¶

Reporting Issues and Suggestions¶

This textbook is an open-source project hosted on GitHub, a website where software and content projects are developed collaboratively. You don't need to understand programming to report a problem or suggest an improvement.

What is a GitHub Issue?¶

A GitHub Issue is like a support ticket — it's a way to report a bug, suggest an improvement, or ask a question. Each issue gets a unique number and can be discussed by the project team and community.

How to Submit Feedback¶

Go to the textbook's GitHub repository: dmccreary/xapi-course
Click the "Issues" tab at the top of the page.
Click the green "New issue" button.
Give your issue a clear title (e.g., "Broken link in Chapter 7 references" or "Suggestion: add MicroSim for cmi5 launch").
In the description, provide as much detail as possible:
- Which page or chapter has the problem
- What you expected to see vs. what you actually see
- Your browser and device (if relevant)
Click "Submit new issue".

You will need a free GitHub account to submit issues. If you prefer not to create an account, you can email feedback to the author using the Contact page.

Types of Feedback Welcome¶

Typos and errors — factual mistakes, spelling errors, broken formatting
Broken links — URLs that no longer work
MicroSim bugs — simulations that don't load or behave unexpectedly
Content suggestions — topics that should be covered, examples that could be improved
Accessibility issues — content that is difficult to read or navigate for students with disabilities

Understanding the License¶

What is a Creative Commons License?¶

A license is a legal document that explains what others are allowed to do with a piece of work. A Creative Commons (CC) license is a standardized, easy-to-understand license used for educational and creative content. It tells you exactly what permissions you have without needing a lawyer.

This Textbook's License¶

This textbook uses the CC BY-NC-SA 4.0 license. Here's what each part means:

Code	Full Name	What It Means
CC	Creative Commons	A standard open license
BY	Attribution	You must give credit to the original author
NC	Non-Commercial	You cannot use the material to make money
SA	Share-Alike	If you modify the material, you must share it under the same license
4.0	Version 4.0	The version of the license (the current standard)

What You CAN Do¶

Copy the entire textbook or individual chapters for your students.
Share the textbook link with other instructors, students, or colleagues.
Print chapters for classroom use.
Modify the content — add your own examples, remove sections, change the order.
Translate the content into other languages.
Create derivative works — build your own version of the textbook based on this one (for example, an "xAPI for K-12 Administrators" or "xAPI for Corporate L&D" derivative).

What You CANNOT Do¶

Sell the textbook or charge students for access.
Remove attribution — you must credit the original author (Dan McCreary).
Use a different license — if you modify and share, it must remain CC BY-NC-SA 4.0.
Claim it as your own work — the attribution requirement means you must acknowledge the original source.

For the full legal text, see the License page.

Customizing Your Own Textbook¶

One of the most powerful features of this textbook is that you can create your own customized version. This section explains how, step by step.

Key Technical Terms¶

Before we begin, here are some terms you'll need to understand:

Repository (repo) — A folder on GitHub that contains all the files for a project. Think of it as the project's home directory.
Git — A version control tool that tracks changes to files. It lets you see what changed, when, and by whom.
Clone — Making a complete copy of a repository on your own computer.
Fork — Making a complete copy of a repository on your own GitHub account (stays on GitHub, not your computer).
MkDocs — The software that converts the textbook's markdown files into a website. You don't need to learn MkDocs deeply — just enough to make basic changes.
Markdown — A simple text formatting language. If you can write an email, you can write Markdown. **bold** makes bold, # Heading makes a heading, and - makes a bullet point.
mkdocs.yml — The main configuration file for the textbook website. It controls the site title, navigation structure, colors, and which features are enabled.

Step 1: Create a GitHub Account¶

If you don't already have one, go to github.com and create a free account.

Step 2: Fork or Clone the Repository¶

Option A: Fork (easier, stays on GitHub)

Go to dmccreary/xapi-course.
Click the "Fork" button in the upper-right corner.
This creates a copy in your own GitHub account that you can edit.

Option B: Clone (more control, works on your computer)

Install Git on your computer (git-scm.com).
Open a terminal (Command Prompt on Windows, Terminal on Mac).
Run this command:

git clone https://github.com/dmccreary/xapi-course.git

This downloads the entire textbook to your computer.

Step 3: Make Changes¶

All content files are in the docs/ folder. They are written in Markdown (.md files) — plain text files with simple formatting. You can edit them with any text editor.

Changing the Title and Description¶

Open mkdocs.yml and edit these lines:

site_name: "Your Custom Textbook Title"
site_description: "Your description here"
site_author: "Your Name"

Changing the Colors¶

In mkdocs.yml, find the palette section:

theme:
  palette:
    primary: indigo    # Change to: blue, red, purple, teal, etc.
    accent: orange     # Change the accent color

MkDocs Material supports these primary colors: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue grey.

Changing the Logo¶

Replace the file at docs/img/logo.png (or, in this textbook, the mascot image at docs/img/mascot/neutral.png referenced from theme.logo) with your own logo image.

Step 4: Preview Your Changes Locally¶

Install Python (version 3.8 or newer) from python.org.
Install MkDocs and the Material theme:

pip install mkdocs mkdocs-material

Navigate to the project folder and start the preview server:

cd xapi-course
mkdocs serve

Open your browser to http://127.0.0.1:8000/xapi-course/ to see your customized version.

The preview server watches for file changes. When you edit and save a Markdown file, the page automatically refreshes in your browser.

Step 5: Publish Your Version¶

To publish your customized textbook as a free website using GitHub Pages:

mkdocs gh-deploy

This command builds the website and publishes it to https://YOUR-USERNAME.github.io/xapi-course/. The process takes about 1–2 minutes.

Customizing Your Analytics¶

What is Web Analytics?¶

Web analytics is the process of measuring how visitors use a website — which pages they visit, how long they stay, and where they come from. For an educational textbook, analytics can help you understand which chapters students read most, which MicroSims they interact with, and where they might be struggling.

Google Analytics¶

This textbook supports Google Analytics — a free service from Google that tracks website visits. The author's analytics property may already be configured, but if you create your own fork, you'll want to set up your own.

Setting Up Your Own Google Analytics¶

Go to analytics.google.com and sign in with a Google account.
Create a new property (Google's term for a tracked website).
Google will give you a Measurement ID — a code that looks like G-XXXXXXXXXX.
In your mkdocs.yml, update the extra section:

extra:
  analytics:
    provider: google
    property: G-YOUR-MEASUREMENT-ID

Rebuild and deploy your site. Analytics data will start appearing within 24–48 hours.

What You Can Learn from Analytics¶

Which chapters are most/least visited — helps you identify where students might be skipping content.
Average time on page — longer times may indicate engagement or confusion.
Device breakdown — what percentage of students use phones vs. computers.
Geographic distribution — where your students are accessing from.
Search terms — what students search for on your site.

xAPI Monitoring (Advanced — and Also the Topic of This Book)¶

The whole point of this textbook is to teach you and your students how to instrument intelligent textbooks with xAPI. Of course, you can also instrument this textbook the same way. The same patterns you'll learn in Chapters 8–10 — emit-path topology, statement batching, offline buffering, monitoring dashboards — are exactly what you'd use to capture rich learning analytics from your students' use of this book.

What is an LRS?¶

An LRS (Learning Record Store) is a database that stores xAPI learning records. Think of it as a specialized analytics system designed specifically for education. If you use an LRS, you can track granular student learning data — which is the kind of data your students will be designing systems to produce.

Important: Regulatory Considerations¶

Before collecting student-specific learning data, be aware of these regulations (covered in detail in Chapter 14):

FERPA (Family Educational Rights and Privacy Act) — U.S. federal law that protects student education records. If you collect data that can identify individual students, you must comply with FERPA.
COPPA (Children's Online Privacy Protection Act) — U.S. federal law that applies to children under 13. Most readers of this book will be teaching adults, so COPPA usually does not apply, but check before assuming.
State laws — Many U.S. states have additional student privacy laws.
GDPR (General Data Protection Regulation) — European Union law that applies if any of your students are in the EU.

Recommendation: The Google Analytics setup described above is anonymous by default — it tracks aggregate page views, not individual students. This is the safest approach for instructor-side measurement. If you want individual student tracking via xAPI as part of a course project, consult your institution's data privacy officer first, and use the pseudonymization patterns from Chapter 13.

The Learning Graph¶

What is a Learning Graph?¶

A learning graph is a visual map showing how concepts in the textbook depend on each other. It is structured as a DAG (Directed Acyclic Graph) — a diagram where arrows show which concepts must be understood before others.

For xAPI, this matters more than usual: the standard introduces vocabulary that interlocks tightly. Concepts like Statement, Actor, Verb, Object, Activity, Agent, IFI, and Context Activity all reinforce one another, and missing one weakens the rest. The learning graph makes these dependency chains visible.

How Instructors Can Use the Learning Graph¶

Prerequisite checking — Before teaching a concept, verify that students have covered its prerequisites.
Remediation — If a student struggles with a concept, trace back to its prerequisites to find the gap (e.g., a student stuck on "context activity buckets" probably needs to revisit "statement structure" first).
Curriculum mapping — Compare the learning graph to your existing syllabus to identify coverage gaps.
Enrichment — Advanced students can explore concepts ahead of the current chapter by following the graph forward.

The interactive Learning Graph Viewer is available in the "Learning Graph" section of the left navigation, and is itself one of the MicroSims (built with vis-network) — so it's a working example of the kind of interactive concept map your students will learn to instrument.

Xavi the Octopus: Your Pedagogical Agent¶

What is a Pedagogical Agent?¶

A pedagogical agent is a character that appears throughout a textbook to guide students. Research shows that pedagogical agents improve student engagement and perception of learning — a phenomenon called the persona effect.

Meet Xavi¶

Xavi (pronounced "ZAH-vee") is a round, indigo-blue octopus with large curious eyes and small round glasses perched near the top of his mantle. His catchphrase is "Every interaction tells a story!" — which conveniently happens to be the entire premise of xAPI. Xavi is curious, methodical, encouraging, and witty. He refers to students as "builders" or "engineers."

How Xavi Appears¶

Xavi appears as colored callout boxes (called admonitions) throughout each chapter. There are seven types:

Type	Color	Purpose	Frequency
Welcome	Green	Introduces the chapter	Every chapter opening
Thinking	Orange	Highlights key insights	1–2 per chapter
Tip	Green	Shares practical advice	As needed
Warning	Red	Alerts to common mistakes ("footguns")	As needed
Encourage	Blue	Supports on harder concepts	Where students may struggle
Celebration	Purple	Celebrates progress	Every chapter ending
Neutral	Gray	General notes	As needed

Xavi appears no more than 5–6 times per chapter to avoid overuse. Mascot admonitions are never placed back-to-back.

Tips for Instructors¶

Read Xavi's tips aloud — They're written in a conversational, technically-precise tone that works well when spoken.
Use as discussion prompts — Xavi's "thinking" admonitions highlight the most important insights in each chapter and make excellent in-class discussion starters.
Encourage struggling students — Point students to Xavi's "encourage" admonitions when they're frustrated with a concept, especially in Chapter 5 (IFIs) and Chapter 7 (authentication), where the cognitive load peaks.
Use the "warning" admonitions for code review — Xavi's warnings flag the silent-failure patterns ("footguns") that production xAPI implementations get wrong. Have students hunt for the same patterns in their own capstone code.

A Final Note from the Author¶

xAPI is one of those standards that can feel sprawling at first — a lot of vocabulary, a lot of edge cases, a lot of "but what about…" questions. The framing of this textbook is that every interaction tells a story, and learning xAPI is the superpower that lets your students hear those stories instead of throwing them away.

Whether you're teaching this in a graduate seminar, a corporate training cohort, or a self-paced study group, the goal is the same: by the end of the course, your students should be able to walk into an instructional design meeting, listen to a pedagogical question, and say "we can measure that" — and then go build the instrumentation that proves it.

If you find ways to make this textbook better for your students, please open a GitHub issue or send a pull request. Every interaction tells a story, and your story as an instructor is one we want to hear.

— Dan McCreary, 2026