Dokumentation
Anleitung

PDF mit Overlays – Ergebnisse mit xAPI senden

Eigene HTML-Übungen im Edupool-Reader anbinden: Startkontext nutzen, xAPI-Ergebnisse senden und abrufen sowie die Zuordnung zur Auswertung vorbereiten.

Auf dieser Seite

Diese Anleitung richtet sich an Entwickler eigener HTML-Übungen. Sie beschreibt das Senden von Ergebnissen aus einem online geöffneten PDF-Overlay im Edupool-Reader. Avallain ist dafür nicht erforderlich. Ein beliebiges xAPI-Paket lässt sich aber nicht allein durch seinen Upload automatisch in die Edupool-Auswertung integrieren.

Übertragung und Auswertung sind getrennte Schritte

Ein Learning Record Store (LRS) speichert Lernereignisse. xAPI beschreibt deren Datenformat und Übertragung. Edupool ergänzt beim Empfang die Teilnehmeridentität und das Produkt aus dem autorisierten Startkontext.

Für die Anzeige im Buch, in der Kursauswertung oder in einer Aufgabe benötigt Edupool außerdem eine eindeutige Zuordnung der Übungskennungen zu den Inhalten. Ein erfolgreicher HTTP-Aufruf allein belegt diese Zuordnung nicht. Auch die Overlay-Felder taskID, skills und exerciseSubcategory richten keine Ergebnisübertragung ein.

Die vorhandene HTML-Anleitung Eigene HTML-Übungen aus der PDF öffnen enthält bewusst eine Übung ohne Übertragung. Das folgende Beispiel ist eine separate Erweiterung; diese Eigenschaft des bisherigen Pakets bleibt bestehen.

Beispielpaket und Datenschutz

Vollständiges Online-xAPI-Beispielpaket herunterladen

Das Paket basiert auf „Hallo, Viertel!“ aus Materialien nach Aufgaben bündeln. Die Café-Übung prüft eine Auswahlfrage. Erst ein zusätzlicher Klick auf Ergebnis an Edupool senden überträgt Punkte und Antwort. Es werden weder Aufgaben abgegeben noch Lehrkraftnoten gesetzt. Verwenden Sie für Tests ein Testkonto; übertragene Ergebnisse können dessen Lernstand verändern.

Die Übung enthält keine Zugangsdaten. Das bedeutet nicht, dass die Ergebnisse anonym sind: Der Reader-Zugang ordnet sie serverseitig dem angemeldeten Konto zu. Verwenden Sie keine Namen, E-Mail-Adressen oder vertraulichen Freitexte in Activity-IDs, Titeln oder Antworten. Klären Sie vor produktivem Einsatz Informationspflichten und Aufbewahrung der Lerndaten.

1. Den Startkontext an die Übung übergeben

Laden Sie das entpackte Paket in ein separates, ausgeblendetes Testmedium. Die Einrichtung von PDF, JSON und Abspieltyp steht in PDF mit Overlays im Marketplace einrichten. Die PDF bleibt die Index-Datei. Eine Abspielberechtigung ist zusätzlich zu den Uploadrechten erforderlich.

Wählen Sie für das Medium den Abspieltyp PDF mit Overlay. Ein gültiger Abspiellink und eine gewählte Index-PDF allein reichen dafür nicht aus.

Der relevante Overlay-Eintrag lautet:

{
  "type": "link",
  "pageNum": 2,
  "destX": 18.4,
  "destY": 23.5,
  "hyperlinkObj": "exercises/cafe/index.html?endpoint=",
  "description": "Übung – höflich bestellen (xAPI)",
  "taskID": "L2-A1",
  "exerciseSubcategory": "Übung",
  "skills": ["Lesen"]
}

Der leere Parameter ?endpoint= ist hier ein Platzhalter für den Online-Reader. Dieser ersetzt ihn beim Ausliefern durch den zur Sitzung gehörenden LRS-Endpunkt. Öffnen Sie die Übung aus dem Buch, nicht direkt aus der Dateiverwaltung.

Im HTML lesen Sie den Parameter aus:

const endpoint = new URLSearchParams(location.search).get('endpoint');

Ohne gültigen Startkontext darf die Übung lokal prüfen, aber nicht senden. Der Beispielcode deaktiviert dafür den Senden-Button.

Ohne Reader-Start: Antwort korrekt, Übertragung deaktiviert

Speichern Sie keine konkrete Sitzungsadresse im Produkt und geben Sie sie nicht in Screenshots oder Supporttickets weiter. Der Endpoint ist vertraulich. Der bestehende Online-Reader ersetzt beim Einfügen des Endpoints weitere Query-Parameter; legen Sie notwendige Übungskonfiguration daher in der HTML-Datei oder einer separaten Produktdatei ab. Externe Websites und beliebige fremde LRS-Endpunkte sind nicht Teil dieses Beispiels.

2. Ein Ergebnis als Statement erstellen

