psi-pulse in eigene Seiten einbauen

Diese Seite richtet sich an Lehrende, die Wiederholungsfragen in ihre eigenen Webseiten einbauen möchten, und an alle, die das technisch umsetzen. Sie brauchen dafür eine Zeile JavaScript und etwas HTML, aber keinen eigenen Server und kein Konto bei psi-pulse.

psi-pulse steht auch Lehrenden anderer Hochschulen offen. Wir betreiben den Dienst nach bestem Bemühen, ohne Zusage zu Verfügbarkeit oder Support. Ob Sie ihn in Ihrer Lehre einsetzen dürfen, stimmen Sie bitte mit den Datenschutzbeauftragten Ihrer Hochschule ab. Der Quelltext liegt offen auf GitHub (AGPL-3.0), Sie können psi-pulse also auch selbst betreiben. Wie das Ergebnis aussieht, zeigt die Demo-Seite, auch in mehreren Gestaltungen.

Einbinden

Eine Frage besteht aus gewöhnlichem HTML, das Skript von psi-pulse macht daraus einen Selbsttest: Frage, Knopf „Antwort zeigen“, danach „Gewusst“ oder „Nicht gewusst“. Ohne JavaScript bleibt die Antwort aufklappbar; beim Drucken erscheinen Frage und Antwort.

<script defer
  src="https://pulse.psi.uni-bamberg.de/embed/v2/pulse.min.js"></script>

<pulse-question key="krypto-signatur">
  <p>Was garantiert eine digitale Signatur?</p>
  <details><summary>Antwort</summary>
    <p>Integrität und Authentizität der Nachricht.</p>
  </details>
</pulse-question>

Das Skript lässt sich auf drei Arten einbinden; die Fragen verhalten sich jedes Mal gleich:

<!-- 1. vom Server von psi-pulse -->
<script defer
  src="https://pulse.psi.uni-bamberg.de/embed/v2/pulse.min.js"></script>

<!-- 2. eigene Kopie der Datei -->
<script defer src="/js/pulse.min.js"
  data-host="https://pulse.psi.uni-bamberg.de"></script>

<!-- 3. direkt in der Seite -->
<script data-host="https://pulse.psi.uni-bamberg.de">
  /* Inhalt von pulse.min.js */
</script>

Vom Server von psi-pulse laden: am einfachsten, Verbesserungen kommen automatisch an. Dafür lädt jeder Aufruf Ihrer Seite das Skript von pulse.psi.uni-bamberg.de.
Datei selbst ausliefern: Sie legen pulse.min.js zu Ihren Dateien und nennen mit data-host den Server von psi-pulse. So bestimmen Sie selbst, wann Sie eine neue Fassung übernehmen.
Direkt in die Seite schreiben: für eigenständige HTML-Dateien, etwa ein Skript zum Herunterladen. Das funktioniert auch, wenn die Datei lokal geöffnet wird.

Das Skript darf im <head> oder am Ende der Seite stehen. Die Dateien liegen unter /embed/v2/pulse.min.js und, lesbar kommentiert, unter /embed/v2/pulse.js.

Fragen schreiben

Alles in <pulse-question> außer dem <details>-Block ist die Frage; der Inhalt von <details> ohne <summary> ist die Antwort. Beide dürfen beliebiges HTML enthalten, auch Code, Formeln oder Bilder. Für die Erinnerungsmails verwendet psi-pulse nur den reinen Text.

key: Ein fester Name der Frage, eindeutig auf der Seite. Wir empfehlen ihn: Mit key bleibt der Lernstand der Studierenden erhalten, wenn Sie den Fragetext später korrigieren; psi-pulse übernimmt dann den neuen Text. Ohne key erkennt psi-pulse die Frage an ihrem Text, und eine geänderte Frage gilt als neue Frage.
<pulse-deck>: Ein Stapel: zeigt mehrere Fragen nacheinander („Frage 1 von 3“). Beim Laden rücken neue Fragen und solche, die wieder dran sind, nach vorn.
group: Optionaler Gruppenname, etwa ein Kapitel. Er ordnet die Fragen in der Web-App und in den Mails. Er steht an <pulse-deck> oder an einer einzelnen Frage.
<pulse-summary>: Optional: Stand der Fragen auf dieser Seite, kurze Erklärung und Anmeldung. Mit dem Attribut compact wird daraus eine Zeile, die sich aufklappen lässt.

<pulse-deck group="Kryptographie">
  <pulse-question key="krypto-signatur">…</pulse-question>
  <pulse-question key="krypto-hash">…</pulse-question>
