Unity Client Overview

Copied!

This section will cover in-depth working with StreamChatClient - the main client to interact with Stream Chat API.

Plugin Structure

Copied!

Stream Chat SDK package consists of multiple modules, among which you'll find a Sample Project and Code Samples.

Stream Chat Unity SDK after importing to Unity

Modules:

Copied!
  1. Config* - Sample config asset

  2. Core - The main logic of the Stream Chat SDK

  3. EditorTools*

  4. Libs - libraries, dependencies

  5. SampleProject* - Example UGUI project

  6. Samples* - Code samples

  7. Tests* - unit & integration tests

* - These folders are optional and can be safely removed. Note that they will not contribute to your application build size as they're wrapped in Unity's Assembly Definition and target only the Editor hence they'll be excluded from the build. The only required modules are Core and Libs

Client Lifecycle

Copied!

There are 4 stages of the StreamChatClient that happen throughout your application's lifecycle:

  1. Initialize - Instantiate and configure the client

  2. Connect - Connect with the Stream server

  3. Update - Update the client per frame

  4. Destroy - Dispose of the client when you're done using it

We'll go through each stage in more detail below.

1. Initialize

Copied!

In order to create an instance of StreamChatClient you can use the static StreamChatClient.CreateDefaultClient factory method as shown in the example below:

This will instantiate the client using the default dependencies.

Note that instantiated client is not yet connected to the Stream server.

Auth Credentials

Copied!

You need to pass valid credentials in order to connect with the Stream server.

param name

description

apiKey

You can get your API KEY from the Dashboard

userId

- In production mode - User ID should be provided by your backend solution

- In development mode - You can enable Developer Tokens

userToken

- In production mode - User Token should be provided by your backend solution

- In development mode - You can enable Developer Tokens

Optional Configuration

Copied!

When creating the client you can pass an optional StreamClientConfig parameter that allows you to set a desired logging level of the client as shown below:

The LogLevel field supports the following options:

  • StreamLogLevel.All - All logs will be emitted. Recommended for development or production mode.

  • StreamLogLevel.FailureOnly - Only Errors and Exception. Recommended for production mode.

  • StreamLogLevel.Debug - Additional logs will be emitted. Useful when debugging the StreamChatClient or internal WebSocket connection.

  • StreamLogLevel.Disabled - Logging is entirely disabled. This option is not recommended.

2. Connect

Copied!

After your client is instantiated and configured you can now establish a connection with the Stream server by calling the streamChatClient.Connect()method.

This is deliberately separated from the initialization step as depending on your scenario, you may wish to defer connection with the server until the user opens a chat window.

3. Update

Copied!

Once the client is connected it needs to be updated every frame by calling streamChatClient.Update(Time.deltaTime). There are a few things that StreamChatClient takes care of when being updated:

  1. Monitor connection health - Detect broken connection as soon as possible

  2. Retry the connection if it gets lost. The interval is based on the retry strategy configuration which you can control via StreamChatClient.SetReconnectStrategySettings method

  3. Exchange messages between the WebSocket buffers

Calling streamChatClient.Update per frame is necessary for the client to work.

4. Destroy

Copied!

After you're done using the client (e.g. closing your application) you should call the streamChatClient.Dispose() method on the client instance to disconnect and clear resources.

Complete Example

Copied!

A common pattern is to wrap the StreamChatClient instance in a MonoBehaviour, here's a complete example of how to instantiate, connect, update and destroy the client:

The Awake(), Update() and OnDestroy() are all Unity's special methods that are automatically called by the Unity Engine on every script that inherits from MonoBehaviour and is attached to an active GameObject in a scene.

Performance

Copied!

The internal WebSocket communication is being handled on the background threads and exchanged with the main thread only via thread-safe buffers, which makes the client perform very efficiently.

Working with the API

Copied!

Working with the API is achieved via 4 API submodules accessible as properties in the StreamChatClient instance:

  • StreamChatClient.ChannelApi - Channel endpoints e.g. Create, Query, Update, Delete

  • StreamChatClient.MessageApi - Message endpoints e.g. Send, Update, Delete, Add reaction, Upload file

  • StreamChatClient.ModerationApi - Moderation endpoints e.g. Mute, Ban, ShadowBan, Flag

  • StreamChatClient.UserApi - User endpoints e.g. Query, Create, Update

Async/Await pattern

Copied!

StreamChatClient utilizes .NET's modern approach to asynchronous programming using the Task async/await model syntax meaning that every call to the API is wrapped in Task as shown in the example below:

Run Task as Callback

Copied!

If you wish to use the client with a classical callback pattern, you can achieve this by using the AsCallback helper method as shown in the example below.

However, we recommend using the async/await pattern as it strongly simplifies the code logic.

Error Handling

Copied!

The StreamChatClient client may throw a StreamApiException in case a request failed on the server, or another type of Exception if it failed in the Unity client.

In the simplest approach you may want to just log the Exception caught in a try/catch block as shown in the example below:

The StreamApiException contains detailed information about what exactly went wrong with your request.

StreamApiException properties:

Property name

Description

StatusCode

Response HTTP status code

Code

API error code. More info here

Message

Message describing an error

MoreInfo

URL with additional information

ExceptionFields

Additional error info

This allows you to apply a dedicated recovery strategy depending on the exact type of the problem.

Example below shows how you can achieve this:

Run Client without Unity Engine

Copied!

It is possible to run the StreamChatClient within .NET/C# application without the Unity Engine. The Core module of the SDK has no dependencies on the Unity Engine. Only a few libraries in the Libs module use Unity Engine API but these can be easily replaced. Consider this Github repository as an example of how to use Stream Chat Unity SDK in a .NET Console Application.