TangyForm player to generate xAPI statement that comply with spec/norms

[mikedawson]

When a Tangerine form is submitted:

• There should be one xAPI statement for each answer provided; statement should follow the spec as per xAPI to SCORM cookbook
• Each question is a separate activity. If the form activityid is 'https://example.org/form1' then question id could be 'https://example.org/form1/question1' etc. The child (eg question) should be linked to the parent using statement parent context as per xAPI spec
• Statements are not sent to LRS until form is actually submitted.

[faridy-mahvish]

Hi @mikedawson

xAPI Statement Builder – Conceptual Plan
I'm working on designing a class named XAPIStatementBuilder which is aimed at generating xAPI (Experience API) statements based on user input interactions from dynamic forms. The main objective is to track user behavior and responses in a structured and standards-compliant way. The logic is modular and extensible. Here's the planned structure and flow:

Structure Overview

• Class: XAPIStatementBuilder
  • This class will encapsulate all logic to generate valid xAPI statements.

Core Components

1. Constructor

   • Initializes the builder with key metadata: actor, endpoint, and auth (authentication and identity for the xAPI endpoint).

2. Verb Generator (_generateVerb)

   • Determines the verb (answered or attempted) based on whether the input has a meaningful value or not.

3. Object Generator (_generateObject)

   • Builds the xAPI object field based on input type, tag type, and user-friendly label.
   • Supports various tag types like:
     • Text inputs, radio buttons, checkboxes, toggle switches, GPS, signatures, etc.
   • Constructs metadata like interactionType, choices, and descriptions.

4. Result Generator (_generateResult)

   • Forms the result part of the xAPI statement, including:
     • Whether the input was completed
     • Duration of activity
     • User's response
     • Extensions like raw input values

5. Statement Builder (buildStatements)

   • Loops through form inputs and assembles complete xAPI statements for each relevant user interaction.
   • Skips disabled or irrelevant fields.

6. Helper (_getInputValue)

   • Normalizes input values (strings, booleans, arrays) into a consistent format for xAPI.

How It Will Work

• The system will receive form data and metadata like form duration and submission status.
• Each form input will be evaluated:
  • Based on its value, we determine whether a user has "answered" or merely "attempted".
  • Input type and structure guide how we build the object and result portions of the statement.
• The final output is a structured list of xAPI statements ready to be sent to a Learning Record Store (LRS).

Goals and Benefits

• Compliance: Aligns with xAPI standards for learning analytics.
• Flexibility: Designed to support a wide range of input types and use cases.
• Extensibility: New input types and tracking logic can be added easily in future.

[mikedawson]

I think we need to follow the design pattern used in the code base now.

Each tangy form component now emits a TANGY_FORM_UPDATE event when its value changed (which is then captured by the tangy form component). I suggest adding that each component should similarly emit a TANGY_FORM_STATEMENT event with an xAPI statement.

This event could then be similarly captured so the statement is saved until the form is submitted. When the form is submitted, then the statements are sent to the LRS.

I do not think we should have one giant XAPIStatementBuilder class disconnected from the form components themselves (as suggested above).

[esurface]

I agree with this approach. Please proceed.