xAPI (Tin Can) Learning Records

Pro feature

🔶 Pro feature. Available in Learnomy Pro.

xAPI (also called Tin Can API) lets Learnomy report learning activity to your Learning Record Store (LRS). As students enrol, complete lessons, and answer quiz questions, Learnomy builds standard ADL xAPI statements and delivers them to the LRS you configure, so the record of what each learner did lives in your own analytics system.

What you can do

Send a learning record to any xAPI 1.0.3 LRS (Learning Locker, Watershed, Veracity, SCORM Cloud, and similar) as learners move through your courses.
Capture four lifecycle events automatically:
- Enrolled in a course (registered verb).
- Completed a lesson (completed verb, with the owning course as parent context).
- Quiz graded (passed or failed verb, with the scaled and raw score).
- Question answered (answered verb, with correctness and the learner's response).
Choose how learners are identified in the LRS: by email address, or by an anonymous site account id when you must not send email addresses off-site.
Send a one-off test statement to confirm the connection before real learning traffic starts.
Review a delivery log of failed sends and test sends, and retry a failed delivery from the admin screen.

xAPI settings and delivery log in Learnomy Settings > Settings (xAPI panel in the left navigation)

How to use it

Enable the xAPI module. Go to Learnomy Settings > Modules, find xAPI in the Integrations group, and turn it on. The module is off by default and is opt-in per site. Enabling it makes the xAPI card appear on the Integrations screen; disabling it removes the card again.
Open the xAPI card. Go to Learnomy Settings > Settings and open the Integrations section. The xAPI (Experience API) card is shown there.
Enter your LRS connection details from your LRS provider:
- LRS Endpoint - the xAPI endpoint URL. It must start with https://. Learnomy POSTs statements to {endpoint}/statements.
- LRS Key - the Basic-auth key (client id or username) your LRS issued.
- LRS Secret - the Basic-auth secret (password) your LRS issued. It is stored encrypted and is never shown again after saving. Leave it blank on a later save to keep the stored value.
Choose how learners are identified in the Identify learners by dropdown: email address (mbox) or site account (anonymous id).
Click Save Changes.
Send a test statement. In the Delivery log card below the settings, click Send test statement. Learnomy sends one statement to your LRS immediately and shows the result inline. Confirm the statement arrives in your LRS.
Let real activity flow. Once the connection is verified, statements are emitted automatically when students enrol, complete lessons, and answer quizzes. Delivery happens in the background, so a slow or unreachable LRS never delays the learner's page.

Settings & options

All fields live on the xAPI (Experience API) card in Learnomy Settings > Settings (xAPI panel in the left navigation). They are saved to the dedicated learnomy_xapi option group.

Field	Stored as	What it does
LRS Endpoint	`learnomy_xapi[endpoint]`	The LRS xAPI endpoint. Must be a valid `https://` URL; a bad value is rejected and the previous value is kept. Statements POST to `{endpoint}/statements`.
LRS Key	`learnomy_xapi[key]`	The Basic-auth key (client id / username) from your LRS.
LRS Secret	`learnomy_encrypted[xapi_secret]`	The Basic-auth secret (password). Stored encrypted and write-only; shows a Saved pill when one is on file. Leave blank to keep the saved value.
Identify learners by	`learnomy_xapi[actor_mode]`	`mbox` (email address) or `account` (site homepage plus the WordPress user id as an anonymous name). Defaults to `mbox`.

What each event sends

Learnomy event	Verb	Activity type	Extra data
Student enrolls in a course	`registered`	course	-
Lesson completed	`completed`	lesson	`completion: true`, parent course context
Quiz graded	`passed` or `failed`	assessment	`success`, `completion`, scaled + raw score, parent course context
Quiz question answered	`answered`	cmi.interaction	`success` (when known), the learner's `response`, parent course context

Every statement declares xAPI version 1.0.3 and uses the canonical ADL verb and activity-type IRIs, so a statement means the same thing in any LRS.

Delivery, retries, and the log

Delivery is asynchronous through Action Scheduler, so the learner's request never waits on the LRS network round trip.
If a send hits a timeout or a 5xx error, Learnomy retries with backoff: up to 4 attempts total (immediate, then after 5 minutes, 30 minutes, and 2 hours). Each retry sends the same statement id, so the LRS de-duplicates it.
A 4xx response (for example bad credentials) is treated as non-retryable and fails immediately.
After the final failed attempt, the statement is recorded in the audit log so it is never silently dropped. The Delivery log card lists the last 50 failed deliveries and test sends, with a Retry action on each failed row. Successful production statements are not listed here; they live in your LRS.

When it does nothing

If the module is enabled but no LRS Endpoint is saved, Learnomy emits nothing and skips every send, so a half-configured site never queues statements it cannot deliver.

For developers

Two filters and two admin-only REST routes are available.

learnomy_xapi_iri_base (filter) - override the identity base for activity IRIs. Defaults to home_url(). Set this once and keep it stable: it is the identity of every activity already recorded in the LRS, so changing it later forks the history.
```
add_filter( 'learnomy_xapi_iri_base', function ( string $base ) {
    return 'https://id.myinstitution.edu/learnomy';
} );
```

learnomy_xapi_statement (filter) - edit, enrich, or drop a single statement just before it is queued for delivery. Return null or an empty value to suppress emission for that event. Receives ( array|null $statement, string $event, array $ctx ).

add_filter( 'learnomy_xapi_statement', function ( $statement, $event, $ctx ) {
    // Drop question-level statements, keep enrol / lesson / quiz.
    if ( 'question_answered' === $event ) {
        return null;
    }
    return $statement;
}, 10, 3 );

REST routes (namespace learnomy-pro/v1, both gated to manage_options):
- POST /xapi/test - send a one-off test statement and return the result. Backs the Send test statement button.
- POST /xapi/retry - re-enqueue the statement stored on a failed-delivery log row (requires an audit_id). Backs the Retry row action.