Analytics event contract

Helix.analytics is the platform event contract for user journeys, world sessions, creator monetization, social loops, purchases, safety events, and retention. The contract is shared across web, mobile wrappers, Unreal/native clients, workers, and server code.

Sending events from a world

Helix.analytics.track(eventName, input?) posts one client event to the HELIX collector. The SDK fills the envelope itself (event_id, occurred_at, user or anonymous id, platform: 'web', source: 'client', world_id), so a world only names the event and adds context:

await Helix.analytics.track('world_loaded', {
  instanceId,                        // optional: instance, item, invite, referrer, eventId
  properties: { loadMs: 1840, quality: 'high' },
});

World code may send only these ten events: world_entered, world_loaded, world_load_failed, world_exited, world_heartbeat, instance_joined, instance_left, creator_product_viewed, client_error_seen and api_error_seen. Property values are strings, numbers, booleans or null; the SDK drops keys that look sensitive (password, token, secret, email, payment and similar) and truncates strings to 256 characters. The promise rejects if the collector answers with an error.

Architecture split

• HELIX collector accepts single events and batches, validates the envelope, links anonymous and authenticated identities, deduplicates by event_id, and returns quickly.
• Raw event store keeps append-only normalized events indexed by user, anonymous user, session, world, creator, event name, and timestamp.
• PostHog forwarder sends approved, redacted events downstream and can be disabled without breaking HELIX event capture.
• Rollups aggregate hourly and daily data by world, creator, user, session, invite, FTUE step, item, product, and platform.
• Staff tools use rollups and controlled timelines for support, product, safety, and creator operations. PostHog remains the deeper internal exploration tool in v1.

Heavy analysis reads rollups or an external analytics surface. Hot product paths must not query raw events.

Event envelope

Every event uses the same envelope. Fields that do not apply should be omitted or set to null, not filled with placeholder values.

MVP taxonomy

The collector accepts a closed list of event names; GET /api/v1/analytics/event-names returns the live list (it is longer than the core taxonomy below). One unknown name rejects its whole batch.

Identity and acquisition:

• user_signed_up
• user_logged_in
• anonymous_user_identified
• invite_sent
• invite_opened
• invite_accepted
• referral_source_captured

FTUE:

• ftue_started
• ftue_step_viewed
• ftue_step_completed
• ftue_step_skipped
• ftue_completed
• ftue_abandoned

Sessions and worlds:

• session_started
• session_ended
• world_entered
• world_loaded
• world_load_failed
• world_exited
• world_heartbeat
• instance_joined
• instance_left

Social:

• friend_request_sent
• friend_request_accepted
• party_created
• party_joined
• share_clicked

Economy and creator:

• item_viewed
• item_purchased
• item_equipped
• home_visited
• creator_product_viewed
• creator_product_purchased
• creator_earned
• lix_spent
• coins_spent

Safety and platform health:

• report_submitted
• moderation_action_created
• content_rating_changed
• trust_state_changed
• client_error_seen
• api_error_seen

Authority rules

• Server events are authoritative for purchases, ownership, inventory, grants, creator earnings, moderation actions, bans, trust changes, reports, and content-rating changes.
• Client events are useful for journeys, UI behavior, FTUE, gameplay flow, performance context, and client errors. They are not trusted for value-bearing state.
• Event ingestion is append-only. Corrections are new events, never in-place edits.
• Every source uses the shared envelope so the vendor can change without changing the HELIX contract.

Privacy and creator boundary

Sensitive data must not be captured by default. Do not put raw chat, raw voice, payment details, tokens, secrets, exact private messages, or unnecessary PII in analytics events.

Use event and property allowlists instead of arbitrary property capture. Web session replay, when enabled in PostHog, must be sampled, controlled, web-only, and disabled for sensitive flows by default.

Creators and world owners see aggregate analytics for their own worlds:

• visits and unique visitors
• new vs returning users
• average session length and total playtime
• retention summaries
• invite and referral sources
• product and item sales
• creator earnings
• FTUE or world-specific drop-off points
• top products and items

Creators do not get raw per-user journey timelines in v1. Staff timelines are internal support, product, safety, and operations tools.

Runtime responsibilities

Web frontend:

• Wrap event capture behind a shared analytics client.
• Capture route context, FTUE steps, invites, world entry and exit, session lifecycle, client errors, and selected UI events.
• Identify users on login or signup and link anonymous history.

Mobile wrapper:

• Use the same envelope.
• Prefer the shared web bridge when the app is a web wrapper.
• Add native forwarding only for native-only events.

Unreal and native clients:

• Use a lightweight batch HTTP client that submits the same envelope to the HELIX collector.
• Start with session, world, instance, gameplay milestone, error, and economy events.
• Do not talk directly to PostHog in v1.

Server and workers:

• Emit authoritative events for money, inventory, ownership, invites, reporting, moderation, trust, content rating, and creator earnings.
• Forward only approved, redacted events to PostHog.
• Keep analytics non-blocking so capture never slows gameplay, checkout, ownership, grants, or backend authority paths.

What exists today

The backend (/api/v1/analytics) ships:

• Capture: POST /events (one event) and POST /events/batch (1–100 events), public and rate-limited per IP and per anonymous id; GET /event-names.
• Identity linking and PostHog forwarding. Forwarding runs only when it is switched on and configured; capture works without it.
• Staff tools (admins only): journeys, FTUE / invite / open-alpha funnels, actor detail, an event export and an AI insight scaffold.
• Creator rollups (signed-in owners): GET /creator/rollup, GET /creator/worlds/:worldId/rollup and GET /creator/homes/:homeId/rollup.

Not done yet: the Unreal adapter (the plugin marks analytics.track as needing a correction because its platform is hard-coded to web) and a mobile-native adapter.

Deferred from v1

• Full custom analytics query builder.
• Public user-level analytics.
• Raw creator access to user timelines.
• Native mobile SDK beyond the wrapper bridge unless native-only events require it.
• Unreal dashboard parity. Unreal only needs event submission first.
• Voice analytics or moderation analytics beyond event hooks.
• Real-time warehouse streaming unless raw storage and rollups prove insufficient.