WebSockets
With version 48 we have expanded the Blueprint Secure Networking Interface to include support for WebSockets.
The implementation pattern for WebSockets you will find is very similar to HTTP Requests.
IMPORTANT NOTE:Â Custom Cosmetics mods cannot Create or interact with WebSockets. No exceptions, they are blocked from doing so. Any attempts to circumvent this will be dealt with.
CONSOLES REQUIRE SECURE CONNECTIONS: If your mod is crossplatform and you require the use of WebSockets on console clients then you must use a secure connection. Some platforms will outright refuse to allow the connection otherwise so make sure your service supports wss and not just ws protocol. This is not something we can change it is a requirement enforced by the platform.
Step 1: Add the interface
The first step is to figure out what blueprint you want to use to send and receive network requests. On this blueprint go to Class Settings and then to the Interface section. Search for BPSecureNetworkingInterface and add it.
This will add a set of events and implementable functions to your blueprint. you do not have to use all of them, only implement what you need.
The Audit functions are a key component, if they are not implemented then requests of that type will not be sent by the game at all.
Step 2: Set up your Audits
The Audit functions are you opportunity as a mod author to ensure that the WebSocket functions that ctreate, Open, and close a websocket being sent in the name of your mod are legitimate and not being used as a vector for exploitation. Optionally when you make the request to can enable auditing every message sent through the websocket but by default that does not require auditing.
Their use is simple; returning True will allow the request/action to be sent, False will block it.
A bare minimum that we recommend is maintaining a list of endpoints that you are intending to use and checking to make sure the URL is one of those listed.
Step 3: Create a WebSocket
Use the function Create WebSocket to actually create the WebSocket Instance. At this time the audit implementation will be called if it passes all other validations.
A valid socket ID will be returned if the websocket is successfully created. Make sure to save your socket IDs, you will need it in order to perform any other actions with the WebSocket.
As a rule not only must you have the ID of a websocket but the same object that requested its creation is also the only one that can act on the websocket. if the object that manages the websocket is ever destroyed then the websocket will be closed and disposed of.
Important note: There is a known issue (Discovered as I was writing this documentation) where if a Websocket fails to be created that the last socket ID created will be returned. This is an error and will be fixed in a subsequent update. In the future it will return a value of -1 when the socket fails to be created
Step 4: Connect the WebSocket
Creating a WebSocket does not automatically connect it. When you are ready to connect your WebSocket call the function Connect WebSocket. You will have to pass a valid socket ID AND it will only work if the calling object is the same one that created the WebSocket.
At this time the audit for connection will be executed. After the connection attempt, if it succeeds the On WebSocket Connected event will be triggered. Otherwise the On Websocket Connection Error event will be triggered. Handle these events accordingly.
Step 5: Sending and Receiving Messages
Once your WebSocket has connected, you are ready to begin sending and receiving messages. Websockets allow two way communication with a remote service. Unlike requests, once connected a remote service can send messages to your connection without being prompted.
Before sending messages it may be a good idea to confirm the connection using the Is WebSocket Connected function, which will only return true if the websocket is connected and the calling object is the owner of the websocket.
To send a message through your websocket use the Send Message to WebSocket function. Currently this only supports strings. Blueprint does not currently have a great way to handle binary data arbitrarily, so it is not currently supported to send and receive binary messages.
Messages received by the websocket will be available on the On WebSocket Message Recieved event (I am kicking myself for not seeing that typo, we're stuck with it now)
There is also an event for when messages are sent but this is more for completing the implementation as it was available in the native WebSocket support. So if you have a use for it, it exists.
Step 6: Closing the WebSocket
When you are done with your WebSocket, simply call Close WebSocket. The connection will be closed and the websocket disposed of. You won't be able to reopen it again once closed, you'll have to create a new websocket if you want to reconnect.
