xAPI Tracking

  1. Overview
  2. Hand Off Documentation
  3. Deliver (Export)
  4. xAPI Tracking

Feature: xAPI Export and Tracking Integration
Feature Owner: Jethro Magdaleno Lagmay
Module: Deliver
Priority: High
Sprint: #12
Date: June 30, 2026

EXECUTIVE SUMMARY

What is this feature? This feature introduces xAPI (Tin Can) compatibility to the WyzQuests platform. It allows creators to export a standard tincan.xml ZIP package and enables the Next.js QuestPlayer to asynchronously fire standard xAPI JSON statements (e.g., "actor answered decision") directly to an external Learning Record Store (LRS) when launched via a third-party LMS.

Why does it matter? Modern enterprise and educational clients require granular, event-driven learning analytics that SCORM 1.2/2004 cannot provide. Supporting xAPI makes WyzQuests a viable authoring tool for organizations utilizing modern LRS ecosystems.

What’s the MVP scope?

  • Backend generation of tincan.xml packages without legacy SCORM JS wrappers.

  • Frontend separation of Export API routes (/api/creator/export/xapi).

  • Dynamic URL parameter extraction (endpoint, auth, actor) via the index.html iframe bridge.

  • Client-side tracking trigger on Decision Nodes (mapping choices to the answered verb).

1. USER PAIN POINT & SOLUTION

Current State (Without Feature) WyzQuests only exports SCORM packages, which limits tracking to a single pass/fail "Mastery Score" and basic completion statuses.

Pain Point

  • Emotional: Creators feel limited by the lack of insight into how learners are navigating their branching scenarios.

  • Functional: External LMSs cannot track granular decision-making inside a WyzQuests iframe.

  • Business Impact: Loss of potential enterprise clients who mandate xAPI/cmi5 compliance for their internal training stacks.

Future State (With Feature) Creators can export an xAPI package. When learners play the quest in an LMS, every decision node choice fires a real-time tracking statement back to the host organization's LRS.

Marketing Hook "Unlock granular learner analytics. Export your WyzQuests directly to your xAPI-compliant Learning Record Store and track every decision your learners make in real-time."

2. 4D FRAMEWORK MAPPING

Diagnose: Client LRS systems cannot read iframe interactions without standard xAPI credential passing and statement formatting.
Design: Split the export architecture (SCORM vs. xAPI). Hide mastery score for xAPI. Use window.location.search to pass credentials safely to the Next.js client.
Develop: Implemented /api/creator/export/xapi route, generateTinCanManifest template, and sendXAPIStatement fetch wrapper in QuestPlayer.tsx.
Deliver: Tested end-to-end via SCORM Cloud and Ngrok secure tunneling.

3. USER FLOWS

Entry Point

  1. Creator: Quest Editor -> Public Share Modal -> Export Tab.

  2. Learner: External LMS Dashboard -> Click Launch -> Loads WyzQuests Iframe.

Success Criteria

  • Creator successfully downloads a valid .zip containing tincan.xml and index.html.

  • Learner interactions fire HTTP 200 POST requests to the external LRS.

Main Flow (Happy Path)

  1. Creator selects "xAPI" in the Export modal (Mastery Score hides).

  2. Creator clicks "Export Quest", ZIP downloads.

  3. Creator uploads ZIP to SCORM Cloud / LMS.

  4. Learner launches course; LMS appends ?endpoint=...&auth=... to index.html.

  5. index.html passes parameters into the QuestPlayer iframe.

  6. Learner clicks a choice on a Decision Node.

  7. QuestPlayer fires an asynchronous statement to the LRS endpoint.

Edge Cases

  • LMS does not pass credentials: If launched without URL params, QuestPlayer silently aborts tracking to prevent UI blocking or console errors.

  • Network Failure: If the LRS is down, the try/catch in sendXAPIStatement catches the error silently so the learner can still progress in the visual canvas.

Decision Points

  • Export Modal: Route to /api/creator/export/xapi vs /api/creator/export/single-sco.

4. INFORMATION ARCHITECTURE

Primary Information (Always visible)

  • Export Options Dropdown (SCORM 1.2, SCORM 2004, xAPI).

  • Export Button.

Secondary Information

  • Mastery Score Input (Conditionally visible: Only shows for SCORM types, hidden for xAPI).

Tertiary Information (Hidden until needed)

  • Loading spinners / Exporting state.

