> ## Documentation Index > Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt > Use this file to discover all available pages before exploring further. # WebSocket connection (Socket.IO) > ## WebSocket Real-Time Events This is a **Socket.IO** WebSocket endpoint, not a REST endpoint. This documentation describes the WebSocket protocol. ### Connection Connect using a Socket.IO client to the `/events` path: ```js import { io } from "socket.io-client"; const socket = io("https://{domain}/nbc", { path: "/players/@me/events", transports: ["websocket", "polling"], auth: { bearer: "" } }); ``` ### Authentication Provide a valid **player JWT token** in the `auth.bearer` field during the handshake. Connections without a valid token are rejected with an `Unauthorized` error. ### Events (Server → Client) | Event | Payload | Description | |-------|---------|-------------| | `game.event.update` | `string` (dataType) | Emitted when a game event occurs for the connected player. The payload is the event's `dataType` string (see examples below). | ### dataType values The `dataType` payload is a string identifying what happened. Common examples: | dataType | Trigger | |----------|---------| | `LEVEL_UP` | Player reached a new level | | `REWARD_DISTRIBUTED` | A reward was given to the player | | `QUEST_COMPLETED` | Player completed a quest | | `QUEST_STARTED` | A quest was started for the player | | `CHALLENGE_COMPLETED` | Player completed a challenge | | `CHALLENGE_PROGRESS_UPDATED` | Progress on a challenge changed | | `PERK_REWARDED` | A perk was awarded to the player | | `PERK_ACTIVATED` | Player activated a perk | | `DAILY_CLAIMED` | Player claimed a daily bonus | | `ACHIEVEMENT_REWARD_CLAIMED` | Player claimed an achievement reward | | `LEADERBOARD_ROTATED` | A leaderboard rotation occurred | | `POLL_VOTE_SUBMITTED` | Player submitted a poll vote | | `ASSIGNMENT_GIVEN` | An assignment was given to the player | | `ASSIGNMENT_COMPLETED` | Player completed an assignment | | `USER_CREATED` | A new user was created | Use `dataType` to decide which parts of the UI to refresh (e.g., re-fetch quests on `QUEST_COMPLETED`, re-fetch balance on `REWARD_DISTRIBUTED`). ### Example: Listening to events ```js socket.on("game.event.update", (dataType) => { switch (dataType) { case "REWARD_DISTRIBUTED": refreshBalance(); break; case "QUEST_COMPLETED": refreshQuests(); break; case "LEVEL_UP": showLevelUpAnimation(); break; default: console.log("Event received:", dataType); } }); socket.on("connect_error", (err) => { console.error("Connection failed:", err.message); }); ``` ## OpenAPI ````json GET /nbc/players/@me/events { "openapi": "3.0.0", "info": { "title": "Loyalty API", "version": "1.0.0", "description": "Combined API documentation. Includes: Player API, Admin API, Redeem Options API, Notifications API" }, "servers": [ { "url": "https://{domain}" } ], "tags": [ { "name": "Admin", "description": "Endpoint with unlimited access" }, { "name": "Users", "description": "Endpoint to get information for one or more users" }, { "name": "Tokens", "description": "Tokens related endpoints" }, { "name": "Perks", "description": "Perks related endpoints" }, { "name": "System", "description": "Not business logic information" }, { "name": "Quests", "description": "Quests related endpoints" }, { "name": "Daily", "description": "Daily bonus related endpoints" }, { "name": "Rewards", "description": "Rewards related endpoints" }, { "name": "Achievements", "description": "Achievements related endpoints" }, { "name": "Segments", "description": "Segments related endpoints" }, { "name": "Reward Rules", "description": "Game rules related endpoints" }, { "name": "Level Config", "description": "Level config related endpoints" }, { "name": "Schedule", "description": "Schedule related endpoints" }, { "name": "Scheduled Events", "description": "Scheduled events related endpoints" }, { "name": "Leaderboards", "description": "Leaderboards related endpoints" }, { "name": "Auth", "description": "Authorization" }, { "name": "Documentation", "description": "Documentation" }, { "name": "Feedback", "description": "Feedback" }, { "name": "File System", "description": "File System" }, { "name": "I18n", "description": "Internationalization" }, { "name": "Integrations", "description": "Integrations" }, { "name": "Permissions", "description": "Permissions" }, { "name": "Rewarder", "description": "Rewarder" }, { "name": "Widgets", "description": "Widgets" }, { "name": "Redeem Options", "description": "" }, { "name": "Redeem Providers", "description": "" } ], "x-readme": {}, "paths": { "/nbc/players/@me/events": { "get": { "description": "\n## WebSocket Real-Time Events\n\nThis is a **Socket.IO** WebSocket endpoint, not a REST endpoint. This documentation describes the WebSocket protocol.\n\n### Connection\n\nConnect using a Socket.IO client to the `/events` path:\n\n```js\nimport { io } from \"socket.io-client\";\n\nconst socket = io(\"https://{domain}/nbc\", {\n path: \"/players/@me/events\",\n transports: [\"websocket\", \"polling\"],\n auth: {\n bearer: \"\"\n }\n});\n```\n\n### Authentication\n\nProvide a valid **player JWT token** in the `auth.bearer` field during the handshake. Connections without a valid token are rejected with an `Unauthorized` error.\n\n### Events (Server → Client)\n\n| Event | Payload | Description |\n|-------|---------|-------------|\n| `game.event.update` | `string` (dataType) | Emitted when a game event occurs for the connected player. The payload is the event's `dataType` string (see examples below). |\n\n### dataType values\n\nThe `dataType` payload is a string identifying what happened. Common examples:\n\n| dataType | Trigger |\n|----------|---------|\n| `LEVEL_UP` | Player reached a new level |\n| `REWARD_DISTRIBUTED` | A reward was given to the player |\n| `QUEST_COMPLETED` | Player completed a quest |\n| `QUEST_STARTED` | A quest was started for the player |\n| `CHALLENGE_COMPLETED` | Player completed a challenge |\n| `CHALLENGE_PROGRESS_UPDATED` | Progress on a challenge changed |\n| `PERK_REWARDED` | A perk was awarded to the player |\n| `PERK_ACTIVATED` | Player activated a perk |\n| `DAILY_CLAIMED` | Player claimed a daily bonus |\n| `ACHIEVEMENT_REWARD_CLAIMED` | Player claimed an achievement reward |\n| `LEADERBOARD_ROTATED` | A leaderboard rotation occurred |\n| `POLL_VOTE_SUBMITTED` | Player submitted a poll vote |\n| `ASSIGNMENT_GIVEN` | An assignment was given to the player |\n| `ASSIGNMENT_COMPLETED` | Player completed an assignment |\n| `USER_CREATED` | A new user was created |\n\nUse `dataType` to decide which parts of the UI to refresh (e.g., re-fetch quests on `QUEST_COMPLETED`, re-fetch balance on `REWARD_DISTRIBUTED`).\n\n### Example: Listening to events\n\n```js\nsocket.on(\"game.event.update\", (dataType) => {\n switch (dataType) {\n case \"REWARD_DISTRIBUTED\":\n refreshBalance();\n break;\n case \"QUEST_COMPLETED\":\n refreshQuests();\n break;\n case \"LEVEL_UP\":\n showLevelUpAnimation();\n break;\n default:\n console.log(\"Event received:\", dataType);\n }\n});\n\nsocket.on(\"connect_error\", (err) => {\n console.error(\"Connection failed:\", err.message);\n});\n```\n ", "operationId": "WebSocketDocsController_getWebSocketDocs", "parameters": [ { "name": "scrimmage-namespace", "in": "header", "description": "Namespace", "required": false, "schema": { "type": "string", "default": "staging" } }, { "name": "Scrimmage-Version", "in": "header", "description": "Version", "required": false, "schema": { "type": "string" } } ], "responses": { "405": { "description": "This is a WebSocket endpoint. Use a Socket.IO client to connect to /events." } }, "security": [ { "bearer": [] } ], "summary": "WebSocket connection (Socket.IO)", "tags": [ "WebSocket" ] } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } } ````