Release notes

v2.1.9

v2.1.9 was released on February 22, 2024.

This is the first release of the Signaling SDK for Unity v2.x, which brings innovation in functional coverage, performance improvement, and experience optimization.

• Functional coverage: v2.x covers more business use-cases by introducing functional modules such as channels, messages, topics, presence, storage, and locks. This enables you to focus more on your own business innovation.
• Performance improvement: v2.x implements a restructured technical architecture and enhances performance through optimized network connections. Our long-term real-time network access capabilities ensure high service quality characterized by low latency, high reliability, extensive concurrency, and robust extensibility.
• Experience optimization: We have revamped and streamlined our APIs to support the widely adopted Async/Await programming model in the industry. Additionally, we have enriched our documentation, including user guides and API references, with extensive sample code to provide you with comprehensive developer resources. These improvements significantly reduce the effort required to understand and integrate the SDK, ultimately enhancing development efficiency.

Compatibility changes

This release improves the following features, ensure that you modify the implementation of the relevant features after upgrading the SDK.

• Message publish options

  This release optimizes the options parameter of the PublishAsync and PublishTopicMessageAsync methods as follows:

  • Removes the sendTs parameter, and adds the channelType parameter in PublishOptions of the PublishAsync method. See details in PublishOptions.
  • Modify the type of the options parameter in the PublishTopicMessageAsync method from PublishOptions to TopicMessageOptions. See details in TopicMessageOptions.

• Connection state callback renaming

  This release changes the name of the onConnectionStateChange callback to onConnectionStateChanged.

New features

v2.1.9 provides the following core functional modules:

1. Initial configuration

   The initial configuration of the Signaling client involves pre-defining or configuring key parameters that influence its subsequent behaviors. Additionally, it offers functions such as login and logout. The core competencies of the Signaling client are as follows:

   • createAgoraRtmClient: Create an instance of the Signaling client and perform the initial configuration as follows:
     • appId: Set the App ID to enable communication between apps with the same ID while isolating apps with different IDs.
     • userId: Set the user ID to distinguish users or devices.
     • areaCode: Set the area code for the geo-fencing feature.
     • presenceTimeout: Set the presence timeout.
     • useStringUserId: Set the data type of the user ID, which can be of type string or type uint.
     • logConfig: Configure the log file size, log file path, and output level.
     • proxyConfig: Configure whether to enable proxy.
     • encryptionConfig: Configure whether to enable encryption.
   • Event handling: Implement event notification for the events such as onMessageEvent, onPresenceEvent, onTopicEvent, onStorageEvent , onLockEvent, onConnectionStateChanged, and onTokenPrivilegeWillExpire.
   • login: Log into the Signaling service.
   • logout: Log out of the Signaling service.
   • release: Destroy the Signaling client.

2. Channel

   In the Signaling real-time network, channels serve as a mechanism for managing data transmission. When a user subscribes to or joins a channel, they can receive messages and events transmitted within the channel with a latency of up to 100 milliseconds. Signaling enables clients to subscribe to hundreds or even thousands of channels. Most Signaling APIs perform operations such as sending, receiving, and encrypting data on a channel basis.

   Signaling includes two types of channels, message channel and stream channel, each offering distinct core capabilities as follows:

   • Message channel:
     • subscribe: Subscribe to the specified message channel and receive messages and event notifications in the channel.
     • unsubscribe: Unsubscribe from the specified message channel and stop receiving messages and event notifications in the channel.
   • Stream channel:
     • createStreamChannel: Create a stream channel instance and then call relevant APIs.
     • join: Join the stream channel and receive messages and event notifications in the channel.
     • leave: Leave the stream channel and stop receiving messages and event notifications in the channel.
     • release: Destroy the stream channel.

   By calling different methods, the SDK triggers different event notifications.

   • The subscribe, unsubscribe, join, and leave methods trigger the onPresenceEvent event notification. Other users in the channel receive the corresponding Join and Leave event notifications.
   • When calling subscribe and join to subscribe or join a channel, you can choose whether to configure withMessage, withPresence, withMetadata, withLock, and other parameters to enable or disable the monitoring of the corresponding event. To enable the monitoring, you also need to register the corresponding event listener to receive corresponding event notifications.

