DE

Embedding psi-pulse in your own pages

This page is for teachers who want to add review questions to their own web pages, and for anyone who builds that. You need one line of JavaScript and some HTML, but no server of your own and no psi-pulse account.

psi-pulse is open to teachers at other universities too. We run the service on a best-effort basis, without any commitment to availability or support. Please check with your university’s data protection office whether you may use it in your teaching. The source code is on GitHub (AGPL-3.0), so you can also run psi-pulse yourself. The demo page shows the result, in several designs.

Embedding

A question is plain HTML; the psi-pulse script turns it into a self-test: the question, a “Show answer” button, then “I knew it” or “I didn’t”. Without JavaScript the answer can still be expanded; when printed, question and answer both appear.

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

<pulse-question key="crypto-signature">
  <p>What does a digital signature guarantee?</p>
  <details><summary>Answer</summary>
    <p>Integrity and authenticity of the message.</p>
  </details>
</pulse-question>

There are three ways to include the script; the questions behave the same in each case:

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

<!-- 2. your own copy of the file -->
<script defer src="/js/pulse.min.js"
  data-host="https://pulse.psi.uni-bamberg.de"></script>

<!-- 3. written into the page -->
<script data-host="https://pulse.psi.uni-bamberg.de">
  /* content of pulse.min.js */
</script>
  1. Load it from the psi-pulse server: the simplest option, and improvements arrive automatically. In return, every visit to your page loads the script from pulse.psi.uni-bamberg.de.
  2. Serve the file yourself: put pulse.min.js among your own files and name the psi-pulse server in data-host. You then decide when to take a new version.
  3. Write it into the page: for self-contained HTML files, such as lecture notes to download. This also works when the file is opened locally.

The script may go in the <head> or at the end of the page. The files are at /embed/v2/pulse.min.js and, readable with comments, at /embed/v2/pulse.js.

Writing questions

Everything inside <pulse-question> except the <details> block is the question; the content of <details> without the <summary> is the answer. Both may contain any HTML, including code, formulas or images. The reminder emails use the plain text only.

key
A fixed name for the question, unique on the page. We recommend it: with key, students keep their progress when you later correct the question text, and psi-pulse takes over the new text. Without key, psi-pulse recognises a question by its text, and a changed question counts as a new one.
<pulse-deck>
A deck: shows several questions one after another (“Question 1 of 3”). On loading, new questions and those due again move to the front.
group
Optional group name, for example a chapter. It orders the questions in the web app and in the emails. It goes on <pulse-deck> or on a single question.
<pulse-summary>
Optional: progress on this page, a short explanation and sign-in. With the compact attribute it becomes a single line that expands.
<pulse-deck group="Cryptography">
  <pulse-question key="crypto-signature">…</pulse-question>
  <pulse-question key="crypto-hash">…</pulse-question>
</pulse-deck>

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

Pages written for the first version of psi-pulse keep working: <pulse-question question="…" answer="…">, <pulse-page name="…"> and the <pulse-stack> deck are understood, and students keep their progress. You only swap the script. Your own CSS rules for pulse-deck should then name pulse-stack as well.

Settings

Settings go on the script as attributes. All of them are optional.

data-page
Name of the page, for example “Lecture 3: Cryptography”. Students see it in the web app and in the emails; the questions of one page belong together. Keep the name stable, as progress is tied to it. Without it, psi-pulse uses <meta name="pulse:page">, otherwise the page title.
data-url
The public address of the page; the web app links back to it. Without it, psi-pulse uses <meta name="pulse:url">, then <link rel="canonical">, then the address in the browser. For files opened locally, psi-pulse sends no address, so never a path on your computer.
data-print
What appears in print: answers (question and answer, the default), questions (questions only) or hide (no questions).
data-host
Address of the psi-pulse server. Only needed if you serve the script yourself or write it into the page.
data-style
With none, psi-pulse adds no CSS of its own; you style everything yourself.

Adapting the look

The questions take on the fonts, colours and headings of your page. The psi-pulse CSS is deliberately weak: every rule of your page wins, without !important. That includes general rules such as button { … }, which then also change the question buttons.

Set colours and shapes with CSS variables, on the element itself or on an enclosing element:

--pulse-accent
buttons, label, links, focus outline (default: text colour)
--pulse-on-accent
text on filled buttons
--pulse-rule
border and the line above the answer
--pulse-bg
background of the box (default: transparent)
--pulse-radius
rounding of box, buttons and fields
--pulse-ui-font, --pulse-ui-size
font and size of buttons and notes
--pulse-muted
colour of notes
--pulse-space
padding and margin of the box
--pulse-error
error messages during sign-in
pulse-question, pulse-deck, pulse-summary {
  --pulse-accent: #00457d;
  --pulse-on-accent: #fff;
  --pulse-rule: #ccdae5;
  --pulse-radius: .5rem;
}

Pages with a global reset. If your page resets all spacing, for example with * { margin: 0; padding: 0 }, that rule wins too and the questions look cramped. Set the spacing yourself in that case, for example like this:

/* after the page's reset */
: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; }

Further classes and states for targeted changes are documented in pulse.js.

What students experience

Without signing in

