Разработка LMS-платформы с поддержкой xAPI (Experience API)

Поддержка xAPI (Experience API / Tin Can) в LMS

xAPI — современная замена SCORM. В отличие от SCORM, xAPI не требует iframe и работает через REST API к Learning Record Store (LRS). Записывает «statements» — утверждения вида «актор выполнил действие с объектом»: "Иван завершил урок Python", "Мария набрала 85 баллов в тесте".

Концепция xAPI Statement

{
  "actor": {
    "objectType": "Agent",
    "name": "Иван Иванов",
    "mbox": "mailto:[email protected]"
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/completed",
    "display": { "en-US": "completed", "ru-RU": "завершил" }
  },
  "object": {
    "objectType": "Activity",
    "id": "https://lms.example.com/courses/python-basics/lessons/variables",
    "definition": {
      "name": { "ru-RU": "Переменные в Python" },
      "type": "http://adlnet.gov/expapi/activities/lesson"
    }
  },
  "result": {
    "score": { "scaled": 0.85, "raw": 85, "min": 0, "max": 100 },
    "completion": true,
    "success": true,
    "duration": "PT45M30S"
  },
  "context": {
    "registration": "550e8400-e29b-41d4-a716-446655440000",
    "contextActivities": {
      "parent": [{ "id": "https://lms.example.com/courses/python-basics" }]
    }
  },
  "timestamp": "2026-03-28T10:30:00Z"
}

Собственный LRS (Learning Record Store)

LRS — это REST-сервис, принимающий и хранящий xAPI statements. Можно использовать готовые (SCORM Cloud, Learning Locker, ADL LRS) или написать свой:

import { Router } from 'express';
const xapi = Router();

// PUT/POST /xapi/statements — принять statement(ы)
xapi.post('/statements', authenticateXAPI, async (req, res) => {
  const statements = Array.isArray(req.body) ? req.body : [req.body];

  const ids = await Promise.all(
    statements.map(async (stmt) => {
      // Валидация обязательных полей
      if (!stmt.actor || !stmt.verb || !stmt.object) {
        throw new Error('Invalid xAPI statement: missing required fields');
      }

      // Добавить ID если нет
      if (!stmt.id) stmt.id = crypto.randomUUID();

      // Сохранить
      await db.xapiStatements.create({
        id: stmt.id,
        actor: stmt.actor,
        verb: stmt.verb,
        object: stmt.object,
        result: stmt.result ?? null,
        context: stmt.context ?? null,
        timestamp: stmt.timestamp ? new Date(stmt.timestamp) : new Date(),
        storedAt: new Date(),
      });

      // Обновить прогресс обучающегося
      await updateLearnerProgress(stmt);

      return stmt.id;
    })
  );

  res.status(200).json(ids);
});

// GET /xapi/statements — запросить statements
xapi.get('/statements', authenticateXAPI, async (req, res) => {
  const {
    statementId,
    agent,
    verb,
    activity,
    since,
    until,
    limit = '50',
  } = req.query;

  const statements = await db.xapiStatements.query({
    statementId: statementId as string,
    actor: agent ? JSON.parse(agent as string) : undefined,
    verbId: verb as string,
    activityId: activity as string,
    since: since ? new Date(since as string) : undefined,
    until: until ? new Date(until as string) : undefined,
    limit: Math.min(Number(limit), 500),
  });

  // xAPI требует заголовки X-Experience-API-Version
  res.setHeader('X-Experience-API-Version', '1.0.3');
  res.json({
    statements,
    more: '',  // URL для пагинации если есть больше
  });
});

Обновление прогресса из statements

async function updateLearnerProgress(stmt: XAPIStatement) {
  // Извлечь learner id
  const email = stmt.actor.mbox?.replace('mailto:', '') ??
    stmt.actor.account?.name;
  if (!email) return;

  const user = await db.users.findByEmail(email);
  if (!user) return;

  // Определить тип события по глаголу
  const verbId = stmt.verb.id;
  const activityId = stmt.object.id;

  const VERB_COMPLETED = 'http://adlnet.gov/expapi/verbs/completed';
  const VERB_PASSED = 'http://adlnet.gov/expapi/verbs/passed';
  const VERB_FAILED = 'http://adlnet.gov/expapi/verbs/failed';
  const VERB_ANSWERED = 'http://adlnet.gov/expapi/verbs/answered';
  const VERB_PROGRESSED = 'http://adlnet.gov/expapi/verbs/progressed';

  switch (verbId) {
    case VERB_COMPLETED:
    case VERB_PASSED:
      await db.lessonProgress.markCompleted(user.id, activityId, {
        score: stmt.result?.score?.scaled,
        duration: parseDuration(stmt.result?.duration),
        completedAt: new Date(stmt.timestamp ?? new Date()),
      });
      await checkCourseCompletion(user.id, activityId);
      break;

    case VERB_FAILED:
      await db.lessonProgress.markFailed(user.id, activityId, {
        score: stmt.result?.score?.scaled,
      });
      break;

    case VERB_ANSWERED:
      await db.quizAnswers.create({
        userId: user.id,
        questionId: activityId,
        score: stmt.result?.score?.raw,
        success: stmt.result?.success,
      });
      break;

    case VERB_PROGRESSED:
      const progress = stmt.result?.extensions?.[
        'https://w3id.org/xapi/video/extensions/progress'
      ];
      if (progress) {
        await db.lessonProgress.updateProgress(user.id, activityId, Number(progress));
      }
      break;
  }
}

Аутентификация LRS

xAPI использует Basic Auth или OAuth 2.0 для авторизации запросов от контента:

function authenticateXAPI(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith('Basic ')) {
    res.setHeader('WWW-Authenticate', 'Basic realm="xAPI LRS"');
    return res.status(401).end();
  }

  const [key, secret] = Buffer.from(authHeader.slice(6), 'base64')
    .toString()
    .split(':');

  // Верифицировать ключ/секрет приложения
  const app = lrsClients.find(c => c.key === key && c.secret === secret);
  if (!app) return res.status(401).end();

  req.lrsClient = app;
  next();
}

xAPI Launch — запуск контента без iframe

В отличие от SCORM, xAPI-контент запускается напрямую и сам отправляет statements через fetch:

// Генерация Launch URL с параметрами
function generateXAPILaunchUrl(
  courseUrl: string,
  userId: string,
  userEmail: string
): string {
  const params = new URLSearchParams({
    endpoint: `${process.env.APP_URL}/xapi/`,
    auth: `Basic ${Buffer.from(`${lrsKey}:${lrsSecret}`).toString('base64')}`,
    actor: JSON.stringify({
      objectType: 'Agent',
      name: userId,
      mbox: `mailto:${userEmail}`,
    }),
    registration: crypto.randomUUID(),
  });

  return `${courseUrl}?${params.toString()}`;
}

Аналитика через xAPI

LRS накапливает rich data о поведении обучающихся — можно строить детальную аналитику:

-- Средний балл по урокам
SELECT
  s.object->>'id' AS activity_id,
  s.object->'definition'->'name'->>'ru-RU' AS lesson_name,
  AVG((s.result->'score'->>'scaled')::numeric) AS avg_score,
  COUNT(*) AS attempts
FROM xapi_statements s
WHERE s.verb->>'id' = 'http://adlnet.gov/expapi/verbs/completed'
  AND s.result->'score' IS NOT NULL
GROUP BY 1, 2
ORDER BY avg_score;

Сроки

Базовый LRS с приёмом statements и обновлением прогресса — 1 неделя. С OAuth2, аналитикой и поддержкой xAPI Launch — ещё 3–5 дней.