Activity Tracking - Chizverse

BASE API : https://api-chizverse.beespokedev.com

Activity Tracking is the canonical gameplay lifecycle API. Create a launch before opening the game, exchange the launchToken for a tracked session, batch gameplay events with the returned sessionKey, and end the session with a final flush. ChizPay game transactions should use the returned sessionId as the gameSession value so wallet ledger rows can be reconciled with gameplay telemetry.

Session Lifecycle

Create Launch with Game Manager.
Open the game URL with chz_launch_token.
Create Tracked Session from the launch token.
Track gameplay events in ordered batches.
Flush queued events during critical transitions.
End Session with game.session.ended.

Endpoints

Create Launch

Creates a tracked game launch and returns the launchToken required for session initialization.

Method & URL

POST /game-manager/v1.0/games/{gameId}/launches

Headers

Name	Type	Required	Description
`authorization`	string	Yes	ChizVerse bearer returned by `POST /core/public/auth/chizmis`. Example: `Bearer <token>`.

Path Parameters

Name	Type	Required	Description
`gameId`	string \| number	Yes	Game identifier to launch.

Getting `gameId`

Open the ChizVerse Developer Console and go to the game list. The gameId is the number shown under the game title, for example #27.

Find the Game ID in the Developer Console game list

Request Body

Name	Type	Required	Description
`allowedOrigin`	string	Yes	Allowed origin/domain where the game is launched.
`buildId`	number	Yes	Game build identifier.
`gameVersionId`	number	Yes	Published game version identifier.
`launchSource`	enum(`CATALOG_PLAY`, `CONSOLE_PREVIEW`)	No	Launch source. Defaults to `CATALOG_PLAY`.
`metadata`	object	No	Optional launch metadata.

`launchSource` values

CATALOG_PLAY: Player launched the game from public catalog/store surfaces.
CONSOLE_PREVIEW: Developer/admin launched the game from console tools for internal preview/testing.

{
  "allowedOrigin": "https://chizverse.beespokedev.com/",
  "buildId": 120,
  "gameVersionId": 12,
  "launchSource": "CATALOG_PLAY",
  "metadata": {
    "region": "ph"
  }
}

Response Example

{
  "success": true,
  "response": {
    "launchToken": "launch_abc123",
    "apiBaseUrl": "https://api-chizverse.beespokedev.com",
    "expiresAt": "2026-05-06T11:00:00.000Z",
    "queryParams": {
      "chz_api_base_url": "https://api-chizverse.beespokedev.com",
      "chz_launch_token": "launch_abc123"
    }
  }
}

Getting `launchToken`

Use response.launchToken (or response.queryParams.chz_launch_token) from this endpoint as the launchToken value for Create Tracked Session.

Error Responses

Status	Meaning	Example Message
`400`	Invalid payload	`buildId is required`
`401`	Unauthorized client	`Unauthorized`
`404`	Game/build/version not found	`Game not found`
`500`	Internal server error	`Internal server error`

Create Tracked Session

Creates a new tracked session using a launch token.

Method & URL

POST /game-manager/v1.0/sdk/sessions

Headers

No custom headers required.

Request Body

Name	Type	Required	Description
`clientOrigin`	string	Yes	Origin identifier of the game client.
`clientPlatform`	enum(`web`, `desktop`)	Yes	Platform where the game runs.
`launchToken`	string	Yes	Launch token from Create Launch (`response.launchToken` or `response.queryParams.chz_launch_token`).
`sdkVersion`	string	Yes	SDK version sending the request.
`metadata`	object	No	Optional extra context data.

{
  "clientOrigin": "chizverse-portal",
  "clientPlatform": "web",
  "launchToken": "launch_abc123",
  "sdkVersion": "1.2.0",
  "metadata": {
    "gameId": "space-racer",
    "region": "ph"
  }
}

Response Example

{
  "success": true,
  "response": {
    "acceptedEventTypes": [
      "game.session.started",
      "game.presence.changed",
      "game.score.updated",
      "game.metric.recorded",
      "game.progress.updated",
      "game.session.paused",
      "game.session.resumed",
      "game.session.ended",
      "game.session.heartbeat"
    ],
    "flushIntervalMs": 5000,
    "heartbeatIntervalSeconds": 30,
    "maxBatchSize": 20,
    "sessionId": "123",
    "sessionKey": "sesskey_abc123"
  }
}

Error Responses

Status	Meaning	Example Message
`400`	Invalid payload	`launchToken is required`
`401`	Unauthorized client	`Unauthorized`
`404`	Launch token not found	`Invalid launch token`
`500`	Internal server error	`Internal server error`

Tracking Flow

Call Create Launch to get a launchToken.
Call Create Tracked Session with that launchToken.
Use returned sessionId and sessionKey for Ingest Event Batch.

Get Session Checkpoint

Returns the latest active tracked-session state. Use this after session start to resume score, level, presence, and progress snapshot state.

Method & URL

GET /game-manager/v1.0/sdk/sessions/{sessionId}/checkpoint

Headers

Name	Type	Required	Description
`x-session-key`	string	Yes	Session key returned by Create Tracked Session.