The self-tests work straight away. The browser stores the answers “I knew it” and “I didn’t” on the student’s device (in your page’s localStorage). The script makes no request at all to psi-pulse.

After signing in

Below an answered question there is a link “Keep it and review by email”. Students who choose this enter an email address and type in the six-digit code from the email. There is no password; anyone without an account gets one in the process. The script then moves the earlier answers from the browser into the account and deletes them from the browser.

Once signed in, each question shows whether it is due again. A question that is not due yet can be revealed but not rated, so nobody skips the intervals. When a question comes back is described under Learning logic.

Signing in applies to one website in one browser. On another website with psi-pulse questions, or in another browser, students sign in once more. Signing out removes the sign-in and the answers from the browser.

Language and accessibility

Labels appear in German or English, depending on the lang attribute around the question, so please set it on the <html> element. The buttons are real buttons and work with the keyboard, and screen readers announce status messages. Because the questions take on your page’s colours, please check the contrast in your design.

Privacy and requirements

Without sign-in, the script sends nothing to psi-pulse. If you load the script from the psi-pulse server (option 1), the browser only fetches the script file from there. The script sets no cookies, uses no iframe and no trackers. After sign-in, the psi-pulse privacy policy applies; psi-pulse stores the email address, a name if given, question and answer texts, page name and page address, and whether an answer was known.

Mention psi-pulse in your page’s privacy notice, and check with your university’s data protection office whether you may use the service.

If your page has a Content Security Policy (CSP, a list of permitted sources in an HTTP header), it needs two entries:

No frame-src entry is needed.

Learning logic: when a question comes back

This section describes how psi-pulse schedules questions for students who have signed in. Without sign-in, psi-pulse schedules nothing; the answers stay in the browser.

Intervals

With each answer you knew, the interval until the next review grows: 1, 2, 4, 7, then 14 days. After that it stays at 14 days, so a question you always know comes back every two weeks, with no end. To stop seeing a question, archive it (see below).

The interval counts from the last answer. After that the question is “due again” and goes into the next reminder email. Because that email arrives at a fixed time, it can take a few hours up to a day longer.

The first answer is given while reading, in the lecture notes. If it was known, the question is due again after one day. If not, the question is already in the next reminder email.

Pages can set their own intervals with attributes in the style of the first version (state-…); otherwise the intervals above apply.

“I didn’t”

Answering “I didn’t” does not move the question up: it comes back after the same interval as last time. If the answer is “I didn’t” again next time, the question drops back to the next shorter interval, and one more step with each further “I didn’t”, until it is in every reminder email. As soon as the answer is known again, the interval grows as usual.

Reminder email

psi-pulse sends at most one reminder email a day, and only on days when at least one question is due again. It arrives from the time students choose in their settings (full hours, German time). If more than six questions are due, psi-pulse picks six at random; the others follow on the next days.

Each question in the email has its own link, plus one link for all. A question from a reminder email only goes into another one once it has been answered, whether through the email, in the web app or in the lecture notes.

Weekly selection

Once a week a second email brings a random selection from all of one’s questions, including those not due at the moment. Students choose the day, the time and the number of questions; the default is six questions on Wednesdays. The selection is valid until the next one, after which its link no longer works. Archived questions do not appear in it.

Answers in the weekly selection do not change the schedule. Only an “I didn’t” counts: if another one follows next time, the question drops back as described above.

Streak

Answering a weekly selection down to the last question extends the streak by one week; the web app shows it on its overview. If the next weekly selection arrives before the previous one is finished, the streak starts again at zero.

Pause

psi-pulse pauses all emails for 14 days if a student

A short email announces the pause. After 14 days psi-pulse sends an email that it is back, and reminders resume. Answering any of one’s questions before that ends the pause at once; an email confirms this too.

Neglected questions

The web app shows a status for each question. If a question stays unanswered for twice its current interval, so 14 days after the last answer at an interval of 7 days, it counts as “Neglected”. An interval shorter than a day, for example right after “I didn’t”, counts as one day: a question is neglected two days after the last answer at the earliest. After the next answer outside the weekly selection it shows “Pending”, after one more it is active again. The status does not change when the question comes; the web app’s overview counts the active questions.

Archiving and deleting

On the “Questions” page of the web app, students select questions and archive or delete them; when answering from an email, “Archive” is also in the question’s menu. Archived questions no longer appear in reminder emails or weekly selections. Their progress is kept, and archiving can be undone on the same page. Deleting removes the question together with its progress; answering it again in the lecture notes later starts it from the beginning. Deleting the account deletes all questions.

How long codes and links are valid

Sign-in code in the lecture notes
10 minutes, at most five attempts
Sign-in in the lecture notes
90 days on this website in this browser, until signing out
Sign-in link for the web app
2 hours, usable once
Link to one question from a reminder email
until the question has been answered
Link to all questions of a reminder email
until all are answered, at most 30 days
Link to the weekly selection
until it is finished or the next one arrives
Unsubscribe link
until it is used

Accounts whose sign-up was never confirmed are deleted by psi-pulse after 30 days.

Questions and feedback

If you would like to use psi-pulse in your teaching, want to build your own client, or something does not work as described, write to dh.psi@uni-bamberg.de.