SURF-1415 feat(store): first-touch UTM persistence in the Surface tag

[paragmore]

Problem

Customers running paid campaigns lose attribution before a form is ever opened: the tag reads window.location.search fresh on every STORE_UPDATE, so a visitor who lands on a paid landing page with utm_source/utm_medium/click-id params and then navigates loses them — especially when internal CTAs replace the query string with internal tags (e.g. ?utm_content=home_homepage-hero). Verified in Yuma's prod data: across two LinkedIn campaign windows, zero genuine prospect submissions carried LinkedIn-paid params. Paid Social shows zero in their HubSpot; contacts land as Direct/Offline.

Ticket: SURF-1415

Change

• src/store/first-touch.ts (new): on page load, if the URL carries qualifying attribution params, persist { params, url, referrer, at } in first-party cookie surface_first_touch (30-day max-age, base-domain scoped via getJourneyCookieDomain(), values capped at 256 chars).
  • Qualifying = utm_source, utm_medium, or a click-id (gclid, fbclid, li_fat_id, msclkid, ttclid). utm_content alone does not qualify — internal CTA tags would poison the slot.
  • Capture is skipped when document.referrer is same-origin (internal navigation), and is write-once until expiry (strict first-touch, matching HubSpot Original Source semantics).
  • Capture runs on page load only, not on SPA route changes — a route change with params is internal navigation by definition, and document.referrer is stale on pushState so the same-origin guard can't protect that path.
• SurfaceStore.getPayload(): merge { ...getFirstTouchParams(), ...this.urlParams } — current-page params win, first-touch fills gaps. Merging here (not in sendPayloadToIframes()) also covers the direct notifyIframe() call on the embed partial-fill path.
• test/first-touch.html (new): manual test page showing the cookie and the merged payload params.

Downstream (form-render URL_DATA.params → HubSpot UTM hidden fields) is unchanged — the merged params flow through the existing plumbing.

Verification (Playwright against the built bundle)

• Landing with ?utm_source=linkedin&utm_medium=paid_social&utm_campaign=Test+Campaign&li_fat_id=test-123&utm_content=ad-variant-a → cookie written with all params.
• Navigating to ?utm_content=home_homepage-hero → merged payload keeps all LinkedIn params, current page's utm_content wins.
• Same-origin navigation carrying ?utm_source=sneaky-internal → cookie NOT written.
• utm_content-only landing with no referrer → cookie NOT written.
• Second external landing with ?utm_source=google&gclid=… while cookie set → stored record unchanged (write-once); merged payload shows current-page google params winning, first-touch filling utm_medium.
• pnpm run typecheck + pnpm run build clean; surface_tag.js/surface_embed_v1.js rebuilt.

Rollout note

Consumers load @latest from jsDelivr — purge https://purge.jsdelivr.net/gh/trysurface/scripts@latest/surface_tag.min.js after merge to make it land same-day.

🤖 Generated with Claude Code

[notion-workspace]

Surface tag: first-touch UTM persistence

[greptile-apps]

Greptile Summary

This PR adds first-touch campaign attribution persistence to the Surface tag. The main changes are:

• A new surface_first_touch cookie for landing-page UTM and click-id params.
• First-touch params merged into iframe payload URL data.
• Fresh URL param reads inside getPayload() for direct iframe notifications.
• Updated built bundles and a manual first-touch test page.

Confidence Score: 4/5

This is close, but the oversized-cookie fallback should be fixed before merging.

• Fresh URL params are now read in getPayload(), which covers the direct iframe notification path.
• The cookie domain retry handles hosts that reject the base-domain attribute.
• Very large encoded attribution records can still skip the cookie write entirely, so first-touch attribution can still be lost for valid campaign URLs.

src/store/first-touch.ts

_{Reviews (2): Last reviewed commit: "fix(store): address review — fresh urlPa..." | Re-trigger Greptile}

[greptile-apps]

Oversized Params Still Drop When a qualifying landing URL contains several long non-ASCII UTM values, the fallback can still leave the encoded JSON above MAX_ENCODED_COOKIE_BYTES. This branch then returns without writing any cookie, so later pages receive no first-touch params at all. That preserves the attribution loss this size guard is meant to avoid; the fallback should keep degrading or preserve a minimal qualifying attribution record instead of silently dropping the capture.