NextCommerceCo / NextCommerceCo/developer-docs
Analytics docs: fix purchase-lifecycle drift + add canonical third-party tracking page
Nobody has claimed this yet.
- Dominant language
- MDX
- Stars
- 2
- Forks
- 0
- Avg merge
- 6h 4m
- Merged PRs (30d)
- 13
Description
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; manualtrackPurchaseonly 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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare content/docs/campaigns/analytics/tracking-api.mdx and best-practices.mdx with the wording in events.md, then read src/utils/analytics/tracking/PendingEventsHandler.ts for lifecycle claims. Add the canonical third-party tracking page under analytics/ with runnable snippets, deduplication guidance, verification steps, and citations; update the drifted guidance and test with a real order.
Written by the indexing model from the issue text.
Assessment
- Domain
- analytics, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100