Actions

  • Primary CTA: Export Quest.

  • Secondary Actions: Select Version.

5. WIREFRAMES

N/A

6. WIREFLOWS

N/A

7. PROTOTYPE

Already synced in the development server.

8. BACKEND SCHEMA

Database Tables

  • No new database migrations required. Operates on existing quests and canvas_metadata schemas.

Constants / Enums

  • XAPI_EXPORT: Added to constants/export.ts to manage dropdown state and API payload validation.

9. API ENDPOINTS

Endpoint 1: Generate xAPI Package

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

  • Auth: Requires valid user session (Supabase).

  • Payload: { "questId": "uuid", "version": "xapi" }

  • Response: 200 OK (application/zip binary buffer).

  • Logic: Validates ownership, fetches quest data, generates tincan.xml and modified index.html, streams ZIP buffer to client.

10. DATA REQUIREMENTS

Frontend Needs

  • Quest ID and Export Version from the UI form state.

  • xapiConfig (Extracted from URL search params on app/scorm/[questID]/page.tsx).

API Calls Frontend Will Make

  • Internal: /api/creator/export/xapi

  • External: POST {xapiConfig.endpoint}/statements (Fired directly to host LRS).

Caching Strategy

  • Cache-Control: no-store applied to the ZIP export response to prevent downloading stale packages.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

  • Standard index utilization on questId during the export fetch.

API Response Time

  • ZIP generation occurs in memory using jszip (Node.js buffer). Expect < 1000ms response time for standard quests.

Frontend Tracking Impact

  • xAPI statements are fired asynchronously (fetch without await blocking the UI state update). The learner experiences zero UI lag when clicking a decision, regardless of LRS network latency.

12. SECURITY & AUTHORIZATION

Who can access this feature?

  • Export: Authenticated quest creators/owners.

  • Tracking: Any learner launching the package via a secure LMS.

Authorization Logic

  • Export route utilizes standard authenticateUser() and questChecker() helpers.

  • Client-side tracking utilizes the Basic or Bearer token provided dynamically by the external LRS via the auth URL parameter.

Data Validation

  • Strict Zod validation omitted for Mastery Score when mode === XAPI_EXPORT.XAPI.

13. ERROR HANDLING

  • Export Failures: Catches JSON error payloads from the backend and surfaces them via toast.error().

  • Missing LRS Parameters: The handleChoiceSelect function requires xapiConfig?.endpoint, auth, and actor to be truthy. If false, it acts as a silent return.

  • Invalid Actor Format: parseXAPIActor() safely falls back to a generic anonymous user if the LRS provides a malformed actor string.

14. TESTING CHECKLIST

Happy Path

  • [x] Select xAPI in Export Modal, verify Mastery Score hides.

  • [x] Export ZIP, verify tincan.xml is present and SCORM JS files are absent.

  • [x] Tunnel localhost via Ngrok (ngrok http 3000).

  • [x] Export Ngrok-based ZIP and upload to SCORM Cloud.

  • [x] Launch course, click decision nodes, verify answered statements appear in LRS Statement Viewer.

Edge Cases

  • [x] Attempt to submit export form with SCORM selected but no Mastery Score (Should block).

  • [x] Launch xAPI course outside of an LMS (e.g., standard web preview). Verify UI does not crash and no failed network requests occur.

15. OPEN QUESTIONS

  • None at this time.

16. OUT OF SCOPE

  • Full cmi5 specification packaging.

  • Tracking standard canvas clicks, slide views, or dwell time (focus is strictly on Decision Node answered interactions).

  • Building an internal LRS dashboard within WyzQuests.

17. SUCCESS METRICS

  • Zero 500 errors on the /api/creator/export/xapi endpoint.

  • Successful validation of WyzQuests packages inside standard LMS environments (SCORM Cloud, Canvas, Moodle).

18. DEPENDENCIES

This feature depends on:

  • External LRS supporting standard xAPI 1.0.3 POST requests.

  • Host LMS correctly passing endpoint, auth, and actor URL parameters to the launch file.

These features depend on this:

  • Future branching logic analytics integrations.

19. TIMELINE & OWNERSHIP

Implemented: June 2026
Owner: Jethro Magdaleno Lagmay

Document Version

v1.0 - Initial Document
v1.1 - Minor Changes

Written by Jupiter Last updated July 1, 2026
Was this article helpful?