Enable Session Replay for a Tenant

Session replay records how visitors move through a tenant site (pages, clicks, scrolling, where something breaks) on our own OpenReplay instance. It is off for every brokerage until you give that brokerage a project key. Turning it on also turns on the recording section of that site’s privacy page, so the policy and the behaviour cannot drift apart.

Caution

One OpenReplay project per brokerage, never shared. The instance has no isolation below the project level, so the project boundary is the only thing keeping one brokerage’s visitors out of another brokerage’s view. Ask the analytics team for a project keyed to the brokerage slug.

---

Before you enable it

1. The brokerage’s designated broker has confirmed in writing that their site may record visitor sessions.
2. The replay provisioning key is on the machine you run onboarding from, at ~/.local/share/replay-gateway/homestar-provisioning.key (or point REPLAY_PROVISIONING_KEY_FILE at it). It mints projects for our slugs and cannot read a single session.
3. Nothing on the tenant site renders data an MLS prohibits from display. Recording captures the page as drawn, so this is a check on the site, not on the recorder.

---

Enable it

1. Add an analytics block to the brokerage’s spec under .onboarding/:

   analytics:
     session_replay: true

2. Apply the spec. This mints the brokerage’s own replay project through the gateway, one per slug, and stores both the tracker key and the project’s data key on the brokerage row.

   make onboard-brokerage BROKERAGE=<slug>

   Re-running is safe: the gateway returns the same project (existing) and the stored keys are left alone.

3. Load the tenant site. The public layout now mounts the tracker, and /privacy shows a Session Recording section quoting the enforced 30-day retention.

Leaving the analytics block out of a later re-run leaves recording as it is. Set session_replay: false and re-apply to switch it off.

Data key on a second deployment

The gateway hands out the project’s data key exactly once, on the creating call. If the project was first minted from a workstation and prod later runs the same spec, prod gets existing with no key and cannot show replays. Run once with a rotation, which mints a fresh key for that deployment and revokes every prior one:

make onboard-brokerage BROKERAGE=<slug> ROTATE_REPLAY_KEY=1

---

What visitors get

• Inputs are obscured in the browser before anything is uploaded. Contact and tour forms record that a field was used, never what was typed.
• Do Not Track and Global Privacy Control are honored. A browser sending either is never recorded, and the tracker is not even started.
• Admin and sign-in pages are never recorded. They use different layouts; only the public tenant layout mounts the tracker.
• Recordings expire after 30 days, enforced on the instance by a daily job. This is quoted verbatim on the privacy page from one setting, OPENREPLAY_RETENTION_DAYS, so if the instance ever changes, change the setting rather than the prose.

---

What agents see

On the lead detail page, a Session replay card lists the recordings of the visits that produced the lead, newest first. Each shows when the visit started, how long it ran, the pages walked, and any issue signals the recorder saw (dead clicks, rage clicks, failed requests, script errors, and so on, with counts). Watch opens the replay in place. The card renders nothing when the tenant does not record or nothing was recorded.

The player URL is minted server-side each time the card loads and lives fifteen minutes. The brokerage’s data key never reaches the browser.

---

Where recordings show up

Two places, and they answer different questions.

The lead detail page carries a Session replay card listing the visits that produced that lead, with the pages walked and any issue signals. That only ever covers people who filled something in.

The Visitors page (brokers and above) lists recorded visits whether or not they converted, ranked by how much the person actually looked at. Most traffic never becomes a lead, so this is where a long, unconverted browse becomes visible. Each row says how long they stayed, how many pages and listings they opened, and links to the lead if one exists.

Players are minted when you click Watch and live about fifteen minutes. The brokerage’s data key never reaches the browser.

---

How it joins to leads

As soon as the tracker starts, the page reads its replay session id and announces it to the API, then repeats it with every behaviour batch. The API stores it on the visitor’s sessions row (replay_session_id) and, each time it changes, writes a replay_session_started event to the session timeline. Nothing of ours is sent to the replay instance; we hold their id, they hold nothing of ours.

Note

Session replay is a support and product tool. The IMLS audit trail required by rule 18.3.9 stays in our own database, where we control retention. Recordings are never re-published, sold, or mined into a listing dataset.

---

Testing a tenant site locally

Tenant hostnames are not served by the dev container by default. To exercise one:

1. Add the hostname to DEV_TENANT_HOSTS in .env (comma-separated), for example kroetch.l.homestar.ink, and make sure its prefix is in TENANT_PREFIXES.
2. Insert a brokerage_domains row for that hostname pointing at the brokerage.
3. Publish an explicit DNS record for the hostname. The dev wildcard is a CNAME, which shadows the certificate challenge until an explicit record exists.
4. Recreate idx-app-dev. Caddy issues the certificate within a couple of minutes.