Release notes

The Agora Signaling SDK provides a streamlined and stable messaging mechanism for you to quickly implement real-time messaging for various use-cases. See product overview for more information.

This page contains information on the following releases:

Starting from v2.2.0, the Signaling SDK and Video SDK (version 4.3.0 or later) both include the libaosl.so library. If you use both SDKs, take the following steps to avoid conflicts:

• If you manually integrate the SDK through CDN, manually delete the older version of the libaosl.so library;
• If you integrate the SDK using a dependency management tool, such as Maven or CocoaPods, ensure that the newer version of the libaosl.so library is included in your project.

For more information, see How do I handle issues when integrating the Signaling SDK and Video SDK simultaneously?

• Signaling SDK v2.2.4 libaosl.so version: 1.2.13.
• Signaling SDK v2.2.2 libaosl.so version: 1.0.11.
• Signaling SDK v2.2.1 libaosl.so version: 1.0.11.
• Signaling SDK v2.2.0 libaosl.so version: 1.0.0.17.

v2.2.4 was released on April 10, 2025.

• New link state change reason

  This release adds the reason LOGIN_TOO_FREQUENT (37) to RtmLinkStateChangeReason, indicating that the current login operation is too frequent.

• New renew token timeout error code

  To better reflect the result of the renew token operation, this release adds the error code RENEW_TOKEN_TIMEOUT (10026).

• Presence event notification optimization

  When channel data fails to sync properly, the SDK retriggers the SNAPSHOT event. Upon receiving this event, you can update the app's local cache.

• Other improvements

  • Improved reconnection speed of the Signaling service when switching to background or sleep mode.
  • Optimized SDK performance in weak network conditions.
  • Improved selection of access nodes to enhance connection speed.
  • Further optimized the response time of the login service.

• The subscription service occasionally did not recover during reconnection.
• Query results for users in some channels included information about abnormally offline users.
• Uncaught exceptions in callback functions could cause the SDK to crash.
• Subscribing to a topic could sometimes return an error indicating that the user was not in the channel.

v2.2.2 was released on December 13, 2024.

1. SNAPSHOT state trigger timing changes

   This release modifies the trigger timing of the SNAPSHOT event in the Presence event. Now, as long as the user is in the channel, they may receive the SNAPSHOT event again; after receiving it, the user can update their full information to avoid state inconsistencies caused by exceptions.

2. Lock timeout calculation rule changes

   This release modifies the calculation rule of the lock (Lock) timeout. Starting from this version, the lock timeout is calculated from the time when the server determines that the user is offline.

1. SDK connection state change reason

   This release adds the RtmLinkStateChangeReason enumeration class to the SDK connection state LinkStateEvent to report the reason for the connection state change.

2. Support 16 KB page size

   Starting from Android 15, the system supports a 16 KB page size. For more information, see Support 16 KB page size. Starting from this version, the SDK supports a 16 KB page size to ensure seamless operation on devices using 4 KB and 16 KB page sizes, improving compatibility and avoiding crashes.

This release improves the performance of the basic messaging service during exceptions, avoiding service unavailability caused by the failure of some services.

This release fixed the following issues:

• In some use-cases, incorrect token types cause exceptions.
• In some use-cases, users may receive repeated offline notifications from the same user who has gone offline.
• After logging in from different devices with the same UID, the connection state may be abnormal.
• When setting the Presence state frequently, data may be abnormal.
• When the specified service is not activated, joining a channel does not return an error.
• In some use-cases, abnormal property values may cause crashes.

v2.2.1 was released on August 9, 2024.

This release optimizes the implementation of the following features, which involves renaming, deleting, or modifying the behavior of some APIs. To ensure the proper functioning of your project, modify your implementation after upgrading the SDK.

• Removes the createMetadata method. Refer to the sample code below to modify your implementation:

  
  

  _2

  // Before v2.2.1

  _2

  Metadata metadata = rtmClient.getStorage().createMetadata();

  
  
  
  

  _2

  // v2.2.1 or later

  _2

  Metadata metadata = new Metadata();

  
  

• Removes the StateItem class, and changes the type of the following parameters from ArrayList<StateItem> to HashMap<String, String>:

  • The items parameter of the setState method.
  • The stateItems parameter of the PresenceEvent class.
  • The states parameter of the UserState class.