3. Message

   The basis of Signaling is the ability to send messages. You can send messages to channels anytime, anywhere, and the messages are delivered within 100 milliseconds. Signaling supports message payloads of both string and binary type.

   Call publish to send a message to the specified message channel. Calling publish triggers the onMessageEvent event notification. If you want to receive messages in the channel, set withMessage to true when calling subscribe and register the event handler for the onMessageEvent event.

4. Topic

   In stream channels, topics serve as a data flow management mechanism. This feature allows you to subscribe to, distribute, and notify events related to data streams within stream channels. By leveraging topics effectively, you can significantly reduce business complexity and enhance development efficiency. The main functions of topics are as follows:

   • joinTopic: Register as the publisher of this topic to gain the ability to send messages.
   • publishTopicMessage: Send a message to the topic in the stream channel.
   • leaveTopic: Unregister as the message publisher of this topic.
   • subscribeTopic: Subscribe to one or more message publishers of the topic in this channel.
   • unsubscribeTopic: Unsubscribe from this topic or unsubscribe from one or more message publishers in this topic.

   Register (joinTopic) and unregister (leaveTopic) as a message publisher trigger the onTopicEvent event notification that is sent to other users in the channel.

1. Presence

   Presence provides the ability to monitor the online status and temporary status changes of users. With presence, you can obtain real-time information as follows:

   • Real-time event notification when a user joins or leaves a specified channel.
   • Real-time event notification when the custom temporary user state changes.
   • Query which channels a specified user has joined or subscribed to.
   • Query which users have joined a specified channel and their temporary user state data.

   The following features can be used in both message channels and stream channels:

   • getOnlineUsers: Get real-time information about the number of online users, the list of online users, and their temporary status in a specified channel.
   • getUserChannels: Get real-time information about the list of channels which a specific user joins.
   • setState: Set the temporary status of a user in a specified channel.
   • getState: Get the temporary status of a user in a specified channel.
   • removeState: Remove the temporary status of a user in a specific channel.

   In addition, presence also provides event notification capabilities through the onPresenceEvent. Events such as users joining, leaving, going offline, setting user state, and removing user state are sent as notifications to other users in the channel in real time (Announce Mode) or at regular intervals (Interval Mode). Presence greatly simplifies the implementation of the synchronization logic related to user online and offline status and state changes. This feature helps make your business more stable, real-time, and reliable.