Das folgende Beispiel ist ein Edupool-Gateway-Vertrag, nicht die Minimalvorlage für jeden beliebigen xAPI-LRS. Insbesondere ergänzt das Gateway den hier noch unvollständigen Actor.

const statement = {
  id: crypto.randomUUID(),
  timestamp: new Date().toISOString(),
  actor: { objectType: 'Agent' },
  verb: { id: 'http://adlnet.gov/expapi/verbs/answered' },
  object: {
    id: 'antares_halloviertelcafe01/0',
    objectType: 'Activity',
    definition: {
      name: { und: 'Hallo, Viertel! – Im Café bestellen' }
    }
  },
  result: {
    score: { raw: 1, min: 0, max: 1, scaled: 1 },
    response: 'b'
  }
};
Feld Bedeutung im bestehenden Vertrag
id Neue UUID für ein neues Ereignis. Beim erneuten Senden desselben Ereignisses dieselbe UUID und denselben Inhalt behalten.
timestamp Zeitpunkt des Ereignisses als ISO-Zeitstempel.
actor Wird aus dem autorisierten Startkontext ersetzt. Keine eigene Teilnehmeridentität einschleusen.
verb.id Die aktuelle Ergebnisanzeige liest answered. Nur completed oder passed zu senden reicht dafür nicht.
object.id Stabile Kennung der Interaktionsseite. Nicht bei jedem Start neu erzeugen und nicht nur den veränderlichen Titel verwenden.
definition.name.und Lesbarer Titel. Die aktuelle Auswertung verwendet insbesondere und.
result.score Tatsächliche Punkte; max positiv und scaled konsistent zu den Punkten angeben. Ein echtes Ergebnis mit null Punkten ist gültig. Fehlende Ergebnisse nicht als null Punkte erfinden.
result.response Optionale Antwort als String; im Beispiel nur der Antwortcode b.

Optional kann result.duration eine ISO-8601-Dauer wie PT12S enthalten. Definieren Sie, was Sie messen. Verstrichene Zeit einschließlich Pausen ist keine aktive Lernzeit.

Der aktuelle Online-Zugang ergänzt relative Activity-IDs unter der historischen Basis https://lrs.edupool.cloud/; absolute HTTP(S)-IDs bleiben erhalten. Er setzt die Produktkennung in context.extensions["http://antares.net/extension/bookID"] aus der Sitzung und erhält andere Kontext-Erweiterungen. Die Metadatenzuordnung der Auswertung hat zusätzliche Anforderungen an die Kennungen, siehe Abschnitt 4. Diese Regeln sind Edupool-spezifisch, nicht allgemeine xAPI-Vorgaben.

3. Das Statement senden

Das Beispiel sendet per POST ein Array, hier mit einem Statement. Der Zugang unterstützt außerdem einzelne Statement-Objekte; für xAPI-PUT verwenden Sie ein einzelnes Objekt mit passender statementId.

const response = await fetch(endpoint.replace(/\/+$/, '') + '/statements', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Experience-API-Version': '1.0.3'
  },
  body: JSON.stringify([statement])
});
if (!response.ok) {
  throw new Error('Übertragung fehlgeschlagen: HTTP ' + response.status);
}

Verwenden Sie nur den vom Reader gelieferten Endpoint. Hinterlegen Sie weder LRS-Benutzername und Passwort noch einen festen Authorization-Header im ausgelieferten HTML. Ein aus einem Anbieterbeispiel kopiertes Authorization: undefined ist ebenfalls keine Zugangskonfiguration.

Das vollständige Paket ergänzt eine Zeitbegrenzung, verhindert paralleles Senden und behält bei Fehlern das vorbereitete Statement für eine Wiederholung. Ein Timeout kann nach erfolgreicher Speicherung eintreten. Deshalb nicht automatisch eine neue Statement-ID erzeugen und denselben Versuch als neues Ereignis senden.

Gespeicherte Statements zurücklesen

Zum Nachweis der Speicherung können Sie ein eigenes Statement aus demselben Teilnehmer- und Buchkontext abrufen. statementId ist die beim Senden vergebene UUID, keine neue Kennung:

const url = new URL(endpoint.replace(/\/+$/, '') + '/statements');
url.searchParams.set('statementId', statement.id);
const storedResponse = await fetch(url, {
  headers: { 'X-Experience-API-Version': '1.0.3' },
  cache: 'no-store'
});
if (!storedResponse.ok) {
  throw new Error('Abruf fehlgeschlagen: HTTP ' + storedResponse.status);
}
const storedStatement = await storedResponse.json();

Fügen Sie beim Einzelabruf keine Filter wie agent oder activityId hinzu. Das Gateway prüft die zurückgelieferte ID, die aktuelle Teilnehmeridentität einschließlich einer etwaigen Reset-Generation und die Produktkennung vor der Ausgabe. Eine andere Buchsitzung darf das Statement nicht lesen. voidedStatementId ist als alternativer Selektor vorgesehen; beide Selektoren zusammen, ungültige IDs, HEAD und Multipart-Anhänge sind für diesen Einzelabruf nicht zugelassen.

