NextCommerceCo / NextCommerceCo/developer-docs

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.

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

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.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.