Events API

Log any player interaction or system action. Events are the backbone of reports such as session counts, activity distribution, and retention.

Endpoint

POST /events/hit

Request body (example)

{
  "player_id": "p_123",
  "event_type": "achievement", 
  "metadata": {
    "level": 5,
    "map": "intro_forest",
    "difficulty": "normal",
    "session_id": "s_abc123"
  }
}
    

• player_id optional; if absent, SDK may derive a deterministic id.
• event_type may be predefined or custom.
• metadata is JSON and supports both indexed and freeform keys (subset indexed for fast queries).

Response (preview)

{
  "success": true,
  "id": 942381,
  "created_at": "2025-08-10T14:23:01Z"
}
    

Tips

• Idempotency: reuse a session_id and include client timestamps for accurate session stitching.
• Minimal payloads: send only fields you’ll query or analyze later.
• Timezones: send UTC; UI will render in user locale.