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 <noreply@anthropic.com>

* refactor: name the local Studio upgrade CTA and drop the explaining comments

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
terencecho
2026-11-11 21:15:38 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent c218b37a31
commit 2a70733c15
14 changed files with 226 additions and 19 deletions
+8
View File
@@ -2332,6 +2332,14 @@ values are never collected, except short self-identifying names: `AGENT`,
the `<app>/<version>/<channel>` 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
+1 -1
View File
@@ -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.";
@@ -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();
});
+44 -6
View File
@@ -1,12 +1,50 @@
import type { LocalShareInteraction } from "@hyperframes/studio-server";
function choice<T extends string | boolean>(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;
}
}
@@ -17,6 +17,8 @@ it.each(["free", "subscribed", undefined] as const)(
} as Parameters<typeof presentSpaces>[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,
);
},
);
+4 -1
View File
@@ -50,7 +50,10 @@ function planOffer(
entitlements: Awaited<ReturnType<ShareService["spaces"]>>[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"] {
+15
View File
@@ -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 }],
]);
});
+23 -4
View File
@@ -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<string, string | boolean>): 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;
+6 -1
View File
@@ -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"] };
@@ -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<HTMLAnchorElement>(
'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<HTMLInputElement>('input[type="checkbox"]')!.click());
const manage = host.querySelector<HTMLAnchorElement>('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" }],
]);
});
@@ -81,6 +81,9 @@ export function QuickShareContent({
{manageUrl ? (
<a
href={manageUrl}
onClick={() =>
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 ? (
<a
href={url}
onClick={() =>
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"
@@ -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 });
}}
/>
<span>
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 (
<div className="flex flex-wrap items-center justify-between gap-2 text-step-12">
{space && space.limit !== null && space.used !== null ? (
@@ -252,6 +261,15 @@ export function SharePlan({ model, snapshot }: Props) {
{space?.plan === "free" && allowed ? (
<a
href={upgrade}
onClick={() =>
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"
@@ -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();
});
@@ -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<void>)
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<void>)
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,