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.

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

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.

Rollout phases

1. Event contract, taxonomy, and docs.
2. Backend collector, raw storage, validation, identity linking, and PostHog forwarding.
3. Web analytics wrapper and core FTUE, invite, world, and session events.
4. Server-authoritative events for sessions, purchases, earnings, invites, moderation, reports, and ownership changes.
5. Rollups and internal staff journey dashboard.
6. Creator and world analytics dashboard from rollups.
7. Mobile and Unreal/native adapters after the contract stabilizes.
8. AI-ready exports and insight jobs.

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.