Project / Asset Set Up

Our asset works quite straight-forward. Just create a GameObject and add the "Socket IO Communicator" component to it. Enter all detail used for connecting into the fields. The Address has to be provided without protocol prefix or any folders. Socket.IO-Namespaces are not supported by this library.

The Socket.IO-Address has to be entered in an URI-Format without protocol: If using standard ports (Insecure: tcp/80, secure: tcp/443) you do not need to enter a port. If using the standard socket.io path (/socket.io/) you do not need to specify a path. WARNING: Paths are not the same as namespaces! A path is what you enter in path-option on server side.

Whenever possible you should not use the "Auto Connect" feature as most likely you will want to setup the listeners ("On") before connecting. See the example for a best practice setup.

Connecting at runtime / from code

Instead of configuring the connection parameters in the component using the inspector, you can also specify the target address at runtime using the Connect() method: void Instance. Connect ( [string targetAddress, bool enableReconnect,][SIOAuthPayload authPayload])

This is described later in this documentation.

Multiple Socket.IO Connections

If you want to connect to more than one Socket.IO server, you have to use one GameObject per connection and you need to name them different. If you use two GameObjects identically named with SocketIOCommunicator Component in WebGL builds, it will result in unexpected behavior because the Socket.IO system depends on unique names from javascript (JSLib) side.

Json.NET for better Json parsing

Why Json.NET

Unfortunately Unity's own JSON "Skills" (JsonUtility) are very limited and everything except reliable when it comes to complex objects – but that's fine as that is not the scope of those methods. There is a very great alternative out there: Newtonsoft Json / JSON.NET – The latter is a fork which has been customized to support Unity's IL2CPP builds (e.g. WebGL).

How do I integrate Json.NET? To utilize that and keep the ease of use of "Emit(eventName, data)" without the third parameter, install the JSON-NET package as described here: https://github.com/jilleJr/Newtonsoft.Json-for-Unity#installation

Afterwards head to your project's player settings and set the "Scripting Define Symbol" HAS_JSON_NET:

Do not set the flag, if you did not install JSON.NET into the project. This would cause compiler errors.

Recent Unity versions bring their own copy of Json.Net. Their package is identical to the „official" Json.Net implementations so you can use whichever your prefer´but installing Json.Net while having unity's variant in the project will cause compiler errors regarding duplicate assemblies.

Unity's variant is currently delivered with the perforce / collab plugin which is enabled by default.

https://docs.unity3d.com/Packages/com.unity.nuget.newtonsoft-json@2.0/manual/index.html

Using the asset / Code Referene

We provide a well-documented example in our asset. Please review the code to get a closer understanding.

The SocketIOCommunicator Component provides access to a singleton "Instance" which contains the actual Socket.IO implementation specific to the platform. You use this to interact with the library. Further in runtime it will create an object called "SIODispatcher" which is a helper for running everything thread safe. This component is used to enqueue actions to be run on the main thread.

The "Instance" provides the API required to interact with Socket.IO. Click here to view it's reference.