# @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`](../../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

```bash
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.