</pulse-deck>

<pulse-summary compact></pulse-summary>

Seiten, die noch für die erste Version von psi-pulse geschrieben sind, funktionieren weiter: <pulse-question question="…" answer="…">, <pulse-page name="…"> und der Stapel <pulse-stack> werden verstanden, und der Lernstand bleibt erhalten. Sie müssen nur das Skript austauschen. Eigene CSS-Regeln für pulse-deck sollten dann auch pulse-stack nennen.

Einstellungen

Einstellungen stehen als Attribute am Skript. Alle sind optional.

data-page: Name der Seite, etwa „Vorlesung 3: Kryptographie“. Studierende sehen ihn in der Web-App und in den Mails; die Fragen einer Seite gehören zusammen. Halten Sie den Namen stabil, denn der Lernstand hängt an ihm. Ohne Angabe nimmt psi-pulse <meta name="pulse:page"> und sonst den Titel der Seite.
data-url: Adresse, unter der die Seite öffentlich erreichbar ist; die Web-App verlinkt dorthin zurück. Ohne Angabe nimmt psi-pulse <meta name="pulse:url">, dann <link rel="canonical">, dann die Adresse im Browser. Bei lokal geöffneten Dateien sendet psi-pulse keine Adresse, also nie einen Pfad auf Ihrem Rechner.
data-print: Was beim Drucken erscheint: answers (Frage und Antwort, Vorgabe), questions (nur Fragen) oder hide (keine Fragen).
data-host: Adresse des psi-pulse-Servers. Nur nötig, wenn Sie das Skript selbst ausliefern oder in die Seite schreiben.
data-style: Mit none fügt psi-pulse kein eigenes CSS ein; Sie gestalten alles selbst.

Aussehen anpassen

Die Fragen übernehmen Schrift, Farben und Überschriften Ihrer Seite. Das eigene CSS von psi-pulse ist absichtlich schwach: Jede Regel Ihrer Seite gewinnt, ohne !important. Das gilt auch für allgemeine Regeln wie button { … }, die dann auch die Knöpfe der Fragen verändern.

Farben und Formen stellen Sie über CSS-Variablen ein, am Element selbst oder an einem umgebenden Element:

--pulse-accent: Knöpfe, Beschriftung, Links, Fokusrahmen (Vorgabe: Textfarbe)
--pulse-on-accent: Schrift auf gefüllten Knöpfen
--pulse-rule: Rahmen und Trennlinie vor der Antwort
--pulse-bg: Hintergrund des Kastens (Vorgabe: durchsichtig)
--pulse-radius: Rundung von Kasten, Knöpfen und Feldern
--pulse-ui-font, --pulse-ui-size: Schrift und Größe von Knöpfen und Hinweisen
--pulse-muted: Farbe von Hinweisen
--pulse-space: Innen- und Außenabstand des Kastens
--pulse-error: Fehlermeldungen bei der Anmeldung

pulse-question, pulse-deck, pulse-summary {
  --pulse-accent: #00457d;
  --pulse-on-accent: #fff;
  --pulse-rule: #ccdae5;
  --pulse-radius: .5rem;
}

Seiten mit globalem Reset. Setzt Ihre Seite alle Abstände zurück, etwa mit * { margin: 0; padding: 0 }, gewinnt diese Regel ebenfalls, und die Fragen wirken gequetscht. Setzen Sie die Abstände dann selbst, zum Beispiel so:

/* nach dem Reset der Seite */
:is(pulse-question, pulse-deck) { margin: .75em 0; padding: .75em; }
pulse-deck pulse-question { margin: 0; padding: 0; }
:is(pulse-question, pulse-deck) :is(.pulse-bar, .pulse-grade, .pulse-a) {
  margin-top: .6em;
}
:is(pulse-question, pulse-deck) .pulse-btn { padding: .4em .9em; }

Weitere Klassen und Zustände für gezielte Anpassungen sind in pulse.js kommentiert.

Was Studierende erleben

Ohne Anmeldung

Die Selbsttests funktionieren sofort. „Gewusst“ und „Nicht gewusst“ speichert der Browser auf dem Gerät der Studierenden (im localStorage Ihrer Seite). Das Skript stellt dabei keine einzige Anfrage an psi-pulse.

Mit Anmeldung

