Event Ingestion & Taxonomy
Learn how GN-Apex tracks page views, interactive clicks, e-commerce purchases, and custom user properties through an offline-resilient client pipeline.
“Events captured during offline periods are queued in IndexedDB and automatically flushed upon reconnection.”
Standard Event Taxonomy
The platform categorizes events into distinct analytical domains:
page_view
Captured on route transitions with referrer and search params.
click & scroll
Link/button clicks with element IDs, dataset tags, and depth percentiles.
purchase
Order IDs, revenue, SKU arrays, and conversion values.
identify & alias
Stitching anonymous hardware fingerprints to named user accounts.
vitals & rum
Core Web Vitals, resource waterfails, and navigation timing.
video_play & pause
Media engagement, 50% milestone tracking, and duration metrics.
Analytics Payload Schema
Every event packet transmitted to POST /api/collect adheres to this contract:
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| projectId | string | Required | Target Project Node ID. |
| sessionId | string | Required | Session identifier (rotates after 30 mins of inactivity). |
| visitorId | string | Required | Deterministic hardware/canvas hash. |
| messageId | string | Required | RFC4122 UUID to deduplicate events. |
| eventType | string | Required | Snake_case event type (page_view, click, purchase). |
| eventName | string | Optional | Custom event label (e.g. 'cta_clicked'). |
| eventData | Record<string, any> | Optional | Arbitrary JSON metadata payload. |
| ecommerce | EcommercePayload | Optional | Structured cart/order payload. |
| performance | PerformanceMetrics | Optional | RUM metrics and timing snapshots. |
| clientTimestamp | ISO-8601 Date | Required | Client clock time (validated against server drift). |
Offline Storage & Queue Buffering
The SDK includes a built-in EventStorage class backed by IndexedDB:
- Queue Flushing: Flushes every 5 seconds, when queue count reaches 10, on page hide (
visibilitychange), or immediately onpurchaseandidentifyevents. - Disk Protection: Capped at 500 events. If an extended offline period occurs, the oldest events are evicted to make room for fresh interactions.
SDK Tracking Methods
| 1 | import { nexus } from "@nexushub/client"; |
| 2 | |
| 3 | // Track custom user interactions |
| 4 | nexus.analytics?.track("newsletter_subscribed", { |
| 5 | plan: "enterprise", |
| 6 | source: "footer_modal", |
| 7 | }); |