2. Storage

   The storage feature provides a dynamic database mechanism that allows developers to dynamically set, store, update, and delete channel metadata and user metadata. It also listens to the events generated by changes of channel metadata or user metadata.

   • Channel metadata

     • setChannelMetadata: Set the channel metadata or channel metadata item for a specified channel.
     • getChannelMetadata: Get the channel metadata and channel metadata item for a specified channel.
     • removeChannelMetadata: Remove the channel metadata or channel metadata item for a specified channel.
     • updateChannelMetadata: Update the existing channel metadata or channel metadata item for a specified channel.

     Setting, deleting, and updating channel metadata trigger the onStorageEvent event notification. This feature can greatly optimize your business logic and provide an excellent user experience. Currently, the event notification onStorageEvent carries the complete information of the current channel metadata. It will be optimized in future versions to provide incremental update capabilities.

     Channel metadata also introduces the ability to control locks. When calling APIs to set, delete, or update channel metadata, if the lockName parameter is set, lock verification is enabled. In this case, only the owners of the lock can call the corresponding methods successfully.

   • User Metadata

     • setUserMetadata: Set the user metadata or a user metadata item for a specified user.
     • getUserMetadata: Get the user metadata or a user metadata item for a specified user.
     • removeUserMetadata: Remove the user metadata or a user metadata item for a specified user.
     • updateUserMetadata: Update the existing user metadata or a user metadata item for a specified user.
     • subscribeUserMetadata: Subscribe to event notifications for changes in user metadata or a user metadata item for a specified user.
     • unsubscribeUserMetadata: Unsubscribe from event notifications for changes in user metadata or a user metadata item for a specified user.

     Setting, deleting, and updating user metadata trigger the onStorageEvent event notification. Other users subscribed to this user metadata receive the event notifications. This feature can greatly optimize your business logic and provide an excellent user experience. Currently, the onStorageEvent event notification carries the complete information of the current user metadata. It will be optimized in future versions to provide incremental update capabilities.

   • Compare And Set (CAS) control

     Both channel metadata and user metadata introduce the CAS version control logic, which provides two independent version control fields that you can use according to your business use-case:

     • Enable version number verification for the entire set of channel metadata by setting the majorRevision property in the Metadata class.
     • Enable version number verification for a single metadata item by setting the revision property in the MetadataItem class within the RtmMetadata class.

     When setting, deleting, or updating channel metadata or user metadata, you can control whether to enable revision verification by using the majorRevision or revision property. The logic is as follows:

     • If majorRevision or revision is set to -1, the CAS validation is not enabled for this call. If the metadata or metadata item already exists, it is overwritten by the latest value. If the metadata or metadata item does not exist, a new metadata or metadata item is created.
     • If majorRevision or revision is set as a positive Int64 integer, the CAS validation is enabled for this call. If the metadata or metadata item already exists, the value is updated after successful version number validation. If the metadata or metadata item does not exist, the SDK returns an error code.

3. Lock

   A critical resource can only be used by one process at a time. If different processes share a critical resource, they need to adopt a mutually exclusive approach to prevent interference. Signaling offers a comprehensive set of lock solutions and process control in distributed systems, enabling you to effectively manage competition among users accessing shared resources. Lock provides the following capabilities:

   • setLock: Set a lock for a specified channel.
   • acquireLock: Acquire a specified lock in a specified channel.
   • releaseLock: Release a specified lock in a specified channel.
   • revokeLock: Revoke the ownership of a specific user for a lock in a specified channel to release the lock.
   • getLocks: Get the details of all locks in a specified channel.
   • removeLock: Remove a specified lock in a specified channel.

   The lock setting, acquisition, release, revocation, and deletion operations trigger the corresponding onLockEvent event notification. You can make full use of this feature to optimize the implementation logic of your business.

4. This release adds the GetOnlineUsersAsync method to replace the WhoNowAsync method, and the GetUserChannelsAsync method to replace the WhereNowAsync method.

Improvements

• Error codes

  This release adds the following error codes: INVALID_CHANNEL_TYPE, INVALID_ENCRYPTION_PARAMETER, and OPERATION_RATE_EXCEED_LIMITATION. For error code descriptions and solutions, see Error Codes.

• Presence

  This release optimizes the handling logic for expired user status data during reconnection, and improves the performance of setting the presence event notification in JoinChannelOptions.

• Others

  This release optimizes memory performance and fixes the potential memory leak issue.

Fixed issues

This release fixes the following issues:

• Occasional crash when calling the WhoNowAsync method to retrieve paginated results.
• Occasional packet loss of presence data in specific use-cases.
• Failure to trigger asynchronous callbacks after method calls in specific use-cases.
• Crash caused by invalid parameters when using client-side encryption.
• Occasional inability to log in to or log out of the Signaling system when the network status changed.
• When the network was disconnected, users occasionally did not receive the SNAPSHOT event notification due to that the app did not clear data.
• When a user joined a channel and switched the app to the background and then back to the foreground, the SDK occasionally triggered the REMOTE_JOIN event notification multiple times.