Unter einer beantworteten Frage steht „Dauerhaft sichern und per Mail wiederholen“. Wer das wählt, gibt eine E-Mail-Adresse ein und tippt den sechsstelligen Code aus der Mail ab. Ein Passwort gibt es nicht; wer noch kein Konto hat, bekommt dabei eines. Danach überträgt das Skript die bisherigen Antworten aus dem Browser in das Konto und löscht sie dort.

Angemeldet zeigt jede Frage, ob sie wieder dran ist. Eine Frage, die noch nicht wieder dran ist, lässt sich aufdecken, aber nicht bewerten; so überspringt niemand die Abstände. Wann eine Frage wiederkommt, steht im Abschnitt Lernlogik.

Die Anmeldung gilt für eine Website in einem Browser. Auf einer anderen Website mit psi-pulse-Fragen oder in einem anderen Browser melden sich Studierende einmal neu an. Abmelden löscht Anmeldung und Antworten aus dem Browser.

Sprache und Barrierefreiheit

Die Beschriftungen erscheinen auf Deutsch oder Englisch, je nach dem lang-Attribut um die Frage; setzen Sie es daher am <html>-Element. Die Knöpfe sind echte Schaltflächen und mit der Tastatur bedienbar, Statusmeldungen werden Screenreadern vorgelesen. Weil die Fragen Farben Ihrer Seite übernehmen, prüfen Sie bitte den Kontrast in Ihrer Gestaltung.

Datenschutz und Voraussetzungen

Ohne Anmeldung überträgt das Skript nichts an psi-pulse. Laden Sie das Skript vom Server von psi-pulse (Variante 1), ruft der Browser dort nur die Skriptdatei ab. Das Skript setzt keine Cookies, bindet kein iframe ein und nutzt keine Tracker. Mit Anmeldung gelten die Datenschutzhinweise von psi-pulse; gespeichert werden die E-Mail-Adresse, auf Wunsch ein Name, Fragen und Antworttexte, Seitenname und Seitenadresse sowie ob eine Antwort gewusst war.

Erwähnen Sie psi-pulse in den Datenschutzhinweisen Ihrer Seite, und stimmen Sie mit den Datenschutzbeauftragten Ihrer Hochschule ab, ob Sie den Dienst einsetzen dürfen.

Hat Ihre Seite eine Content Security Policy (CSP, eine Liste erlaubter Quellen im HTTP-Header), braucht sie zwei Einträge:

script-src https://pulse.psi.uni-bamberg.de, oder bei einem direkt eingefügten Skript dessen Hash bzw. 'unsafe-inline',
connect-src https://pulse.psi.uni-bamberg.de für Anmeldung und Antworten.

Ein Eintrag für frame-src ist nicht nötig.

Lernlogik: wann eine Frage wiederkommt

Dieser Abschnitt beschreibt, wie psi-pulse für angemeldete Studierende plant. Ohne Anmeldung plant psi-pulse nichts; die Antworten bleiben im Browser.

Abstände

Mit jeder gewussten Antwort wächst der Abstand bis zur nächsten Wiederholung: 1, 2, 4, 7, dann 14 Tage. Danach bleibt es bei 14 Tagen; eine Frage, die man immer weiß, kommt also alle zwei Wochen wieder, ohne Ende. Wer eine Frage nicht mehr sehen möchte, archiviert sie (siehe unten).

Der Abstand zählt ab der letzten Antwort. Danach ist die Frage „wieder dran“ und kommt in die nächste Erinnerungsmail. Weil diese Mail zu einer festen Uhrzeit kommt, kann es einige Stunden bis einen Tag länger dauern.

Die erste Antwort gibt man beim Lesen, im Skript. War sie gewusst, ist die Frage nach einem Tag wieder dran. War sie nicht gewusst, steht die Frage schon in der nächsten Erinnerungsmail.

Seiten können über Attribute im Stil der ersten Version (state-…) eigene Abstände festlegen; sonst gelten die genannten.

Nicht gewusst

Wer „Nicht gewusst“ wählt, steigt nicht auf: Die Frage kommt nach demselben Abstand wieder wie zuletzt. Ist die Antwort beim nächsten Mal wieder „Nicht gewusst“, fällt die Frage auf den nächstkürzeren Abstand zurück, bei jedem weiteren „Nicht gewusst“ um eine weitere Stufe, bis sie in jeder Erinnerungsmail steht. Sobald die Antwort wieder gewusst ist, wächst der Abstand wie gewohnt.

Erinnerungsmail