Path Parameters

Name	Type	Required	Description
`sessionId`	string	Yes	Active tracked session ID.

Response Example

{
  "success": true,
  "response": {
    "sessionId": "123",
    "gameId": 27,
    "gameVersionId": 12,
    "buildId": 120,
    "status": "active",
    "presenceState": "in_game",
    "levelId": "zone-3",
    "currentScore": 1250,
    "progressSnapshot": {
      "levelId": "zone-3",
      "completionPercent": 60,
      "checkpointId": "checkpoint-3",
      "metadata": {
        "coins": 240
      }
    },
    "lastSequence": 18,
    "lastEventAt": "2026-05-06T10:35:00.000Z"
  }
}

Error Responses

Status	Meaning	Example Message
`401`	Missing or invalid session key	`Unauthorized`
`404`	Session not found	`Session not found`
`409`	Session is not active	`Session is not active.`
`500`	Internal server error	`Internal server error`

Returns the latest durable progress for the player and game associated with the authenticated session. This is separate from the active-session checkpoint and can survive a new session key.

Method & URL

GET /game-manager/v1.0/sdk/sessions/{sessionId}/player-progress

Headers

Name	Type	Required	Description
`x-session-key`	string	Yes	Session key returned by Create Tracked Session.

Path Parameters

Name	Type	Required	Description
`sessionId`	string	Yes	Tracked session ID used to identify the player and game.

Response Example

{
  "success": true,
  "response": {
    "gameId": 27,
    "uid": 1024,
    "levelId": "campaign-1-level-3",
    "progressSnapshot": {
      "levelId": "campaign-1-level-3",
      "completionPercent": 100,
      "milestoneKey": "level_completed",
      "metadata": {
        "nextLevelId": "campaign-1-level-4",
        "saveState": {
          "health": 85,
          "coins": 240
        }
      }
    },
    "lastSessionId": "123",
    "lastEventAt": "2026-05-06T10:35:00.000Z"
  }
}

When no saved progress exists, the endpoint returns:

{
  "success": true,
  "response": null
}

Error Responses

Status	Meaning	Example Message
`401`	Missing or invalid session key	`Unauthorized`
`404`	Session not found	`Session not found`
`500`	Internal server error	`Internal server error`

Ingest Event Batch

Ingests an ordered batch of gameplay events for an active session.

Method & URL

POST /game-manager/v1.0/sdk/events/batch

Headers

Name	Type	Required	Description
`x-session-key`	string	Yes	Session key returned by session initialization.

Request Body

Name	Type	Required	Description
`sessionId`	string	Yes	Session identifier for event ownership.
`events`	array	Yes	Ordered list of events to ingest.
`events[].eventId`	string	Yes	Unique event identifier.
`events[].eventType`	string	Yes	Event name/category.
`events[].eventVersion`	number	Yes	Event schema version.
`events[].occurredAt`	string(date-time)	Yes	Event timestamp (ISO-8601).
`events[].sequence`	number	Yes	Incremental order in the session.
`events[].sessionId`	string	Yes	Session identifier repeated per event.
`events[].clientOrigin`	string \| null	No	Optional origin marker.
`events[].clientPlatform`	enum(`web`, `desktop`)	Yes	Origin platform of event.
`events[].sdkVersion`	string	Yes	SDK version emitting event.
`events[].payload`	object	Yes	Event-specific payload.

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_001",
      "eventType": "quest.completed",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:30:00.000Z",
      "sequence": 14,
      "sessionId": "sess_123",
      "clientOrigin": "chizverse-portal",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "questId": "daily-coin-run",
        "coinsEarned": 250
      }
    }
  ]
}

Response Example

{
  "success": true,
  "response": {
    "accepted": 1,
    "lastSequence": 14,
    "published": 1,
    "rejected": 0
  }
}

Error Responses

Status	Meaning	Example Message
`400`	Invalid payload	`events is required`
`401`	Invalid session key	`Unauthorized`
`404`	Session not found	`Session not found`
`500`	Internal server error	`Internal server error`

Event Mapping

setPresence -> game.presence.changed
trackScore -> game.score.updated
trackMetric -> game.metric.recorded
updateProgress -> game.progress.updated
saveProgress -> queues game.progress.updated, flushes the batch, then reads saved progress
pauseSession -> game.session.paused
resumeSession -> game.session.resumed
endSession -> game.session.ended
flush -> sends all queued event types in one batch

Usage Examples

setPresence -> game.presence.changed
Use this when player presence/state changes (for example menu, in-game, paused).

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_presence_001",
      "eventType": "game.presence.changed",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:30:00.000Z",
      "sequence": 10,
      "sessionId": "sess_123",
      "clientOrigin": "chizverse-portal",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "state": "menu",
        "reason": "opened_inventory"
      }
    }
  ]
}

trackScore -> game.score.updated
Use this to report score updates, including both total score and incremental delta.

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_score_001",
      "eventType": "game.score.updated",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:31:00.000Z",
      "sequence": 11,
      "sessionId": "sess_123",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "score": 1250,
        "delta": 50,
        "reason": "combo_x5"
      }
    }
  ]
}

