fix(telemetry): attribute studio renders to the browser user (joinable funnel) (#1492)

Studio-triggered renders emit render_complete / render_error from the CLI
preview-server process, which stamps every event with the install's
anonymousId (client.ts drainQueueToPayload). The browser, meanwhile, fires
studio_session_start / studio_render_start under its own getAnonymousId(). So
the render outcome and the render start never share a person_id — verified in
data: of 15,125 users who started a studio render in 30d, ZERO have any
render_complete under any source, and the 898 studio-tagged completers are
disjoint server UUIDs. The studio render funnel — the product's core value
moment and strongest retention signal — is therefore unmeasurable.

Thread the browser's telemetry id through to the render-outcome events:

- client.ts: trackEvent takes an optional distinctId; drainQueueToPayload uses
  `event.distinctId ?? config.anonymousId`. CLI renders unchanged.
- events.ts: trackRenderComplete/trackRenderError forward an optional distinctId.
- studioRenderTelemetry.ts: emitStudioRender* pass opts.distinctId through.
- core studio-api (types.ts + routes/render.ts): the render route reads
  `telemetryDistinctId` from the request body (validated string) and passes it
  to the adapter's startRender, which already forwards opts to the emitters.
- studio (useRenderQueue.ts): include getAnonymousId() as telemetryDistinctId
  in the render POST — the same id studio_* events already use.

Result: studio render_complete/error now carry the browser user's id and join
studio_session_start / studio_render_start. Older clients that don't send the
field fall back to anonymousId (no regression). No new tracking surface — it's
the existing anonymous studio id.

Tests: per-event override forwarding (events), studio render distinctId
threading + older-client fallback (studioRenderTelemetry), and route body →
adapter forwarding incl. non-string rejection (core render route).
This commit is contained in:
Miguel Ángel
2026-06-16 02:55:22 -04:00
committed by GitHub
parent d6a846300e
commit 121cdd2d9f
9 changed files with 186 additions and 52 deletions
+11 -2
View File
@@ -24,6 +24,10 @@ let eventQueue: Array<{
event: string;
properties: EventProperties;
timestamp: string;
// Override for the batch distinct_id. Defaults to the install's anonymousId.
// Used to attribute server-side studio renders to the browser user who
// triggered them, so the render funnel is joinable across processes.
distinctId?: string;
}> = [];
let telemetryEnabled: boolean | null = null;
@@ -59,12 +63,17 @@ export function shouldTrack(): boolean {
/**
* Queue a telemetry event. Non-blocking, fail-silent.
*/
export function trackEvent(event: string, properties: EventProperties = {}): void {
export function trackEvent(
event: string,
properties: EventProperties = {},
distinctId?: string,
): void {
if (!shouldTrack()) return;
const sys = getSystemMeta();
eventQueue.push({
event,
distinctId,
properties: {
...properties,
cli_version: VERSION,
@@ -102,7 +111,7 @@ function drainQueueToPayload(): string | null {
const batch = eventQueue.map((e) => ({
event: e.event,
properties: { ...e.properties, $ip: null },
distinct_id: config.anonymousId,
distinct_id: e.distinctId ?? config.anonymousId,
timestamp: e.timestamp,
}));
eventQueue = [];