Métricas, progreso y analítica

1. Fuentes de datos de seguimiento

Durante la reproducción, P2LRN expone cuatro tipos de información con finalidades diferentes: estado de reanudación, puntuaciones, eventos y progresión.

2. Arquitectura de integración

El Player permanece independiente de la base de datos del host. La aplicación integradora aporta la identidad del usuario y del intento; Host Adapter relaciona esos datos privados con los identificadores portables expuestos por P2LRN.

Identidad, matrícula, grupo, convocatoria e intento pertenecen a la plataforma integradora. No se almacenan dentro del .p2lrn y P2LRN no impone su modelo de datos.

3. Contexto e identificación de actividades

El context del Player utiliza identificadores del paquete y del grafo. Su combinación permite asociar cada dato de seguimiento con la versión exacta del contenido sin introducir identificadores privados del LMS en el paquete.

Una clave de persistencia robusta suele combinar learnerId y attemptId de la plataforma con packageId, contentRoot, entityId y la superficie (rendererId, profile o runtime).

4. Integración mediante Host Adapter

El siguiente ejemplo separa los datos privados de la plataforma del contrato portable de P2LRN. currentUser, currentAttempt y learningApi pertenecen a la aplicación integradora; el Player sólo invoca las funciones definidas por 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. Contrato de los callbacks

6. Estructura canónica de los eventos

Todos los eventos que pueden persistirse comparten la misma envoltura. El payload cambia según el tipo de evento y context permite atribuirlo a la actividad correspondiente.

{
  "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
  }
}

En listeners DOM, los campos del payload también aparecen directamente en event.detail y la envoltura completa está disponible en event.detail.event. En HostAdapter.emitEvent() se recibe directamente el evento canónico.

7. Datos disponibles en cuestionarios y juegos

Los cuestionarios y los juegos basados en cuestionario comparten la misma sesión. El contrato permite obtener respuestas, avance, tiempo, intentos, puntuación final y detalle por pregunta sin depender de la interfaz visible.

La puntuación nativa tiene este formato. normalized va de 0 a 1 cuando la corrección es automática; si el modo de corrección pertenece al host, graded es false y 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
    }
  ]
}

El detalle de aciertos, errores, puntos obtenidos y preguntas sin responder se obtiene mediante score.questions y el estado de respuestas. La interfaz visible no debe utilizarse como fuente para reconstruir estos datos.

8. Datos de seguimiento en SCORM 1.2 y SCORM 2004

SCORM mantiene su modelo CMI. P2LRN conserva ese estado y lo entrega mediante saveState y p2lrn:statechange. El objeto contiene state.values; las claves exactas dependen de la versión y de lo que el SCO realmente escriba.

P2LRN deriva reportScore al hacer Commit o Terminate si hay una nota utilizable y ha cambiado. Para SCORM 2004 usa primero cmi.score.scaled; si no existe, puede normalizar raw / max. El campo passed sale de cmi.success_status en 2004 o de cmi.core.lesson_status en 1.2.

9. Datos de seguimiento en H5P y xAPI

H5P comunica estado para reanudación y también puede emitir xAPI. P2LRN reenvía cada statement como p2lrn:xapi y, cuando contiene un resultado, deriva una puntuación común para que la plataforma integradora pueda obtener la nota básica sin interpretar cada tipo de contenido H5P.

10. Estado de progresión del curso

La progresión utiliza un estado separado de los estados internos de cada actividad. El Player lo recalcula a partir de rendered, finalización y puntuación, lo guarda mediante Host Adapter y emite p2lrn:progressionchange cuando cambia.

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

p2lrn:rendered puede marcar una actividad como vista; p2lrn:complete la marca completada; los scores aportan passed y scorePercent. Después se aplican required, gateFollowing, completionRequirement, minScore y unlockWhen.

11. Modelo de persistencia

La persistencia suele separar el snapshot de reanudación del historial analítico. El esquema físico pertenece a la plataforma integradora; la separación por responsabilidad evita mezclar datos con ciclos de vida distintos.

Para reanudar con seguridad, la clave debe incluir contentRoot. Si el contenido cambia, la plataforma puede migrar el estado o iniciar un intento compatible en lugar de aplicar silenciosamente un snapshot de otra versión.

12. Gestión de eventos de alta frecuencia

Los eventos de alta frecuencia no deben convertirse automáticamente en una escritura persistente por cada cambio. p2lrn:timeupdate, respuestas y commits sucesivos pueden agruparse según los requisitos de analítica.

• saveState conserva el último snapshot de reanudación y no sustituye a un historial de eventos.
• La analítica temporal puede persistirse de forma asíncrona o por lotes a partir de emitEvent.
• El evento incluye timestamp; para auditoría conviene añadir además un receivedAt generado por el servidor.
• El tiempo de sesión de negocio debe medirse también a partir de la apertura y cierre del intento en el servidor, sin depender únicamente del reloj del navegador.
• En SCORM pueden conservarse los tiempos CMI publicados por el SCO; en cuestionarios temporizados, el estado de temporización; en H5P, las duraciones xAPI deben tratarse como datos generados por el contenido.

13. Reintentos, duplicados e idempotencia

emitEvent se entrega en orden dentro de un mismo Adapter, pero el evento P2LRN no define un identificador durable de base de datos. Cuando el transporte pueda reintentar peticiones, el servidor debe utilizar una clave de ingestión propia.

Una estrategia habitual consiste en generar un identificador al recibir el evento y, cuando se requiera deduplicación determinista, combinar intento + tipo + timestamp + contexto + hash del payload. La política exacta depende de si la analítica debe conservar repeticiones legítimas.

14. Casos de integración habituales

15. Privacidad y límites de confianza

El paquete P2LRN es portable y no debe contener el historial personal del alumno. Host Adapter pertenece al contexto de confianza del host. Los eventos de contenido pueden describir la actividad realizada, pero identidad, matrícula, intento, permisos y autoridad final pertenecen a la plataforma integradora.

La referencia de Eventos documenta el contrato de cada evento; Progresión describe las reglas de finalización y Integración explica la conexión con los servicios de la plataforma.

Analítica pedagógica enriquecida

Además de estado, nota y finalización, el runtime nativo permite observar el recorrido pedagógico con eventos semánticos que no dependen del HTML visible.

La plataforma puede combinar estos eventos con contentRoot, entityId, intento y usuario del host para construir métricas de participación, reanudación, colaboración y uso del contenido sin introducir esos identificadores privados en el .p2lrn.

API de learning events y tiempo activo

La Web SDK de alpha.11 puede proyectar los eventos runtime a un flujo de aprendizaje ordenado sin cambiar el sobre p2lrn:*.

El tiempo activo es telemetría opt-in; no sustituye por sí solo una regla pedagógica, una nota oficial o una autoridad temporal externa.

P2LRN Analytics

Cuando necesitas consultar estas métricas para muchos alumnos y cursos, P2LRN Analytics proporciona un panel embebible por CDN o NPM. Mantiene separadas la actividad observada y las notas autoritativas del Host.