Session Management
Complete guide to creating, maintaining, and terminating game sessions
Session Management
After successfully completing the authorization flow, you must establish and maintain a game session before requesting advertisements. Sessions provide a structured way to track active gameplay and ensure appropriate ad delivery.
Session Lifecycle
- Initiate: Create a new session when gameplay begins
- Maintain: Send regular heartbeat requests to keep the session active
- Terminate: End the session when the player exits the game
Creating a Session
POST /api/games/sessions/initiate
This endpoint establishes a new game session using the authorization token obtained during the authentication process.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
auth_token | string | Yes | The authorization token received from the authentication flow |
Example Request
{
"auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Response Structure
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the session was successfully created |
Example Response (Success)
{
"success": true
}Possible Errors
| Status Code | Error Code | Description |
|---|---|---|
| 400 | ALREADY_IN_GAME | A session is already active for this user |
| 401 | UNAUTHORIZED | Missing or invalid authorization token |
Maintaining a Session
Game sessions require regular heartbeat requests to remain active. Without these requests, the session will expire and you'll need to create a new one.
POST /api/games/sessions/heartbeat
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
auth_token | string | Yes | The authorization token for the active session |
Example Request
{
"auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Response Structure
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the heartbeat was successfully recorded |
Example Response
{
"success": true
}Possible Errors
| Status Code | Error Code | Description |
|---|---|---|
| 400 | NO_ACTIVE_SESSION | No active session found for this user |
| 401 | UNAUTHORIZED | Missing or invalid authorization token |
Terminating a Session
When gameplay ends, you must properly terminate the session. This ensures accurate session tracking and resource cleanup on our servers.
POST /api/games/sessions/end
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
auth_token | string | Yes | The authorization token for the active session |
Example Request
{
"auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Response Structure
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the session was successfully terminated |
Example Response
{
"success": true
}Possible Errors
| Status Code | Error Code | Description |
|---|---|---|
| 400 | NO_ACTIVE_SESSION | No active session to terminate |
| 401 | UNAUTHORIZED | Missing or invalid authorization token |
Best Practices
-
Heartbeat Frequency: Send heartbeat requests every 9 seconds to maintain the session. Sessions without heartbeats will expire after approximately 10 seconds.
-
Error Handling: Implement robust error handling for all session-related requests. If a session expires unexpectedly, be prepared to create a new one.
-
Graceful Termination: Always terminate sessions when the player exits the game to ensure proper resource management.
-
Performance Considerations: Schedule heartbeat requests at regular intervals to avoid overwhelming the client or server.
Next Steps
Once you have an active game session, you can proceed to requesting advertisements to display to the player.