Metrics, progress and analytics

1. Tracking data sources

During playback, P2LRN exposes four types of information for different purposes: resume status, scores, events, and progression.

2. Integration architecture

The Player remains independent of the host database. The integrating application provides the identity of the user and the attempt; Host Adapter matches that private data with the portable identifiers exposed by P2LRN.

Identity, registration, group, call and attempt belong to the integrating platform. They are not stored within the .p2lrn and P2LRN does not impose its data model.

3. Context and identification of activities

He context The Player uses package and graph identifiers. Combining them allows each tracking data to be associated with the exact version of the content without introducing private LMS identifiers into the package.

A robust persistence key typically combines learnerId and attemptId of the platform with packageId, contentRoot, entityId and the surface (rendererId, profile or runtime).

4. Integration via Host Adapter

The following example separates the private platform data from the P2LRN portable contract. currentUser, currentAttempt and learningApi belong to the integrating application; The Player only invokes the functions defined by the Host Adapter.

const session = Object.freeze({
  learnerId: currentUser.id,
  attemptId: currentAttempt.id,
});

function metricKey(context) {
  return {
    learnerId: session.learnerId,
    attemptId: session.attemptId,
    packageId: context.packageId,
    contentRoot: context.contentRoot,
    entityId: context.entityId ?? null,
    surface:
      context.profile ??
      context.rendererId ??
      context.runtime ??
      'package',
  };
}

const adapter = P2LRN.createHostAdapter({
  async loadState(context) {
    return learningApi.loadState(metricKey(context));
  },

  async saveState(state, context) {
    await learningApi.saveState(metricKey(context), state);
  },

  async reportScore(score, context) {
    await learningApi.saveScore(metricKey(context), score);
  },

  async emitEvent(event, context) {
    await learningApi.appendEvent({
      ...metricKey(context),
      event,
    });
  },
});

document.querySelector('p2lrn-player').adapter = adapter;

5. Callback contract

6. Canonical structure of events

All persistable events share the same envelope. He payload changes depending on the type of event and context allows it to be attributed to the corresponding activity.

{
  "schema": "https://p2lrn.org/schema/runtime-event/1",
  "version": "1",
  "type": "p2lrn:score",
  "timestamp": "2026-10-16T08:30:00.000Z",
  "context": {
    "packageId": "urn:uuid:...",
    "contentRoot": "sha256:...",
    "entityId": "urn:uuid:...",
    "resourceId": "urn:uuid:...",
    "representationId": "urn:uuid:...",
    "rendererId": "https://p2lrn.org/renderer/questionnaire/standard"
  },
  "payload": {
    "graded": true,
    "raw": 8,
    "max": 10,
    "normalized": 0.8
  }
}

In DOM listeners, the payload fields also appear directly in event.detail and the full wrap is available in event.detail.event. In HostAdapter.emitEvent() the canonical event is received directly.

7. Data available in quizzes and games

Quizzes and quiz-based games share the same session. The contract allows you to obtain answers, progress, time, attempts, final score and detail per question without depending on the visible interface.

Native punctuation has this format. normalized goes from 0 to 1 when the correction is automatic; if the correction mode belongs to the host, graded es false and normalized es null.

{
  "graded": true,
  "raw": 8,
  "max": 10,
  "normalized": 0.8,
  "questions": [
    {
      "questionId": "q1",
      "graded": true,
      "correct": true,
      "hits": 1,
      "errors": 0,
      "pointsAwarded": 2,
      "pointsPossible": 2
    }
  ]
}

The details of successes, errors, points obtained and unanswered questions are obtained through score.questions and the status of responses. The visible interface should not be used as a source to reconstruct this data.

8. Monitoring data in SCORM 1.2 and SCORM 2004

SCORM maintains its CMI model. P2LRN preserves that state and delivers it via saveState and p2lrn:statechange. The object contains state.values; the exact keys depend on the version and what the SCO actually writes.

P2LRN deriva reportScore when doing Commit or Terminate if there is a usable note and it has changed. For SCORM 2004 use first cmi.score.scaled; if it does not exist, you can normalize raw / max. The field passed comes out of cmi.success_status in 2004 or cmi.core.lesson_status in 1.2.

9. Tracking data in H5P and xAPI

H5P communicates status for resume and can also issue xAPI. P2LRN forwards each statement as p2lrn:xapi and, when it contains a result, it derives a common score so that the integrating platform can obtain the basic score without interpreting each type of H5P content.

10. Course Progression Status

The progression uses a state separate from the internal states of each activity. The Player recalculates it from rendered, completion and scoring, saves it using the Host Adapter and outputs p2lrn:progressionchange when it changes.

{
  "version": "p2lrn-progression-state/1",
  "entities": {
    "urn:uuid:activity-1": {
      "viewed": true,
      "completed": true,
      "passed": true,
      "scorePercent": 82.5,
      "updatedAt": "2026-10-16T08:30:00.000Z"
    }
  }
}

p2lrn:rendered you can mark an activity as viewed; p2lrn:complete the completed mark; the scores provide passed and scorePercent. Then they apply required, gateFollowing, completionRequirement, minScore and unlockWhen.

11. Persistence model

Persistence typically separates the resume snapshot from the analytic history. The physical scheme belongs to the integrating platform; Separation by responsibility avoids mixing data with different life cycles.

To safely resume, the key must include contentRoot. If the content changes, the platform can migrate the state or initiate a compatible attempt instead of silently applying a snapshot of another version.

12. High frequency event management

High frequency events should not automatically become a persistent write for each change. p2lrn:timeupdate, responses and successive commits can be grouped according to analytics requirements.

• saveState preserves the last resume snapshot and does not replace an event history.
• Temporal analytics can be persisted asynchronously or in batches from emitEvent.
• The event includes timestamp; For auditing, it is also advisable to add a receivedAt generated by the server.
• The business session time should also be measured from the opening and closing of the attempt on the server, without depending solely on the browser's clock.
• CMI times published by SCO can be maintained in SCORM; in timed quizzes, the timing status; in H5P, xAPI durations should be treated as content-generated data.

13. Retries, duplicates, and idempotency

emitEvent It is delivered in order within a single Adapter, but the P2LRN event does not define a durable database identifier. When the transport can retry requests, the server must use its own ingestion key.

A common strategy is to generate an identifier upon receiving the event and, when deterministic deduplication is required, combine intent + type + timestamp + context + payload hash. The exact policy depends on whether analytics should preserve legitimate replays.

14. Common integration cases

15. Privacy and trust limits

The P2LRN package is portable and should not contain the learner's personal history. Host Adapter belongs to the trusted context of the host. Content events can describe the activity performed, but identity, registration, intent, permissions and final authority belong to the integrating platform.

The reference of Events documents the contract for each event; Progress describes the termination rules and Integration explains the connection with the platform services.

Rich pedagogical analytics

In addition to status, grade and completion, the native runtime allows you to observe the pedagogical journey with semantic events that do not depend on the visible HTML.

The platform can combine these events with contentRoot, entityId, intent, and host user to build engagement, resumption, collaboration, and content usage metrics without introducing those private identifiers into the .p2lrn.

Learning events and active time API

The Web SDK alpha.11 can project runtime events to an ordered learning flow without changing the envelope p2lrn:*.

Active time is opt-in telemetry; It does not by itself substitute a pedagogical rule, an official note or an external temporal authority.

P2LRN Analytics

When you need to query these metrics for many learners and courses, P2LRN Analytics provides an embeddable panel via CDN or NPM. Keeps observed activity and Host authoritative notes separate.