Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
#28 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
68/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet

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.

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; 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.

Dominant language
MDX
Stars
2
Forks
0
Avg merge
6h 4m
Merged PRs (30d)
13

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from NextCommerceCo/developer-docs

All issues in NextCommerceCo/developer-docs

Similar issues

More Data Visualization issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.