trackMetric -> game.metric.recorded
Use this for custom gameplay metrics such as counters, gauges, or labeled telemetry values.

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_metric_001",
      "eventType": "game.metric.recorded",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:32:00.000Z",
      "sequence": 12,
      "sessionId": "sess_123",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "metricKey": "bullets_fired",
        "value": 3,
        "aggregation": "increment",
        "labels": {
          "weapon": "pistol"
        }
      }
    }
  ]
}

updateProgress -> game.progress.updated
Use this to report progression milestones like level advancement or completion percentage.

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_progress_001",
      "eventType": "game.progress.updated",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:33:00.000Z",
      "sequence": 13,
      "sessionId": "sess_123",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "levelId": "zone-3",
        "completionPercent": 60
      }
    }
  ]
}

pauseSession -> game.session.paused
Use this when gameplay is temporarily paused and the session should be marked inactive.

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_pause_001",
      "eventType": "game.session.paused",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:34:00.000Z",
      "sequence": 14,
      "sessionId": "sess_123",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "reason": "player_paused"
      }
    }
  ]
}

resumeSession -> game.session.resumed
Use this when gameplay resumes after a pause and active play continues.

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_resume_001",
      "eventType": "game.session.resumed",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:35:00.000Z",
      "sequence": 15,
      "sessionId": "sess_123",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "reason": "player_unpaused"
      }
    }
  ]
}

endSession -> game.session.ended
Use this when a run/match ends, including final outcome details (reason, score, duration).

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_end_001",
      "eventType": "game.session.ended",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:36:00.000Z",
      "sequence": 16,
      "sessionId": "sess_123",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "reason": "completed",
        "finalScore": 4200,
        "durationSeconds": 180
      }
    }
  ]
}

flush -> batch send of queued events
Use this to immediately send queued events instead of waiting for the next automatic batch cycle.

{
  "sessionId": "sess_123",
  "events": [
    {
      "eventId": "evt_any_001",
      "eventType": "game.metric.recorded",
      "eventVersion": 1,
      "occurredAt": "2026-05-06T10:40:00.000Z",
      "sequence": 20,
      "sessionId": "sess_123",
      "clientPlatform": "web",
      "sdkVersion": "1.2.0",
      "payload": {
        "metricKey": "deaths",
        "value": 1,
        "aggregation": "increment"
      }
    }
  ]
}

Get Game Leaderboard

Fetches leaderboard standings for a game. The SDK calls this directly and it does not require an active tracked session.

Method & URL

GET /leaderboard/v1.0/leaderboards/games/{gameId}

Path Parameters

Name	Type	Required	Description
`gameId`	string \| number	Yes	Game identifier.

Query Parameters

Name	Type	Required	Default	Description
`type`	enum(`ALL_TIME`, `DAILY`, `WEEKLY`)	No	`ALL_TIME`	Leaderboard period.
`limit`	number	No	`5`	Number of entries to return. Capped at `20`.

Response Example

{
  "success": true,
  "response": {
    "entries": [
      {
        "id": 501,
        "leaderboardId": 44,
        "uid": 1024,
        "rank": 1,
        "score": 4200,
        "playerSnapshot": {
          "displayName": "Juan",
          "avatar": "https://cdn.example.com/avatar.png"
        }
      }
    ],
    "leaderboardId": 44,
    "leaderboardType": "ALL_TIME",
    "resetAt": null,
    "totalPlayers": 12
  }
}

If no leaderboard has been created for the game yet, the API returns an empty response:

{
  "success": true,
  "response": {
    "entries": [],
    "leaderboardId": null,
    "leaderboardType": "ALL_TIME",
    "resetAt": null,
    "totalPlayers": 0
  }
}

Error Responses

Status	Meaning	Example Message
`422`	Invalid game id	`Invalid game id.`
`500`	Internal server error	`Internal server error`

New Session Flow

The SDK startNewSession() helper creates a fresh launch and then creates a fresh tracked session. Use the same API sequence when implementing this flow manually:

End or flush the current session as appropriate.
Call Create Launch again with the same gameId, buildId, and gameVersionId.
Call Create Tracked Session with the new launchToken.
Continue sending gameplay events with the new sessionId and sessionKey.

This is useful for a New Game button where each run should have a separate tracked session and leaderboard outcome.

Activity Tracking API

Session Lifecycle

Endpoints

Create Launch

Method & URL

Headers

Path Parameters

Getting gameId

Request Body

launchSource values

Response Example

Getting launchToken

Error Responses

Create Tracked Session

Method & URL

Headers

Request Body

Response Example

Error Responses

Tracking Flow

Get Session Checkpoint

Method & URL

Headers

Path Parameters

Response Example

Error Responses

Get Saved Player Progress

Method & URL

Headers

Path Parameters

Response Example

Error Responses

Ingest Event Batch

Method & URL

Headers

Request Body

Response Example

Error Responses

Event Mapping

Usage Examples

Get Game Leaderboard

Method & URL

Path Parameters

Query Parameters

Response Example

Error Responses

New Session Flow

Getting `gameId`

`launchSource` values

Getting `launchToken`