From 2a70733c15798430e1fae817bc65f1bf90acbed6 Mon Sep 17 00:00:00 2001 From: terencecho <3916587+terencecho@users.noreply.github.com> Date: Wed, 11 Nov 2026 21:15:38 +0000 Subject: [PATCH] fix: track local Studio sharing CTA interactions (#7566) * fix: track local Studio sharing CTA intent * fix: tag local Studio and CLI share upgrade links with where they came from The local Studio share modal's Upgrade to Pro link opens /pricing?from=cli&entry=local_studio_share, and hyperframes share's source-files notice links /pricing?from=cli&entry=cli_share, so the pricing page can tell which link a visit came from and return the visitor to their terminal. The modal accepts its own pricing page with any query, still only on hyperframes.dev's two origins. share_upgrade_clicked carries cta=share_modal_upgrade. Co-Authored-By: Claude Opus 5.5 * refactor: name the local Studio upgrade CTA and drop the explaining comments Co-Authored-By: Claude Opus 5.5 * fix: keep the local Studio upgrade link's return page unchanged Only entry=local_studio_share is added to the local Studio share window's Upgrade to Pro link. from=cli would have told these buyers to go back to their terminal after checkout, but they return to a browser tab. hyperframes share's link keeps from=cli, as the CLI's other upgrade links do. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- docs/packages/cli.mdx | 8 +++ packages/cli/src/commands/share.ts | 2 +- packages/cli/src/server/shareEvents.test.ts | 23 ++++++++ packages/cli/src/server/shareEvents.ts | 50 +++++++++++++++-- .../cli/src/server/sharePresentation.test.ts | 4 +- packages/cli/src/server/sharePresentation.ts | 5 +- packages/cli/src/share/telemetry.test.ts | 15 +++++ packages/cli/src/share/telemetry.ts | 27 +++++++-- packages/studio-server/src/localShare.ts | 7 ++- .../src/components/share/QuickShare.test.tsx | 55 +++++++++++++++++++ .../src/components/share/QuickShare.tsx | 6 ++ .../components/share/QuickShareControls.tsx | 26 +++++++-- .../share/localShareTelemetry.test.ts | 8 +++ .../src/components/share/useQuickShare.ts | 9 ++- 14 files changed, 226 insertions(+), 19 deletions(-) create mode 100644 packages/cli/src/server/shareEvents.test.ts diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 83f66edfc7..22812d4f97 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -2332,6 +2332,14 @@ values are never collected, except short self-identifying names: `AGENT`, the `//` tag an app that launches the CLI sets, sent as `client` so reports from that app can be told apart. +Local Studio sharing also records upgrade clicks (project limit or sharing permissions), +audience selections, editable-source toggles, and sharing action/navigation intent. +These events contain fixed categories and booleans, never share URLs, project paths, +or invitee addresses. The local Studio's and `hyperframes share`'s Upgrade to Pro links add +`?entry=local_studio_share` or `?from=cli&entry=cli_share`, so the pricing page can tell which +link a visit came from. A click records intent, not a successful permission change or purchase. +They follow the same telemetry opt-outs. + Nothing personally identifying is collected until you sign in. **Signed-in usage is not anonymous.** When you run `hyperframes auth login`, your usage is linked to your HeyGen account from then on: it is keyed on an id derived from your diff --git a/packages/cli/src/commands/share.ts b/packages/cli/src/commands/share.ts index 678731d59a..5804b60e4c 100644 --- a/packages/cli/src/commands/share.ts +++ b/packages/cli/src/commands/share.ts @@ -226,7 +226,7 @@ function presentFailure(result: ShareState, json: boolean) { function sourceNotice(reason: string): string { if (reason === "source_plan_required") - return "Your video is shared without editable project files. Upgrade to Pro to include source files: https://hyperframes.studio/pricing"; + return "Your video is shared without editable project files. Upgrade to Pro to include source files: https://hyperframes.studio/pricing?from=cli&entry=cli_share"; if (reason === "requested") return "Sharing the video without editable project files. Use --include-source to upload project files."; return "Sharing the video without editable project files; source sharing is unavailable in this workspace."; diff --git a/packages/cli/src/server/shareEvents.test.ts b/packages/cli/src/server/shareEvents.test.ts new file mode 100644 index 0000000000..0eb2145e52 --- /dev/null +++ b/packages/cli/src/server/shareEvents.test.ts @@ -0,0 +1,23 @@ +import { expect, it } from "vitest"; +import { shareEventInput } from "./shareEvents.js"; +const interactions = [ + { event: "share_upgrade_clicked", reason: "project_limit" }, + { event: "share_upgrade_clicked", reason: "sharing_permissions" }, + { event: "share_audience_selected", audience: "invite" }, + { event: "share_source_toggled", enabled: false }, + { event: "share_navigation_clicked", destination: "manage" }, + { event: "share_action_clicked", action: "access" }, +]; +it.each(interactions)("accepts a bounded sharing interaction: $event", (event) => { + expect(shareEventInput(event)).toEqual(event); + expect(shareEventInput({ ...event, url: "https://secret.test/token" })).toBeNull(); +}); +it.each([ + { event: "share_upgrade_clicked", reason: "private project" }, + { event: "share_audience_selected", audience: "email@example.com" }, + { event: "share_source_toggled", enabled: "true" }, + { event: "share_navigation_clicked", destination: "https://secret.test" }, + { event: "share_action_clicked", action: "delete" }, +])("rejects unrecognized values: $event", (event) => { + expect(shareEventInput(event)).toBeNull(); +}); diff --git a/packages/cli/src/server/shareEvents.ts b/packages/cli/src/server/shareEvents.ts index e3a650458e..dcb27688f7 100644 --- a/packages/cli/src/server/shareEvents.ts +++ b/packages/cli/src/server/shareEvents.ts @@ -1,12 +1,50 @@ import type { LocalShareInteraction } from "@hyperframes/studio-server"; +function choice(value: unknown, ...allowed: T[]): T | undefined { + return allowed.find((item) => item === value); +} export function shareEventInput(value: unknown): LocalShareInteraction | null { if (typeof value !== "object" || value === null || Array.isArray(value)) return null; if (Object.keys(value).length !== 2 || !("event" in value)) return null; - if (value.event === "share_link_copied" && "via" in value && value.via === "copy") - return { event: value.event, via: "copy" }; - if (value.event !== "share_opened" || !("link" in value)) return null; - const link = ["none", "live", "changed"] as const; - const chosen = link.find((item) => item === value.link); - return chosen ? { event: value.event, link: chosen } : null; + const field = (key: string): unknown => Reflect.get(value, key); + switch (value.event) { + case "share_opened": { + const link = choice(field("link"), "none", "live", "changed"); + return link === undefined ? null : { event: value.event, link }; + } + case "share_link_copied": { + const via = choice(field("via"), "copy"); + return via === undefined ? null : { event: value.event, via }; + } + case "share_upgrade_clicked": { + const reason = choice(field("reason"), "project_limit", "sharing_permissions"); + return reason === undefined ? null : { event: value.event, reason }; + } + default: + return settingInteraction(value); + } +} + +function settingInteraction(value: object & { event: unknown }): LocalShareInteraction | null { + const field = (key: string): unknown => Reflect.get(value, key); + switch (value.event) { + case "share_audience_selected": { + const audience = choice(field("audience"), "public", "team", "invite", "private"); + return audience === undefined ? null : { event: value.event, audience }; + } + case "share_source_toggled": { + const enabled = choice(field("enabled"), true, false); + return enabled === undefined ? null : { event: value.event, enabled }; + } + case "share_navigation_clicked": { + const destination = choice(field("destination"), "manage", "shared_page"); + return destination === undefined ? null : { event: value.event, destination }; + } + case "share_action_clicked": { + const action = choice(field("action"), "share", "update", "access", "off", "on", "login"); + return action === undefined ? null : { event: value.event, action }; + } + default: + return null; + } } diff --git a/packages/cli/src/server/sharePresentation.test.ts b/packages/cli/src/server/sharePresentation.test.ts index 987bae7334..9b406c419d 100644 --- a/packages/cli/src/server/sharePresentation.test.ts +++ b/packages/cli/src/server/sharePresentation.test.ts @@ -17,6 +17,8 @@ it.each(["free", "subscribed", undefined] as const)( } as Parameters[0][number]; const [result] = presentSpaces([space]); expect(result?.plan).toBe(plan ?? null); - expect(result?.upgradeUrl).toBe(plan === "free" ? "https://hyperframes.dev/pricing" : null); + expect(result?.upgradeUrl).toBe( + plan === "free" ? "https://hyperframes.dev/pricing?entry=local_studio_share" : null, + ); }, ); diff --git a/packages/cli/src/server/sharePresentation.ts b/packages/cli/src/server/sharePresentation.ts index 614e6ad554..5daa824738 100644 --- a/packages/cli/src/server/sharePresentation.ts +++ b/packages/cli/src/server/sharePresentation.ts @@ -50,7 +50,10 @@ function planOffer( entitlements: Awaited>[number]["review_entitlements"], ) { const plan = entitlements?.plan ?? null; - return { plan, upgradeUrl: plan === "free" ? `${shareSite()}/pricing` : null }; + return { + plan, + upgradeUrl: plan === "free" ? `${shareSite()}/pricing?entry=local_studio_share` : null, + }; } function presentedState(value: ShareState, held: boolean): LocalShareState["state"] { diff --git a/packages/cli/src/share/telemetry.test.ts b/packages/cli/src/share/telemetry.test.ts index 732d6a9e66..900034175d 100644 --- a/packages/cli/src/share/telemetry.test.ts +++ b/packages/cli/src/share/telemetry.test.ts @@ -47,3 +47,18 @@ describe("share telemetry privacy boundary", () => { expect(mocks.track).not.toHaveBeenCalled(); }); }); + +it("forwards only bounded CTA fields with the local Studio surface", () => { + trackShareInteraction( + { event: "share_upgrade_clicked", reason: "project_limit" }, + "local_studio", + ); + trackShareInteraction({ event: "share_source_toggled", enabled: false }, "local_studio"); + expect(mocks.track.mock.calls).toEqual([ + [ + "share_upgrade_clicked", + { client_surface: "local_studio", reason: "project_limit", cta: "share_modal_upgrade" }, + ], + ["share_source_toggled", { client_surface: "local_studio", enabled: false }], + ]); +}); diff --git a/packages/cli/src/share/telemetry.ts b/packages/cli/src/share/telemetry.ts index 3852cb8d20..21b26909bc 100644 --- a/packages/cli/src/share/telemetry.ts +++ b/packages/cli/src/share/telemetry.ts @@ -6,8 +6,12 @@ import { resetTelemetryPostureCache, trackEvent } from "../telemetry/client.js"; import type { ReviewExportProgress } from "@hyperframes/share"; export type ShareSurface = "cli" | "local_studio"; +const LOCAL_STUDIO_UPGRADE_CTA = "share_modal_upgrade"; export type ShareInteraction = - | { event: "share_opened"; link: "none" | "live" | "changed" } + | Exclude< + import("@hyperframes/studio-server").LocalShareInteraction, + { event: "share_link_copied" } + > | { event: "share_link_copied"; via: "copy" | "publish" | "update" }; const REASONS = new Set([ "feature_unavailable", @@ -45,10 +49,25 @@ function emit(event: string, properties: Record): void } } export function trackShareInteraction(input: ShareInteraction, surface: ShareSurface = "cli") { - if (input.event === "share_opened") - emit(input.event, { client_surface: surface, link: input.link }); - else emit(input.event, { client_surface: surface, via: input.via }); + const base = { client_surface: surface }; + switch (input.event) { + case "share_opened": + return emit(input.event, { ...base, link: input.link }); + case "share_link_copied": + return emit(input.event, { ...base, via: input.via }); + case "share_upgrade_clicked": + return emit(input.event, { ...base, reason: input.reason, cta: LOCAL_STUDIO_UPGRADE_CTA }); + case "share_audience_selected": + return emit(input.event, { ...base, audience: input.audience }); + case "share_source_toggled": + return emit(input.event, { ...base, enabled: input.enabled }); + case "share_navigation_clicked": + return emit(input.event, { ...base, destination: input.destination }); + case "share_action_clicked": + return emit(input.event, { ...base, action: input.action }); + } } + function shareAttempt(action: "share" | "update", surface: ShareSurface) { const base = { client_surface: surface, action, attempt_id: randomUUID() }; let admitted = false; diff --git a/packages/studio-server/src/localShare.ts b/packages/studio-server/src/localShare.ts index e4d7b536cd..0cca8ab553 100644 --- a/packages/studio-server/src/localShare.ts +++ b/packages/studio-server/src/localShare.ts @@ -45,4 +45,9 @@ export type LocalShareAction = { }; export type LocalShareInteraction = | { event: "share_opened"; link: "none" | "live" | "changed" } - | { event: "share_link_copied"; via: "copy" }; + | { event: "share_link_copied"; via: "copy" } + | { event: "share_upgrade_clicked"; reason: "project_limit" | "sharing_permissions" } + | { event: "share_audience_selected"; audience: LocalShareAudience } + | { event: "share_source_toggled"; enabled: boolean } + | { event: "share_navigation_clicked"; destination: "manage" | "shared_page" } + | { event: "share_action_clicked"; action: LocalShareAction["action"] }; diff --git a/packages/studio/src/components/share/QuickShare.test.tsx b/packages/studio/src/components/share/QuickShare.test.tsx index f1de926a29..d34056f352 100644 --- a/packages/studio/src/components/share/QuickShare.test.tsx +++ b/packages/studio/src/components/share/QuickShare.test.tsx @@ -132,6 +132,10 @@ it("drains pending editor saves before creating or uploading", async () => { await mount(save); await choose("public"); await act(async () => button("Create share link")?.click()); + expect(interaction).toHaveBeenCalledWith(token, { + event: "share_action_clicked", + action: "share", + }); expect(save).toHaveBeenCalledOnce(); expect(calls).toEqual([]); await act(async () => resolveSave()); @@ -497,6 +501,25 @@ it.each(["free", "subscribed", null] as const)( else expect(link).toBeUndefined(); }, ); +it("keeps the plan link's entry so the pricing page can count where the visit came from", async () => { + snapshot.spaces[0]!.plan = "free"; + snapshot.spaces[0]!.upgradeUrl = "https://hyperframes.dev/pricing?entry=local_studio_share"; + await mount(); + const link = [...host.querySelectorAll("a")].find((a) => + a.textContent?.includes("Upgrade to Pro"), + ); + expect(link?.href).toBe("https://hyperframes.dev/pricing?entry=local_studio_share"); +}); +it("refuses a look-alike pricing host even with a matching path", async () => { + snapshot.spaces[0]!.plan = "free"; + snapshot.spaces[0]!.upgradeUrl = + "https://hyperframes.dev.evil.test/pricing?entry=local_studio_share"; + await mount(); + const link = [...host.querySelectorAll("a")].find((a) => + a.textContent?.includes("Upgrade to Pro"), + ); + expect(link).toBeUndefined(); +}); it("refuses an upgrade destination outside the public pricing flow", async () => { snapshot.spaces[0]!.plan = "free"; snapshot.spaces[0]!.upgradeUrl = "https://example.com/checkout"; @@ -620,3 +643,35 @@ it("discloses source scope and uploads files only after checking the option", as { action: "share", audience: "public", space: "team1", includeSource: true }, ]); }); + +it.each([0, 5])("counts upgrade intent with quota context (used=%s)", async (used) => { + snapshot.spaces[0]!.plan = "free"; + snapshot.spaces[0]!.used = used; + snapshot.spaces[0]!.upgradeUrl = "https://hyperframes.dev/pricing"; + await mount(); + expect(interaction.mock.calls.filter(([, e]) => e.event === "share_upgrade_clicked")).toEqual([]); + const upgrade = host.querySelector( + 'a[href="https://hyperframes.dev/pricing"]', + )!; + upgrade.addEventListener("click", (event) => event.preventDefault()); + await act(async () => upgrade.click()); + expect(interaction).toHaveBeenCalledWith(token, { + event: "share_upgrade_clicked", + reason: used === 5 ? "project_limit" : "sharing_permissions", + }); + expect(calls).toEqual([]); +}); +it("counts explicit audience, source and manage interactions without sending project data", async () => { + await mount(); + await choose("invite"); + await act(async () => host.querySelector('input[type="checkbox"]')!.click()); + const manage = host.querySelector('a[href="https://hyperframes.dev/shares"]')!; + manage.addEventListener("click", (event) => event.preventDefault()); + await act(async () => manage.click()); + expect(interaction.mock.calls).toEqual([ + [token, { event: "share_opened", link: "none" }], + [token, { event: "share_audience_selected", audience: "invite" }], + [token, { event: "share_source_toggled", enabled: true }], + [token, { event: "share_navigation_clicked", destination: "manage" }], + ]); +}); diff --git a/packages/studio/src/components/share/QuickShare.tsx b/packages/studio/src/components/share/QuickShare.tsx index 6a48190fa7..b536f0badb 100644 --- a/packages/studio/src/components/share/QuickShare.tsx +++ b/packages/studio/src/components/share/QuickShare.tsx @@ -81,6 +81,9 @@ export function QuickShareContent({ {manageUrl ? ( + model.track({ event: "share_navigation_clicked", destination: "manage" }) + } target="_blank" rel="noreferrer" className="flex h-8 items-center rounded-full px-2 text-step-12 text-text-2 hover:bg-hover" @@ -91,6 +94,9 @@ export function QuickShareContent({ {url ? ( + model.track({ event: "share_navigation_clicked", destination: "shared_page" }) + } target="_blank" rel="noreferrer" className="flex h-8 items-center rounded-full px-2 text-step-12 text-text-2 hover:bg-hover" diff --git a/packages/studio/src/components/share/QuickShareControls.tsx b/packages/studio/src/components/share/QuickShareControls.tsx index 97fe5aad5f..a5c7b24210 100644 --- a/packages/studio/src/components/share/QuickShareControls.tsx +++ b/packages/studio/src/components/share/QuickShareControls.tsx @@ -179,7 +179,10 @@ export function ShareSourceStatus({ model, snapshot }: Props) { type="checkbox" checked={model.includeSource} disabled={model.busy} - onChange={(event) => model.setIncludeSource(event.target.checked)} + onChange={(event) => { + model.setIncludeSource(event.target.checked); + model.track({ event: "share_source_toggled", enabled: event.target.checked }); + }} /> Include editable project files @@ -236,12 +239,18 @@ export function ShareLogin({ model }: { model: QuickShareModel }) { ); } +const PRICING_ORIGINS = ["https://hyperframes.dev", "https://dev.hyperframes.dev"]; + +function isPricingPage(link: string): boolean { + if (!URL.canParse(link)) return false; + const url = new URL(link); + return PRICING_ORIGINS.includes(url.origin) && url.pathname === "/pricing"; +} + export function SharePlan({ model, snapshot }: Props) { const space = snapshot.spaces.find((item) => item.id === model.spaceId); const upgrade = space?.upgradeUrl; - const allowed = - upgrade && - ["https://hyperframes.dev/pricing", "https://dev.hyperframes.dev/pricing"].includes(upgrade); + const allowed = upgrade !== undefined && upgrade !== null && isPricingPage(upgrade); return (
{space && space.limit !== null && space.used !== null ? ( @@ -252,6 +261,15 @@ export function SharePlan({ model, snapshot }: Props) { {space?.plan === "free" && allowed ? ( + model.track({ + event: "share_upgrade_clicked", + reason: + space.limit !== null && space.used !== null && space.used >= space.limit + ? "project_limit" + : "sharing_permissions", + }) + } target="_blank" rel="noreferrer" className="inline-flex h-8 items-center gap-1 rounded-full px-2 font-semibold text-accent hover:bg-hover" diff --git a/packages/studio/src/components/share/localShareTelemetry.test.ts b/packages/studio/src/components/share/localShareTelemetry.test.ts index b98659de7a..46a67b5e93 100644 --- a/packages/studio/src/components/share/localShareTelemetry.test.ts +++ b/packages/studio/src/components/share/localShareTelemetry.test.ts @@ -20,3 +20,11 @@ it("obeys browser opt-out before calling the guarded local bridge", async () => }), ); }); + +it("does not send upgrade clicks when telemetry is disabled", () => { + const fetch = vi.fn(); + vi.stubGlobal("fetch", fetch); + policy.mockReturnValue(false); + shareInteraction("token", { event: "share_upgrade_clicked", reason: "project_limit" }); + expect(fetch).not.toHaveBeenCalled(); +}); diff --git a/packages/studio/src/components/share/useQuickShare.ts b/packages/studio/src/components/share/useQuickShare.ts index 733e03600a..fa8821238a 100644 --- a/packages/studio/src/components/share/useQuickShare.ts +++ b/packages/studio/src/components/share/useQuickShare.ts @@ -3,6 +3,7 @@ import type { LocalShareAction, LocalShareAudience, LocalShareJob, + LocalShareInteraction, LocalShareSnapshot, } from "@hyperframes/studio-server"; import { useMountEffect } from "../../hooks/useMountEffect"; @@ -106,6 +107,7 @@ export function useQuickShare(token: string, beforeShare?: () => Promise) async function run(action: LocalShareAction) { const signal = lifetime.current?.signal; if (!signal || signal.aborted || working.current) return; + track({ event: "share_action_clicked", action: action.action }); setWorking(true); setError(null); setErrorCode(null); @@ -176,10 +178,15 @@ export function useQuickShare(token: string, beforeShare?: () => Promise) setError("Couldn’t copy. Open the shared page and copy its address."); } } + const track = (event: LocalShareInteraction) => shareInteraction(token, event); return { + track, snapshot, audience, - setAudience, + setAudience: (value: LocalShareAudience) => { + setAudience(value); + track({ event: "share_audience_selected", audience: value }); + }, spaceId, busy, error,