@funnelsgrove/analytics

Shared analytics package for public funnels.

Read this file before editing analytics code. Deeper runtime SDK docs live in docs/funnel-sdk/analytics-sdk.md.

Owns event identity and delivery

@funnelsgrove/analytics owns the browser identity, event-shaping, and delivery contract for public funnel analytics. Funnel code may decide when a business event happened, but this package decides how that event becomes a normalized SDK/PostHog/partner payload.

Use This Package For

• browser user-id persistence
• SDK user bootstrap for public funnel identity
• public analytics event batching and transport
• identify, track, step lifecycle, and checkout event helpers
• Stripe purchase metadata shaping before payment metadata reaches the API
• Google Tag and Meta Pixel event adapters
• local-only no-op behavior when a real publishable key is not configured

Do Not Use This Package For

• step routing
• manifest logic
• checkout orchestration
• billing plan resolution
• Stripe checkout UI
• funnel-specific step components or copy

Public Surfaces

• publicAnalyticsSdk: the canonical browser SDK for identify, track, lifecycle, checkout, and flush calls.
• bootstrapPublicAnalyticsUser: public SDK identity bootstrap helper.
• sdk-user-id.storage: shared browser user-id storage contract.
• buildStripePurchaseMetadata and purchase attribute helpers: safe metadata shaping for payment handoff.
• trackStripePaymentCheckoutReturn: parses and deduplicates Stripe browser-return diagnostics without claiming a purchase conversion.
• google-tag.service and meta-pixel.service: partner event adapters.
• experiment-result-metrics.service: shared experiment result metric helpers.

Engineering Rules

• Keep transport details here; do not duplicate event batching in funnels.
• Keep provider adapters dumb: they map canonical events, not funnel business flow.
• Do not import payment UI or runtime routing from this package.
• Sensitive values must be filtered before metadata reaches Stripe or partner tools.
• A Stripe browser return is diagnostic state only. Use trackStripePaymentCheckoutReturn; never turn query parameters into checkout_completed or trusted purchase_completed.

Google Tag Configuration

NEXT_PUBLIC_GOOGLE_ANALYTICS_ID and NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID configure which Google tags load. Google Ads conversion actions also need the full send_to destination, such as AW-123456789/ConversionLabel.

• NEXT_PUBLIC_GOOGLE_TAG_LEAD_SEND_TO sends an Ads conversion event when the SDK records a lead/email capture.
• NEXT_PUBLIC_GOOGLE_TAG_LEAD_VALUE sets the numeric value for the lead Ads conversion. Empty or invalid values default to 0.
• NEXT_PUBLIC_GOOGLE_TAG_PURCHASE_SEND_TO sends an Ads conversion event when the SDK records a paid checkout completion.

Ads conversion values only fire when NEXT_PUBLIC_GOOGLE_TAG_ENABLED=true. The AW-... prefix is used to load and configure gtag.js; the full AW-.../... value is sent on the conversion event.

Build, Test, Publish

npm run test:run --workspace @funnelsgrove/analytics
npm run build --workspace @funnelsgrove/analytics
npm publish --workspace @funnelsgrove/analytics --access public

The build normalizes generated relative ESM imports to explicit .js files for published package consumers.