• Adds CERTIFICATION_VERIFY_FAILURE(22) in RtmConnectionChangeReason. The values of STREAM_CHANNEL_NOT_AVAILABLE and INCONSISTENT_APPID change to 23 and 24, respectively.

1. Private deployment capability

   This release adds the privateConfig parameter in RtmConfig to set private deployment. See Private deployment configuration.

2. Heartbeat interval configuration

   This release adds the heartbeatInterval parameter in RtmConfig to set the interval at which the SDK sends heartbeat packets to the server. See Heartbeat interval and presence timeout parameters.

3. Dual environment configuration

   This release adds the protocolType parameter in RtmConfig to set the network transport protocol. See Connection protocol.

4. User channel

   This release adds the USER type in RtmChannelType for sending messages to specific users. This feature can replace the peer-to-peer messaging feature in v1.

5. Quiet mode configuration

   This release adds the beQuiet property in SubscribeOptions and JoinChannelOptions to enable quiet mode when subscribing or joining a channel. Once you enable the quiet mode, other users in the channel cannot receive your presence event notifications.

1. Connection state management

   This release deprecates the onConnectionStateChanged callback and adds the onLinkStateEvent callback instead. See Connection management for details.

2. REMOTE_STATE_CHANGED event notification logic

   This release changes the triggering logic of the REMOTE_STATE_CHANGED event. When a user sets or modifies multiple key-value pairs at once, other users in the channel receive only one event notification.

3. Support for event notification timestamps

   This release adds a new timestamp parameter in the following data structures to report the timestamp of the triggered event notification:

   • MessageEvent
   • PresenceEvent
   • TopicEvent
   • StorageEvent
   • LockEvent

4. Optimized API behavior

   This release improves the behavior of the following APIs:

   • login
     • Before v2.2.1: The SDK does not support multiple consecutive calls to this method, or passing an empty string in the token parameter.
     • v2.2.1 or later: The SDK supports multiple consecutive calls to this method without the need for additional calls to logout in between. Additionally, when the token parameter is an empty string, the SDK uses the app ID you provided during initialization as a replacement for the token.
   • subscribe
     • Before v2.2.1: The SDK does not support multiple consecutive calls to this method.
     • v2.2.1 or later: The SDK supports multiple consecutive calls to this method.
   • join
     • Before v2.2.1: The SDK does not support multiple consecutive calls to this method, or passing an empty string in the token parameter.
     • v2.2.1 or later: The SDK supports multiple consecutive calls to this method. Additionally, when the token parameter is an empty string, the SDK uses the app ID you provided during initialization as a replacement for the token.

5. Range of presenceTimeout

   This release changes the range of the presenceTimeout parameter in the RtmConfig from [10, 300] to [5, 300].

6. Other improvements

   This release also enhances the underlying algorithm capability to improve the data synchronization speed.

This release fixed the issue that remote users occasionally did not receive the REMOTE_LEAVE event notification when the local user directly called the logout method without calling the leave method.

v2.1.12 was released on July 2, 2024.

This release includes the following improvements:

• For data synchronization errors caused by network issues, this release introduces a user logout mechanism, which ensures that the SDK automatically logs out of the Signaling system.
• Unsubscribing from a message channel during network disconnection will no longer return an error.

This release fixed the following issues:

• During a disconnection with the Signaling system under poor network conditions, the user experienced errors when unsubscribing from a message channel.
• Under poor network conditions, the user occasionally failed to receive callbacks after a successful login.
• After reconnecting from a disconnection, the user occasionally could not receive the onStorageEvent event notification.
• After reconnecting from a disconnection, the SDK occasionally failed to restore subscription relationships in the stream channel.
• Occasional failure to receive topic messages from web clients.

v2.1.11 was released on May 13, 2024.

This release optimizes the response mechanism when subscribing to or joining channels with the withPresence=true setting. If the user does not receive the SNAPSHOT type of onPresenceEvent event notification within 5 seconds, the SDK will report the CHANNEL_PRESENCE_NOT_READY error code in the resultCallback parameter.

This release fixed the following issues:

• In specific use-cases, after logging out of the Signaling system and logging back in, occasional failures occurred when subscribing to or joining channels with the withPresence=true setting.
• In cases where the connection was lost due to network issues and then restored, if the local user actively called the leave method to leave the channel, the remote user occasionally did not receive the REMOTE_TIMEOUT type of the onPresenceEvent event notification.
• Occasional failures occurred when frequently calling the subscribe and unsubscribe methods.

