Skip to content

docs: add recipes for Google click IDs and form field services - #232

Merged
sadjow merged 2 commits into
mainfrom
docs/recipes
Oct 15, 2026
Merged

sadjow merged 2 commits into
mainfrom
docs/recipes

Conversation

@sadjow

@sadjow sadjow commented Oct 14, 2026

Copy link
Copy Markdown
Member

Two ideas were proposed for the module: Google Analytics integration and output formats other than JSON. Both are better served by documentation than by new features. GA4 already reads the same UTM and Google click parameters from the landing URL and attributes sessions itself. The attribution snapshot is plain data, so its format belongs to whatever receives it. This adds docs/RECIPES.md, linked from the README header and from the form example.

  • Google Analytics client ID. getGoogleAnalyticsClientId() asks gtag for the client ID with a timeout, so the lead is still sent when gtag.js is blocked or consent mode holds it back. The backend can then report later lead events through the Measurement Protocol. The recipe notes that Google's policy forbids sending personally identifiable information, including in URLs.
  • Google Ads click IDs. latestGoogleAdsClick() searches the whole history for the most recent entry with gclid, gbraid, or wbraid, since the last touch may be a later campaign without a Google click. Google says to store the GCLID with the lead for offline conversion import, and to send both gclid and gbraid when a conversion has both.
  • Form services that don't accept JSON. attributionFields() flattens first and last touch into fixed field names such as first_utm_source and returns URLSearchParams, which $fetch sends as application/x-www-form-urlencoded.

The package consumer fixture includes copies of the two helpers that use the module's types, so pnpm test:package fails if the published types stop supporting them. I also type-checked the GA helper and its form handler separately under strict with the DOM library.

Validation: pnpm format:check, pnpm lint --max-warnings 0, and pnpm test:package pass.

@sadjow
sadjow merged commit 0b579a8 into main Oct 15, 2026
7 checks passed
@sadjow
sadjow deleted the docs/recipes branch October 15, 2026 01:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant