feat: capture marketplace app iframe sessions in Fullstory [AIS-488]

[Jared Jolton (jjolton-contentful)]

AIS-488

Draft. Two things are outstanding before this is ready for review, both external to the code. See "Not ready yet" below.

Summary

• Wraps the app root in SegmentAnalyticsProvider so the app reports to its own Segment source. The write key comes from VITE_SEGMENT_WRITE_KEY, injected at build time the same way the app's four existing VITE_* variables are.
• Sets window._fs_run_in_iframe = true at entrypoint module scope. Without it, Fullstory treats a cross-origin iframe as its own root session, so the app's capture would be disjoint from the surrounding web app session. Apps are served from *.ctfapps.net while the parent is app.contentful.com, so this is always cross-origin. The assignment has to happen before Segment loads fs.js, which is why it is in the entrypoint rather than a component.
• Adds only the toolkit as a direct dependency. It already brings @segment/analytics-next, so the app does not need it separately.

Segment write keys are write-only ingest keys and are safe to expose in a client bundle.

Verified

• npx tsc --noEmit exits 0
• npm run build exits 0, and the emitted bundle contains both the flag and the injected key
• Ran against staging with the app served from a local dev server, cross-origin to the parent. In the app frame: _fs_run_in_iframe is true, _fs_is_outer_script is undefined, _fs_org matches the parent, and fs.js loaded. fs-debug.js logs Asking for a frame ID. followed by FrameId received within frame ..., which is the inner and outer Fullstory instances negotiating so the iframe joins the parent's capture rather than starting its own.
• Committed lockfile resolves entirely from public npm, with no npm.pkg.github.com URLs.

Not ready yet

• VITE_SEGMENT_WRITE_KEY needs to exist in CircleCI. Merging before then would build staging and production with an empty key, making the provider a no-op.
• One confirmation still pending: viewing the resulting Fullstory session to see the app's DOM inside the parent session, and no separate session for the app.

Test plan

• CI build passes
• VITE_SEGMENT_WRITE_KEY present in the staging build
• Segment debugger shows traffic from the app after analytics consent is accepted
• Fullstory session shows the app UI rather than a blank frame
• Fullstory session is stitched to the parent session, with no separate session for the app

Generated with Claude Code