HTTP API and player
Everything the dashboard does goes through a small HTTP API. Session endpoints require the admin sign-in cookie.
Endpoints
| Method and path | Sign-in | What it does |
|---|---|---|
POST /api/ingest |
No | Receives batches from the recorder. Cross-origin posts from any site are allowed. |
GET /api/sessions |
Yes | Lists and searches sessions, newest first |
GET /api/sessions/:id |
Yes | Session summary and the list of stored parts |
GET /api/sessions/:id/parts/:name |
Yes | One stored batch |
DELETE /api/sessions/:id |
Yes | Deletes the session and its recordings |
GET /api/auth/status |
No | Whether a password is set and whether you are signed in |
POST /api/auth/setup, /login, /logout, /password |
Varies | Sign-in management, same-origin JSON only |
Deleting a session that is still being recorded removes what has been stored so far. If the visitor keeps browsing, the session comes back with only what is uploaded after the delete.
Searching sessions
GET /api/sessions accepts these optional parameters, combined with AND:
| Parameter | Meaning |
|---|---|
user |
Exact user ID |
url |
A visited page, matched as described in Finding sessions |
urlMode |
prefix (default), exact or contains |
from, to |
Session start time range, in milliseconds |
minDuration, maxDuration |
Duration in seconds |
minPages |
Minimum page views |
errors=1, rage=1 |
Only sessions with errors, or with rage clicks |
device |
desktop, mobile or tablet |
cursor |
The next value from the previous page |
limit |
Page size, 30 by default, 100 at most |
The response is { sessions, next }. Each session includes its user IDs and device. No total count is returned. Invalid values return 400 with a message that says which one.
Embedding the player
The player can run on its own, for example in an internal support tool. The live demo on this site uses it this way.
import { createPlayer } from "./src/player/index.ts";
const player = createPlayer(container, events, { speed: 1, skipIdle: true, trail: true });
player.replayer.on("end", () => console.log("finished"));
player.replayer.play();events is the flattened events array of the stored batches, ordered by the part names (which start with the first timestamp). The returned replayer has play, pause, seek, setSpeed and on("time" | "page" | "state" | "end"). Call player.destroy() to remove it.