Analytics docs: fix purchase-lifecycle drift + add canonical third-party tracking page

[next-devin]

Spun out of NextCommerceCo/next-campaigns-ops#214 (see disposition comment) — this is the "Developer Docs first" step; NextCommerceCo/next-campaigns-ops#257 is blocked on it.

Ground truth (verified against SDK source)

Purchase events are queued to sessionStorage at checkout (src/utils/analytics/tracking/PendingEventsHandler.ts in campaign-cart) and fire once on the first post-checkout page after redirect — upsell or receipt, whichever loads first. dl_upsell_purchase is a separate event. In auto mode, calling next.trackPurchase() again duplicates the SDK's own purchase event.

Drift to fix

• content/docs/campaigns/analytics/tracking-api.mdx (~line 357): says "queued and fired on confirmation page" — wrong for funnels with upsells.
• content/docs/campaigns/analytics/best-practices.mdx (~lines 35, 173, 681, 958): instructs manually tracking purchase on the confirmation page — the auto-mode anti-pattern. Rework: auto mode = don't re-fire; manual trackPurchase only on the manual/special-integration path.
• content/docs/campaigns/analytics/events.md (~line 424) is already correct ("confirmation or upsell page") — use its wording as the reference; every analytics page should agree with it.

Add: canonical third-party tracking page

One page under analytics/ for bridging trackers with no first-class adapter (Hyros, RedTrack, TripleWhale, …). Options: dl_purchase listener, Custom adapter, GTM tag (when GTM is already in the stack), vendor conversion API. Runnable snippets only — define where order comes from, keep a refresh dedup guard keyed on order id, warn against double-counting upsell accepts. Verification = SDK 0.4.28+ debug panel / 0.4.30 setup warnings + a real test order. Cite PendingEventsHandler for lifecycle claims.

[next-devin]

Update — the "canonical third-party page" half of this issue now has a shipped reference implementation (starter templates PR NextCommerceCo/campaign-cart-starter-templates#106, merged 2026-07-10). The lifecycle-drift fix half is unchanged and still needed.

The templates now carry a "Route C" forwarder + 8 direct vendor adapters (GA4, Axon, Taboola, Triple Whale, TikTok, Northbeam, Snapchat, Pinterest) and a RudderStack loader, generated into every family, off by default, enabled per campaign via campaigns.json vendor id keys. Source of truth: _shared/analytics/ in that repo (byte-identical to Sam's upstream analytics-tracking-docs/examples/ reference, which has a regression harness).

Implications for the new docs page:

• Don't write new hand-rolled bridge snippets that duplicate the forwarder. Present the option space as: SDK first-class provider / GTM tag / Route C forwarder (shipped in the starter templates; copyable for non-template kits) / vendor conversion API — and align snippets with the forwarder's semantics rather than inventing parallel ones. Coordinate with Sam (masmalsah), who owns the upstream reference.
• The forwarder is also the best citation for lifecycle claims: it registers the SDK's NextDataLayerTransformFn once, skips _willRedirect events and forwards only the post-redirect replay (i.e. purchase forwards on the first post-checkout page, matching PendingEventsHandler), dedups per adapter on event_id, and defaults to main-funnel events with dl_purchase / dl_upsell_purchase as separate events.
• Rules worth documenting on the page: one path per vendor (Route C instead of GTM/SDK provider for the same vendor — two paths double-fire); RudderStack is an SDK-provider vendor, loader-only (both campaigns.json keys + analytics.providers.rudderstack.enabled: true, and never call rudderanalytics.page() manually); PII/identity hooks are opt-in flags, consent-gated on accepts_marketing.
• Vendors with no adapter (Hyros, RedTrack, …) still need the generic bridge guidance — that part of the original scope stands.