Lesson-Apps mit dem Lesson-SDK

Eine Lesson-App ist eine eigene Anwendung, die im LMS als Lesson läuft. Der Schüler öffnet im Kurs eine Lesson vom Typ external, das LMS schickt ihn mit einem kurzlebigen Token zu deiner Adresse, und deine App liest darüber die Lesson, den Kurs, das Profil und den Fortschritt — und meldet zurück, wenn die Lesson bestanden ist.

Das Paket dazu ist @artim-academy/lms-lesson-sdk. Es ist ein Client für genau diese eine Strecke; alles andere am LMS erreicht man über die APIs dieses Produkts oder den MCP.

Der Ablauf

1. Ein Trainer meldet die App im LMS an (Trainer → Apps → New App) mit Namen, Startadresse und den Scopes, die sie braucht.
2. Ein Plattform-Admin gibt sie frei — im LMS selbst oder über Lesson-App freigeben.
3. Der Trainer bindet sie als Lesson vom Typ external in einen Kurs ein.
4. Öffnet ein Schüler diese Lesson zum ersten Mal, sieht er einen Autorisierungs-Screen mit genau diesen Scopes — einmal je Konto und Akademie.
5. Danach leitet das LMS ihn weiter, mit den Startparametern in der Adresse:

https://deine-app.example.com/lesson
  ?lms_token=…
  &lms_tenant_id=…
  &lms_course_id=…
  &lms_lesson_id=…
  &lms_client_id=…

Installation

npm install @artim-academy/lms-lesson-sdk

Nutzung

Im Browser holt sich der Client die Parameter selbst aus der Adresse:

"use client";
import { LmsLessonClient } from "@artim-academy/lms-lesson-sdk";

const lms = LmsLessonClient.fromCurrentUrl();

const context = await lms.getContext();   // App, Akademie, Lesson, Konto, Scopes
const lesson = await lms.getLesson();     // lesson:read
const user = await lms.getUser();         // user:profile
const progress = await lms.getProgress(); // progress:read

await lms.completeLesson();               // lesson:complete
lms.returnToLms();                        // zurück zur Lesson im LMS

Auf dem Server nimmt er sie als searchParams — die Form, in der Next.js sie an eine Seite gibt:

import { LmsLessonClient } from "@artim-academy/lms-lesson-sdk";

export default async function Page({ searchParams }: { searchParams: Record<string, string> }) {
  if (!LmsLessonClient.isLaunchRequest(searchParams)) return <p>Bitte über das LMS öffnen.</p>;

  const lms = LmsLessonClient.fromSearchParams(searchParams);
  const context = await lms.getContext();

  return <h1>Lesson {context.lessonId}</h1>;
}

fromUrl(url) gibt es für alles daneben; apiBaseUrl in den Optionen zeigt auf eine andere Umgebung, fetch auf eine eigene Implementierung.

Die Aufrufe

Alle sprechen /api/sdk/v1 des LMS mit dem Launch-Token als Bearer.

getReturnUrl(lmsBaseUrl?) baut die Adresse der Lesson im LMS, returnToLms(lmsBaseUrl?) navigiert im Browser dorthin.

Das Token

Es ist opak, nicht ein JWT: an genau eine Lesson und ein Konto gebunden, jederzeit widerrufbar, und es läuft nach zwei Stunden ab. Ein abgelaufenes Token antwortet mit 403 — im SDK ein LmsSdkError mit status === 403. Dann gehört der Schüler über returnToLms() zurück ins LMS; das nächste Öffnen der Lesson stellt ein frisches Token aus.

import { LmsSdkError } from "@artim-academy/lms-lesson-sdk";

try {
  await lms.completeLesson();
} catch (error) {
  if (error instanceof LmsSdkError && error.status === 403) lms.returnToLms();
  else throw error;
}

Halte das Token nicht länger, als der Aufruf dauert, und schicke es nirgendwo anders hin: es ist der Ausweis eines Schülers, nicht der deiner App.

Wenn nichts passiert