Realtime

Provides real-time updates from the Key/Value Store via WebSockets. Ideal for live data synchronization between game clients and backend services.

Connect to the realtime service

get

Creates a websocket connection to the realtime service, sending messages to the realtime service will subscribe you to different resources allowing you to listen to document updates in realtime. When subscribing if a resource doesn't exist yet a listener will be created and will be triggered when the resource is created. If the resource is deleted the listener will still exist so make sure to unsubscribe when you no longer need the resource.

When connecting via a html websocket you will need to parse all of your headers in through Sec-WebSocket-Protocol which is an optional header that takes in a string. Format for the string needs to be a list of headers split by \n and key value split by : and then encoded into base58

Example format

x-m2-organization:testOrg x-m2-project:testProj

Example messages for subscribing to the resources available in the realtime service -

  • KVStore:

      {
          "action": "subscribe",
          "resource": {
              "type": "kvStore",
              "id": "World:kvstoreClient:testKey"
          }
      }
    
  • Collections:

      {
          "action": "subscribe",
          "resource": {
              "type": "collection",
              "id": "public"
          }
      }
    
  • Liveconfig:

      {
          "action": "subscribe",
          "resource": {
              "type": “liveConfig",
              "id": “game"
          }
      }
    

Using the same format, you can also unsubscribe from the resources by changing the action to "unsubscribe" and sending the same resource.

Example response formats below.

Success:

    {
      "userId": "fakeUserId",
      "resource": {
          "type": "collection",
          "id": "private"
      },
      "data": {
          "userId": "fakeUserId",
          "datasourceId": "fakeDatasourceId",
          "userCollection": []
      },
      "version": "2024-01-30T15:50:35.742Z"
    }

Warning:

    {
      "warning": "resource_not_found",
      "message": "KVStore resource doesn't currently exist, subscription was still made successfully"
    }

Error:

    {
      "error": "Invalid message format"
    }
Authorizations
Header parameters
x-m2-organization-idstringRequired

The ID of an organization

x-m2-project-idstringOptional

The ID of a project

x-m2-world-idstringOptional

The ID of a world

Responses
101
Default Response
application/json
Responseany of
stringOptional

Provides information about the service status.

or
or
get
GET /api/realtime/connect/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
Accept: */*
text

Last updated

Was this helpful?