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 2.2.0, the Signaling SDK and Video SDK (version 4.3.0 or later) both include dynamic library files. If you are using both SDKs, manually delete the dynamic library files of the older version to avoid conflicts.

• Signaling SDK v2.2.2 dynamic library version: 1.0.11.
• Signaling SDK v2.2.1 dynamic library version: 1.0.11.
• Signaling SDK v2.2.0 dynamic library version: 1.0.0.17.

v2.2.2 was released on December 13, 2024.

1. SNAPSHOT state trigger timing change

   This release changes the trigger timing of the SNAPSHOT state in the Presence event. Now, as long as the user is in the channel, the SNAPSHOT event may be received again; after receiving it, the user can update their full information to avoid state synchronization issues caused by exceptions.

2. Lock timeout calculation rule change

   This release changes the calculation rule for 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 RTM_LINK_STATE_CHANGE_REASON enumeration class to the SDK connection state LinkStateEvent to report the reason for the connection state change.

This release improves the business 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 offline user.
• 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 certain 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.

1. Initialization

   This release removes the initialize method and adds the initialization parameter to the createAgoraRtmClient method as a replacement. Refer to the sample code below to modify your implementation:

   // Before v2.2.1
   

   // Create a Signaling instance
   

   IRtmClient* rtmClient = createAgoraRtmClient();
   

   
   

   RtmConfig config;
   

   config.appId = "your_appid";
   

   config.userId = "your_name";
   

   config.eventHandler = new RtmEventHandler();
   

   // Initialize the Signaling instance
   

   int ret = rtmClient->initialize(config);
   

   if (ret != RTM_ERROR_OK) {
   

   // Handle initialization error
   

   }
   
   // v2.2.1 or later
   

   RtmConfig config;
   

   config.appId = "your_appid";
   

   config.userId = "your_name";
   

   config.eventHandler = new RtmEventHandler();
   

   int errorCode = 0;
   

   // Create and initialize the Signaling instance
   

   rtmClient = createAgoraRtmClient(config, errorCode);
   

   if (!rtmClient || errorCode != 0) {
   

   std::cout << RED <<"error creating rtm service!" << std::endl;
   

   exit(0);
   

   }
   

2. API return values

   This release adds the return values of all methods, except for createAgoraRtmClient, and changes createStreamChannel and release from int to void. Additionally, this release adds the following asynchronous callbacks:

   • onPublishTopicMessageResult
   • onUnsubscribeTopicResult
   • onGetSubscribedUserListResult
   • onUnsubscribeResult
   • onLogoutResult
   • onRenewTokenResult
   • onUnsubscribeUserMetadataResult

3. Metadata

   This release removes the createMetadata method. Refer to the sample code below to modify your implementation:

   // Before v2.2.1
   

   IMetadata* metadata = rtmClient->getStorage()->createMetadata();
   
   // v2.2.1 or later
   

   Metadata data;
   

4. Enumerator changes

   This release adds RTM_CONNECTION_CHANGED_CERTIFICATION_VERIFY_FAILURE(22) in RTM_CONNECTION_CHANGE_REASON. The values of the RTM_CONNECTION_CHANGED_STREAM_CHANNEL_NOT_AVAILABLE and RTM_CONNECTION_CHANGED_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 RTM_CHANNEL_TYPE_USER type in RTM_CHANNEL_TYPE 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 the quiet mode when subscribing to 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. RTM_PRESENCE_EVENT_TYPE_REMOTE_STATE_CHANGED event notification logic

   This release changes the triggering logic of the RTM_PRESENCE_EVENT_TYPE_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. Others

   This release also includes the following improvements:

   • Enhances the underlying algorithm capability to improve data synchronization speed.

   • Adds the requestId parameter to the following methods:

     • login
     • logout
     • renewToken
     • unsubscribe

   • Adds the errorCode parameter to the createStreamChannel method.

This release fixed the issue that remote users occasionally did not receive the RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL 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 RTM_PRESENCE_EVENT_TYPE_SNAPSHOT type of onPresenceEvent event notification within 5 seconds, the SDK will report the RTM_ERROR_CHANNEL_PRESENCE_NOT_READY error code in the onJoinResult callback.

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, a remote user occasionally did not receive the RTM_PRESENCE_EVENT_TYPE_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 is the first release of the Signaling SDK for C++ 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: 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.1.9 provides the following core functional modules:

1. Initial configuration

   • 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 geofencing 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, onStorageEvent , onLockEvent, onConnectionStateChange, and onTokenPrivilegeWillExpire.
   • login: Log into the RTM service.
   • logout: Log out of the RTM 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 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.

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

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

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

   caution

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

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

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

   • 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 revision property through the setMajorRevision method in the Metadata data type.
     • Enable version number verification for a single metadata item by setting the revision property in the MetadataItem class.

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

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

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

This release optimizes the handling logic for expired user status data during reconnection.