WebSockets
Interacting with web socket servers from Blueprint
You can connect to your web socket server to send/receive JSON messages from blueprint.
This feature is only available in V25 onwards
Usage Overview
To use the web socket connection, create a new instance of the M2 Web Socket Connection class and store it somewhere in a Blueprint graph.
Authentication
Optionally, call Set Actor Auth Context / Set Actor Component Auth Context passing the Morpheus Actor or Morpheus Actor Component you ant to use as the basis for your authentication.
If you opt to include the delegated auth token, then the initial web socket connection will include an auth token used to help you validate the user's M2 Identity.
As part of authentication you can select one of the M2 Web Platform scopes. If you do so, the following additional headers are added to the request:
| Scope | Headers | Description |
|---|---|---|
None | N/A | No extra headers are applied |
Organization | x-m2-organization-id | Applies the current Organization Id of the Metaverse |
Project | x-m2-organization-id x-m2-project-id | Applies the current Organization Id and Project Id of the Metaverse |
World | x-m2-organization-id x-m2-project-id x-m2-world-id | Applies the current Organization Id, Project Id and World Id of the Metaverse |
Launch Context | x-m2-organization-id x-m2-project-id x-m2-launch-context-id | Deprecated Applies the current Organization Id, Project Id and Launch Context Id of the Metaverse |
When connecting to your web socket server, the auth header will be passed in the initial http request headers as an Authorization: Bearer header.
Connecting
To connect to the Web Socket server you call the Connect method on the connection class.
The parameters are as follows:
| Parameter | Description | Required |
|---|---|---|
Url | The web socket URL to connect to. The This URL must conform to the requirements described in Configuing External URL Access | Yes |
Protocol | An optional subprotocol to pass to your server on connection. If not specified, this will default to empty. | No |
Headers | An optional | No |
On Connected | A delegate that is called if the web socket successfully connects. When this event is received, you can send and receive messages. | No, but recommended |
On Connection Error | A delegate that is called if the web socket fails to connect. If this is called, the web socket cannot be used until it is connected. | No, but recommended |
On Disconnected | A delegate that is called if the web socket disconnects. This is called if the disconnection is user driven or the server connection is broken. If this is called, the web socket cannot be used until it is connected. | No, but recommended |
On Message Received | A delegate that is called whenever the web socket receives a message from the server. Messages must be deserializable from a JSON string to be passed to your handler. If you do not provide this delegate, your socket will ignore any messages that are received. | No, but recommended |
Sending Messages
Once your web socket is connected you can send messages via SendJson. This will take a JsonObject and send it to your remote server as a serialized string.
Handling Disconnection
Disconnection can be manually requested by calling the Disconnect event. This will send a default status of 1000 and no reason string.
Your web socket server connection may be disconnected for other means, such as network errors between the client and web socket server, problems in the web socket server or just that the connection is set to time out.
You can call Reconnect to connect to a web socket that has moved into the disconnected state; however you must have called Connect on it beforehand.
Due to the custom nature of many web socket services, we do not provide automatic reconnection logic. You must manage this yourself by calling Reconnect if required.
Last updated
