NextCommerceCo / NextCommerceCo/developer-docs

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

Aperta
#28 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

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

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. 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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.