v2.1.10 was released on March 11, 2024.

This release fixed the following issues:

• When sending messages frequently, message sending occasionally timed out.
• After calling renewToken to renew the token, some services were not functioning correctly, resulting in unexpected disconnection.

v2.1.9 was released on February 22, 2024.

This release improves message publishing options as follows:

• Removes the sendTs parameter and adds the channelType parameter in PublishOptions. See details in PublishOptions.
• Modifies the type of the options parameter in the publishTopicMessage method from PublishOptions to TopicMessageOptions. See details in TopicMessageOptions.

Make sure to modify the implementation of the relevant features after upgrading the SDK.

This release adds the following improvements:

• Adds error codes: INVALID_CHANNEL_TYPE, RTM_ERROR_INVALID_ENCRYPTION_PARAMETER, and RTM_ERROR_OPERATION_RATE_EXCEED_LIMITATION. For error code descriptions and solutions, see Error Codes.
• Optimizes the handling logic for expired user status data during reconnection.

This release fixed the occasional crash issue when calling the getOnlineUsers method to retrieve paginated results.

v2.1.7 was released on January 22, 2024.

1. Stream Channel

   Experience seamless, delay-free data flow from one point to another. Stream channel solution refers to a real-time data pipeline that enables the uninterrupted flow of data from one point to another without delay or latency.

2. Pub/Sub

   Embrace asynchronous messaging, enabling instant communication between publishers and subscribers without the need for immediate responses. The pub/sub model is a messaging pattern used in real-time messaging solutions where publishers send messages to channels, and subscribers receive messages from the channels they are subscribed to.

3. Topic

   Effectively manage data streams with topics, enabling seamless communications between users. Topic serves as a data flow management mechanism in the stream channel. It enables users to subscribe to, distribute, and notify events of data streams. Topics allow users to register as message publishers, send messages, and receive messages from subscribed publishers in a channel.

4. Storage

   Storage is important in signaling solutions to ensure reliable message delivery and prevent message loss or drop.

5. Removing Event Listeners

   This release adds the removeEventListener method. You can use it to remove a specified event listener.

6. Interval Mode

   This release supports the interval mode of presence function. When the number of online users in a channel exceeds the specified Announce Max value, the channel enters the interval mode. The SDK triggers the presence event notification at regular intervals and provides aggregated incremental information about user join, leave, timeout, and state changes in the interval property. For more details, see Interval Mode.

7. Locks

   Implement locks to maintain the sequence of messages, ensuring your data is processed in a specific order, preventing any data conflicts. When a client accesses a resource, it can acquire a lock on that resource to prevent other clients from accessing it.

Released on July 9, 2025.

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

• Functional coverage: v2.x covers more business scenarios 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: v2.x redesigns and simplifies the API interface. We have additionally 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.

v2.2.4 provides the following core functional modules:

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.
• initialize: 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.
  • context：
    • For Android, it is the context of Android Activity.
    • For Windows, it is the window handle of the app. Once set, this parameter enables you to connect or disconnect the video devices while they are powered.
  • useStringUserId: Set the data type of the user ID, which can be of type string or type uint.
  • eventHandler: Set event listeners.
  • 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, onLockEvent, onStorageEvent, onConnectionStateChanged, and onTokenPrivilegeWillExpire.
• login: Log into the Signaling service.
• logout: Log out of the Signaling service.
• release: Destroy the Signaling client.

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 within 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.

When you call 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 RTM_PRESENCE_EVENT_TYPE_REMOTE_JOIN_CHANNEL and RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL 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.

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 byte 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.

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.
• getSubscribedUserList: Get the list of subscribed publishers in a specific topic.

The joinTopic and leaveTopic operations trigger onTopicEvent event notifications that are broadcast to other users in the channel.

caution

Topics exist only in stream channels, not in message channels.

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.

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. After calling the createMetadata method to create an RtmMetadata, you can perform operations on channel metadata and user metadata based on your specific needs.

• 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.

• 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.

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 scenario:

• Enable version number verification for the entire set of channel metadata by setting the majorRevision property in the RtmMetadata 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 uint64 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.

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.