# Room events

- URL: https://getroomi.com/docs/room-events
- Built: 2026-10-26

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's events say which
app is on the stage, never what happens inside it. What a viewer opens and
clicks inside the demo, with their yes, is a separate record, never their
keystrokes: [Screens and clicks](https://getroomi.com/docs/screens).

## 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 is `opened`;
  two visits, or two minutes in the room, is `engaged`. A viewer's answer at
  the end moves it on: see [Analytics and the pipeline](https://getroomi.com/docs/analytics).
- **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:

```json http
{
  "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](https://getroomi.com/docs/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-done` only 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 `page` events, beside the seconds from the tally;
- runs of each scenario, from `scenario` events;
- 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.

> [!NOTE]
> On the Free plan, analytics are total views only, and no journey is shown.
> The room records the same events whatever the plan. See
> [Plans and limits](https://getroomi.com/docs/plans).

## 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, in these events: what the viewer types there, or
  what it shows. With their yes, the screens they open and what they click are
  kept apart from them ([Screens and clicks](https://getroomi.com/docs/screens)).
- 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:` or `page:` is dropped.
- The viewer's IP address or browser: none of these records holds either.
- Anything at all during Preview as viewer.

> [!NOTE]
> Every workspace starts on Free, and moves to Pro or Team whenever you like, in Settings, Billing. Sign in at app.getroomi.com with GitHub or Google, then add the connector to Claude at https://mcp.getroomi.com/mcp, or run the CLI with npx @getroomi/cli. These pages describe the connector, the CLI, pitch.json, the app and the room as they are.
