Telemetry and xAPI

Telemetry (@lessonkit/core)

Events include course_started, lesson_started, lesson_completed, lesson_time_on_task, quiz_answered, quiz_completed, and interaction.

Configure on Course / LessonkitProvider:

const config = {
  courseId: "my-course",
  tracking: {
    sink: (event) => sendToAnalytics(event),
    batch: { enabled: true, flushIntervalMs: 5000, maxBatchSize: 25 },
    // or batchSink: (events) => api.ingestBatch(events),
  },
  session: {
    sessionId: "optional-fixed-id",
    user: { id: "learner-1", email: "a@b.com" },
  },
};

tracking.enabled: false uses a no-op client.

Full catalog and payloads: Telemetry reference.

xAPI (@lessonkit/xapi)

Pass a transport on config:

xapi: {
  transport: async (statement) => {
    await fetch(LRS_ENDPOINT, { method: "POST", body: JSON.stringify(statement) });
  },
},

Lifecycle helpers on createXAPIClient mirror lesson/course completion. From 0.5+, lifecycle statements are also driven through the telemetry → xAPI mapper when courseId is set.

Inject a custom client:

xapi: { client: myXAPIClient },

LXPack bridge (packaged courses)

When embedded in an LXPack export, @lessonkit/react can forward completion/scores to window.parent.lxpackBridge.v1 (config.lxpack.bridge, default auto). See LXPack bridge reference and Packaging reference.

LessonkitProvider uses runtimeVersion: "v2" by default (headless runtime from @lessonkit/core). Set runtimeVersion: "v1" to opt out; see Core reference and MIGRATION-0.x-to-1.0.md.

Production

Before go-live, complete the production checklist (LMS bridge, flush-on-exit, blockId, observability hooks).

Observability hooks

observability: {
  onTelemetrySinkError: (err, { sinkId }) => { /* report */ },
  onXapiQueueDepth: (depth) => { /* gauge */ },
  onXapiQueueCap: () => { /* alert: queue dropped oldest statement */ },
  onLxpackBridgeMiss: (event) => { /* LMS bridge missing for completion */ },
},

LessonkitProvider flushes xAPI and telemetry when the tab is hidden or on pagehide.

Identity and URNs

All telemetry requires courseId. Object URNs for xAPI follow the identity contract—Identity reference.