[4.2] xAPI Tracking

1. Front Matter

Title: xAPI Export and Tracking Integration

Author: Jethro Magdaleno Lagmay

• Reviewers: James Derrick Billate

• Creation Date: June 6, 2026

• Status: Draft

2. Introduction & Goals

Problem Summary: Historically, WyzQuests supported only SCORM 1.2 and SCORM 2004 for course exports. However, modern Learning Record Stores (LRS) and LMS environments rely on xAPI (Tin Can) to capture granular, event-driven learner data. This feature introduces xAPI export capabilities, allowing creators to generate tincan.xml compliant packages and enabling the WyzQuests player to fire real-time JSON statements to an external LRS when a learner interacts with decision nodes.

Goals & Non-Goals:

• Goals:

  • Enable generation of a valid xAPI .zip package with a tincan.xml manifest.

  • Capture dynamic LMS credentials (endpoint, auth, actor) passed via URL parameters and inject them into the QuestPlayer iframe.

  • Fire asynchronous xAPI answered statements when a learner selects a choice in a Decision Node.

  • Separate SCORM and xAPI backend architectures for maintainability.

• Non-Goals:

  • Building an internal LRS within WyzQuests.

  • Tracking non-decision interactions (e.g., time spent on a single page, scrolling).

  • Implementing the full cmi5 specification.

Glossary:

• xAPI (Experience API / Tin Can): An e-learning software specification that allows learning content and learning systems to speak to each other.

• LRS (Learning Record Store): The system that receives, stores, and returns xAPI statements.

• Statement: The JSON payload formatted as "Actor -> Verb -> Object" (e.g., "John Doe answered Scenario 1").

3. High-Level Architecture

System Diagram:

Technologies Used:

• React / Next.js

• jszip (for dynamic package generation)

• Standard Web APIs (Fetch, URLSearchParams)

4. Detailed Design & Implementation

Data Model / Schema: No new database tables were required. Export constants were centralized to avoid hardcoding:

• XAPI_EXPORT and SCORM_EXPORT implemented via constants/export.ts.

API Specification:

• Endpoint: POST /api/creator/export/xapi

• Description: Generates the xAPI zip package. Does not log to Supabase.

• Request Body: ```json { "questId": "string", "version": "xapi" }

• Response: application/zip containing index.html and tincan.xml.

Logic & Workflows:

• Frontend Export Modal (Export.tsx): Conditionally hides the "Mastery Score" input if xAPI is selected, as xAPI tracking relies on granular node decisions rather than a single passing score. Routes the request to /api/creator/export/xapi instead of the Single-SCO route.

• Manifest Generation: The route utilizes generateTinCanManifest() from lib/export/templates/xapiManifest.ts to build the required XML structure, omitting standard SCORM JavaScript wrappers.

• Event Tracking (QuestPlayer.tsx): The handleChoiceSelect wrapper captures the selected choice ID. It safely maps the choice text and node title against the existing TypeScript interfaces (currentChild, choices) and dispatches the payload using the XAPI_VERBS.answered constant.

5. Infrastructure & Operations

Dependencies:

• This feature strictly relies on the host LMS/LRS to provide valid endpoint, auth, and actor parameters. If these are missing, the QuestPlayer fails silently by design, allowing the visual canvas to continue functioning without tracking.

Monitoring & Alerting:

• Backend export failures will be caught and returned as standard 400/500 JSON responses or bubble up to the global error handler.

• Failed xAPI fetch requests to the external LRS are caught in the client-side try/catch block within the sendXAPIStatement wrapper to prevent blocking the UI thread.

Deployment Plan:

• Standard merge to main. No database migrations or feature flags are required as this extends the existing export functionality.

6. Testing & Quality Assurance

Test Strategy:

• End-to-End Testing: Conducted via SCORM Cloud.

  1. Localhost environment tunneled via ngrok (required as SCORM Cloud blocks non-HTTPS iframes).

  2. xAPI .zip exported using the Ngrok origin.

  3. Package launched in SCORM Cloud.

  4. Verified that UI node interactions dynamically populate the SCORM Cloud LRS Statement Viewer in real-time with valid JSON payloads.

Known Limitations:

• Because WyzQuests relies on an iframe strategy, testing strictly requires HTTPS tunneling (like Ngrok) when interfacing with strict modern LMS platforms.

• Mastery score is intentionally excluded from the xAPI package; teams requiring a strict pass/fail gate should use the SCORM 2004 export.

7. Maintenance & Support

Troubleshooting:

• Issue: "Statements are not appearing in the LRS."

  • Resolution: Inspect the Network tab in the browser. Verify the LMS is correctly appending ?endpoint=...&auth=...&actor=... to the launch URL. If the xapiConfig object in QuestPlayer is missing these, the statements will not fire.

• Issue: "Export fails with 400 Bad Request."

  • Resolution: Verify the frontend is passing version: "xapi" to the isolated /api/creator/export/xapi route, not the legacy SCORM route.

Changelog:

• 1.0 - Draft, Feature pushed to dev server after initial dev review, 06/06/2026