psi-pulse schickt höchstens eine Erinnerungsmail am Tag, und nur an Tagen, an denen mindestens eine Frage wieder dran ist. Sie kommt ab der Uhrzeit, die Studierende in den Einstellungen wählen (volle Stunden, deutsche Zeit). Sind mehr als sechs Fragen dran, wählt psi-pulse sechs zufällig aus; die übrigen folgen an den nächsten Tagen.

Jede Frage in der Mail hat einen eigenen Link, dazu gibt es einen Link für alle. Eine Frage aus einer Erinnerungsmail kommt erst dann in eine weitere, wenn sie beantwortet ist, egal ob über die Mail, in der Web-App oder im Skript.

Wochenauswahl

Einmal pro Woche kommt eine zweite Mail mit einer Zufallsauswahl aus allen eigenen Fragen, auch aus solchen, die gerade nicht dran sind. Tag, Uhrzeit und Zahl der Fragen stellen Studierende ein; vorgegeben sind mittwochs sechs Fragen. Die Auswahl gilt bis zur nächsten, dann funktioniert ihr Link nicht mehr. Archivierte Fragen erscheinen darin nicht.

Antworten in der Wochenauswahl verschieben den Plan nicht. Nur ein „Nicht gewusst“ zählt: Folgt darauf beim nächsten Mal noch eines, fällt die Frage wie oben zurück.

Serie

Wer eine Wochenauswahl bis zur letzten Frage beantwortet, verlängert die Serie um eine Woche; die Web-App zeigt sie in der Übersicht. Kommt die nächste Wochenauswahl, bevor die vorige fertig ist, beginnt die Serie wieder bei null.

Pause

psi-pulse pausiert alle Mails für 14 Tage, wenn Studierende

sieben Tage nach einer Erinnerungsmail noch keine Frage aus den Erinnerungsmails beantwortet haben oder
14 Tage lang keine Wochenauswahl bis zum Ende bearbeitet haben.

Die Pause kündigt eine kurze Mail an. Nach 14 Tagen meldet sich psi-pulse mit einer Mail zurück, und die Erinnerungen laufen wieder. Wer vorher eine seiner Fragen beantwortet, beendet die Pause sofort; auch das bestätigt eine Mail.

Vernachlässigte Fragen

Die Web-App zeigt zu jeder Frage einen Status (bisher auf Englisch). Bleibt eine Frage doppelt so lange unbeantwortet wie ihr aktueller Abstand, beim Abstand von 7 Tagen also 14 Tage nach der letzten Antwort, gilt sie als vernachlässigt („Neglected“). Ein Abstand unter einem Tag, etwa direkt nach „Nicht gewusst“, zählt dabei wie ein Tag: Vernachlässigt ist eine Frage frühestens zwei Tage nach der letzten Antwort. Nach der nächsten Antwort außerhalb der Wochenauswahl steht sie auf „Pending“, nach einer weiteren ist sie wieder aktiv. Der Status ändert nichts daran, wann die Frage kommt; die Übersicht der Web-App zählt die aktiven Fragen.

Archivieren und löschen

In der Web-App auf der Seite „Questions“ wählen Studierende Fragen aus und archivieren oder löschen sie; beim Beantworten aus einer Mail steht „Archive“ auch im Menü der Frage. Archivierte Fragen kommen nicht mehr in Erinnerungsmails und Wochenauswahlen. Ihr Lernstand bleibt, und das Archivieren lässt sich dort rückgängig machen. Löschen entfernt die Frage mit ihrem Lernstand; beantwortet man sie später im Skript noch einmal, beginnt sie von vorn. Wer das Konto löscht, löscht alle Fragen.

Wie lange Codes und Links gelten

Anmeldecode im Skript: 10 Minuten, höchstens fünf Versuche
Anmeldung im Skript: 90 Tage auf dieser Website in diesem Browser, bis zum Abmelden
Anmeldelink der Web-App: 2 Stunden, nur einmal verwendbar
Link zu einer Frage aus der Erinnerungsmail: bis die Frage beantwortet ist
Link für alle Fragen einer Erinnerungsmail: bis alle beantwortet sind, höchstens 30 Tage
Link zur Wochenauswahl: bis sie fertig bearbeitet ist oder die nächste kommt
Link zum Abbestellen: bis er benutzt wird

Konten, deren Anmeldung nie bestätigt wurde, löscht psi-pulse nach 30 Tagen.

Fragen und Rückmeldungen

Wenn Sie psi-pulse in Ihrer Lehre einsetzen möchten, einen eigenen Client bauen wollen oder etwas nicht wie beschrieben funktioniert, schreiben Sie an dh.psi@uni-bamberg.de.