Room events
What the room records as a viewer uses it.
On this page
The room records what a viewer does in it, so you can see each viewer's visits in order and not only the totals. It records two things: how long the viewer spent on each app and page, and the moments that give a visit its order, such as an app switched to, a page opened, a step of the tour. This page lists everything recorded, when, and what the app makes of it.
Nothing here is recorded about the demo itself. The room sees which app is on the stage, never what happens inside it: it does not read the demo's pages, keystrokes or clicks.
Visits and time
A visit begins when the room page opens, and the room's own script keeps a tally of the seconds the viewer spends on each thing it shows:
| Key | Time spent on |
|---|---|
app:<id> |
an app, on the stage, by the id in pitch.json |
page:<id> |
a page, open in the reader, by the page's id |
The tally counts only while the tab is visible: time with the tab hidden is not viewing time. It is sent to the room every 15 seconds, when the tab is hidden, and when the viewer leaves. The first send creates the visit; each later one replaces its totals. Leaving closes it.
The room keeps time only for the apps of the live build and the pages of the project; any other key is dropped, and no key can report more than a day.
What the app makes of it:
- Activity: each visit with its start, its end, its length and its time per app and page, largest first.
- The pipeline: a link with no visit is
sent; one visit isopened; two visits, or two minutes in the room, isengaged. A viewer's answer at the end moves it on: see Analytics and the pipeline. - Viewer-hours: the seconds of every visit begun this month, summed. A plan's viewer-hours are measured from the visits at private links, so a tab left open in the background uses none; time at a public address is counted separately and never against the plan.
Events
Each moment below is sent as it happens, with the visit it belongs to. The room sends the first one after the visit exists.
| Kind | Sent when | What it carries |
|---|---|---|
arrived |
the room page has opened | subject: the viewer's own device, phone, tablet or desktop, told from their screen and pointer. Not the frame they chose for the demo |
app |
the viewer switches to another app | subject: the app's id |
frame |
the viewer chooses a device frame | subject: phone, tablet, laptop, screen or none |
fullscreen |
the stage goes full screen | subject: the app on the stage |
new-tab |
the demo is opened in its own tab | subject: the app |
handoff |
"Open on your phone" shows its QR code | subject: the app the phone will open: the build's phone app if it has one, else the app on the stage |
page |
a page is opened from Read more | subject: the page's id |
scenario |
a scenario button is pressed, and the demo has answered | subject: the scenario's id; ok: whether the demo answered with success |
reset |
the reset button is pressed, and the demo has answered | ok: whether the demo answered with success |
next-steps |
the "What happens next" panel is opened | nothing more |
left |
the viewer leaves the page | subject: where they were, app:<id> or page:<id> |
tour-step |
the tour moves on to a step, or runs it again | subject: the step's id; ok: whether its calls worked, or null when it has none or they did not run |
tour-done |
the viewer reaches the end of the tour | nothing more |
tour-left |
the viewer leaves the tour to explore on their own | subject: the step they left from |
A tour step is recorded when the viewer moves forward to it (Next, or a step
chosen from the outline) or runs it again. Going Back to a step shows it as
it was and records nothing. ok records whether the demo answered each call
with success; what the demo said is shown to the viewer, not kept.
What an event looks like
The room's script sends each one to its own room, beside the visit's id:
{
"visitId": "5b0e8d52-3f7c-4f1e-9a0e-2d7c9b1f6a44",
"event": { "kind": "scenario", "subject": "full-session", "ok": true }
}This is the room's own traffic, not part of the HTTP API: you never send it, and the shape is listed here so you know exactly what is kept. Every field is bounded: an id is lower-case letters, digits and hyphens, up to 40 characters (a page's id up to 64), and anything else is refused.
What is checked before it is kept
An event is kept only when it names something the room actually showed:
- an app, scenario or story step of the live build, or a page of the project;
- a
tour-doneonly when the live build tells a story; - in a visit that belongs to this link, and under the person this browser said it is.
Anything else is refused and not kept, so a journey only ever names things the viewer could have seen. The workspace, the project and the link are taken from the viewer's session, never from what the browser sends.
What each event becomes
A viewer's journey. Activity shows each visit as a list of moments in
order, each with its time and the name of what it names: the app's name from
the build, the page's title, the scenario's label, the step's title. A page
removed since shows as "A page since removed". Where the visit ended is the
left event, else the last app or page recorded. The journey also shows what
the platform recorded itself, beside the room's events:
| Kind | What it is |
|---|---|
comment |
a comment the viewer left, with its text |
answer |
an answer to "What happens next" |
demo-started |
the viewer's copy of a container demo started |
demo-ready |
the copy answered its health path |
turned-away |
the room was full, and the viewer was turned away |
The journey also shows how far the viewer took the live build's story: the furthest step reached, in the story's order, and whether they reached the end.
Analytics. Across a date range, the app counts:
- page opens, from
pageevents, beside the seconds from the tally; - runs of each scenario, from
scenarioevents; - the tour's drop-off: how many people reached each step, how many started the tour, reached its end, or left it to explore.
Page opens and scenario runs are counted from the first event the room recorded for the project. For the days before it, the analytics say they were not recorded rather than show a zero as if it had been measured.
The viewer's own device, from arrived, is shown on each visit of the
journey.
Who an event is filed under
- A private link: under the link, and under the person this browser said it is. Every browser is asked "Are you …?" before the room opens, the first included; someone who says no is added as a forwarded person under the same link, with their own journey. Someone who said yes and then picks "Not Priya?" in the room takes what that browser recorded as her with them.
- A public address: under the address itself, with no person. Each visit carries an anonymous visitor id for the session, stored hashed and used only to count people. Nothing identifies them.
- Preview as viewer: nothing is recorded. The room sends no events and keeps no visit, so your own look at the room never shows up as a viewer.
What is not recorded
- Anything inside the demo: its pages, what the viewer types or clicks there, or what it shows.
- What the demo answered to a scenario, reset or tour step, beyond whether it succeeded.
- Time with the tab hidden.
- Time on a file: a key other than
app:orpage:is dropped. - The viewer's IP address or browser: none of these records holds either.
- Anything at all during Preview as viewer.