activities/state ist eine andere xAPI-Schnittstelle: Sie dient dem Wiederaufnahmezustand einer Übung und verwendet activityId, agent und stateId. Ein gespeichertes Ergebnis-Statement stellt diesen Zustand nicht automatisch wieder her. Die Aussage „Statement abrufbar“ ist deshalb kein Nachweis für eine vollständige Wiederaufnahmefunktion.

Bei HTTP 400 prüfen Sie die UUID und die Anfrageparameter. HTTP 403 bedeutet, dass der aktuelle Kontext keinen Zugriff erlaubt; HTTP 404 bedeutet, dass das Statement nicht gefunden wurde. Setzen Sie für einen Abruf ohne eigenen Cache keine bedingten Anfrageheader: Eine Antwort mit HTTP 304 enthält keinen Statement-Inhalt.

Falsche Antwort mit 0/1 Punkten und bestätigter Übertragung

4. Die Anzeige in Edupool gesondert einrichten

Stimmen Sie die Metadatenübernahme mit Ihrer technischen Ansprechperson ab. Im derzeitigen automatischen Importpfad ist diese Übernahme auf Hueber eingeschränkt. Für andere Produzenten ist ein eigener abgestimmter Import beziehungsweise eine Erweiterung nötig. Ein Upload von tincan.xml allein ist dafür keine allgemeine Zusage.

Der bestehende Auswerter erwartet eine Kennung nach dem Muster präfix_übungsschlüssel/seite. Im Beispiel wird aus antares_halloviertelcafe01/0 der Übungsschlüssel halloviertelcafe01. Verwenden Sie einen stabilen, eindeutigen Schlüssel ohne weitere Unterstriche. Die vollständige Seitenkennung bleibt für einzelne Ergebnisse erhalten.

Für die Metadatenzuordnung werden zusätzlich die importierte Übungskennung, der genaue relative Paketpfad unter exercises/ und die Platzierung in der Buch-JSON benötigt. Lektionen und Kompetenzen kommen aus den Inhaltsmetadaten. Eine Ähnlichkeit von Titeln ersetzt diese Zuordnung nicht.

Die Auswertung verwendet den zuletzt gespeicherten Ergebnisstand je Teilnehmer und Interaktionsseite. Das Senden eines Statements löst keine Aufgabenabgabe aus.

5. Versuche, Abschluss und Avallain unterscheiden

Entscheiden Sie bei eigenen Inhalten ausdrücklich, ob ein Ergebnis eine Seitenprüfung oder einen vollständigen Übungsdurchlauf beschreibt. Mehrere Seitenprüfungen sind nicht automatisch mehrere vollständige Versuche. Auch Schließen oder Öffnen einer Übung belegt keinen Abschluss.

Avallain ist ein konkretes Anbieterformat. Dort enthalten beobachtete answered-Meldungen unter anderem einen JSON-String in result.response, Seitenkennungen und Prüfzähler wie checkAttempts. Diese zusätzlichen Felder sind keine Pflicht für das einfache eigene Beispiel. Eigene Inhalte müssen sie nicht nachbilden, solange keine Avallain-spezifische Wiederherstellung benötigt wird.

Eine zusätzliche completed-Meldung kann fachlich sinnvoll sein, wird aber durch diese Anleitung nicht automatisch zum von Edupool ausgewerteten Durchlaufabschluss. Ein entsprechender Auswertungsvertrag muss gesondert vereinbart und getestet werden.

Prüfliste vor produktivem Einsatz

  • Ohne Reader-Startkontext bleibt das Senden deaktiviert.
  • Richtige und falsche Antworten ergeben die erwarteten Punkte; eine nicht beantwortete Frage erzeugt kein Ergebnis.
  • Ein eigener Prüfklick und das Senden sind nachvollziehbar. Wiederholtes Senden nach einem Fehler behält die Ereignis-ID.
  • Ein autorisierter Online-Test bestätigt die Annahme durch den vorgesehenen Endpunkt. Öffentliche Vorschauen ersetzen diesen Nachweis nicht.
  • Die Plattform prüft separat die gespeicherte Teilnehmer-/Produktzuordnung und die sichtbare Auswertung nach Metadatenimport.
  • Mehrseitige Inhalte und Wiederaufnahme werden gesondert getestet.

Schmale Ansicht: lokales Ergebnis und fehlender Startkontext bleiben lesbar

Bei HTTP 403 zunächst Abspielberechtigung und Sitzung prüfen. Bei fehlendem Endpoint den Start aus dem Buch und ?endpoint= prüfen. Bei erfolgreicher Übertragung ohne sichtbares Ergebnis die Metadatenzuordnung prüfen; nicht durch wiederholtes Senden neue Versuche erzeugen.