NextCommerceCo / NextCommerceCo/developer-docs
Analytics docs: fix purchase-lifecycle drift + add canonical third-party tracking page
Nessuno ha ancora preso questa issue.
- Lingua principale
- MDX
- Stelle
- 2
- Fork
- 0
- Merge medio
- 6h 4m
- PR unite (30g)
- 13
Descrizione
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.
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Confronta content/docs/campaigns/analytics/tracking-api.mdx e best-practices.mdx con la formulazione di events.md, quindi leggi src/utils/analytics/tracking/PendingEventsHandler.ts per verificare le affermazioni sul ciclo di vita. Aggiungi la pagina canonica di tracking di terze parti in analytics/ con snippet eseguibili, indicazioni sulla deduplicazione, passaggi di verifica e citazioni; aggiorna la guida non più allineata e testa con un ordine reale.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Ambito
- analytics, documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Specificata chiaramente
- Idoneità per principianti
- 68/100