diff --git a/assets/images/signaling/authentication-workflow.puml b/assets/images/signaling/authentication-workflow.puml index 8e903dedb..b265c4769 100644 --- a/assets/images/signaling/authentication-workflow.puml +++ b/assets/images/signaling/authentication-workflow.puml @@ -35,10 +35,10 @@ end group Renew token API -> APP: Trigger event: token privilege will expire -APP -> TS: Request an RTM token using:\n App Id, user ID -TS -> TS: Validate request against internal security\n and generate token -TS -> APP: Return RTM token to App -API <- APP: Send RTM token to Signaling with a \ncall to renew token +APP -> TS: Request a token using:\n App Id, user ID +TS -> TS: Validate against internal security\n and generate token +TS -> APP: Return token to App +API -> APP: Send token to Signaling with a \ncall to renew token API -> API: Validate the token API -> APP: Trigger callback end diff --git a/assets/images/signaling/authentication-workflow.svg b/assets/images/signaling/authentication-workflow.svg index 061e13e4a..e9ac1f550 100644 --- a/assets/images/signaling/authentication-workflow.svg +++ b/assets/images/signaling/authentication-workflow.svg @@ -1 +1 @@ -Implemented by youAgoraToken serverToken serverYour appYour appSignalingSignalingLog in to Signaling using authenticationRequest an RTM token using:App Id, user IdValidate request against internal securityand generate tokenReturn RTM token to AppInitiate the Signaling Engine usingApp Id, user Id and the RTM tokenLog in to SignalingValidate the tokenLog in user, then trigger callbackJoin a stream channelRequest an RTC token using:App Id, user Id, and stream channel nameValidate request against internal securityand generate tokenReturn RTC token to AppJoin a stream channel usingchannel name, user Id, and the RTC tokenRenew tokenTrigger event: token privilege will expireRequest an RTM token using:App Id, user IDValidate request against internal securityand generate tokenReturn RTM token to AppSend RTM token to Signaling with acall to renew tokenValidate the tokenTrigger callback \ No newline at end of file +Implemented by youAgoraToken ServerToken ServerYour appYour appSignalingSignalingInitiate the Signaling EngineJoin channel using authenticationRequest a token using:App Id, user IDValidate against internal securityand generate tokenReturn token to AppLog in to Signaling usingUID and token.Validate the tokenLog in user, then trigger callbackRenew tokenTrigger event: token privilege will expireRequest a token using:App Id, user IDValidate against internal securityand generate tokenReturn token to AppSend token to Signaling with acall to renew tokenValidate the tokenTrigger callback diff --git a/assets/images/signaling/get-started-workflow.puml b/assets/images/signaling/get-started-workflow.puml index cee346bb7..d43e121dd 100644 --- a/assets/images/signaling/get-started-workflow.puml +++ b/assets/images/signaling/get-started-workflow.puml @@ -15,17 +15,17 @@ end box group Initialize USR -> APP: Open app APP -> APP: Create a signalingEngine instance -APP -> APP: Add event callbacks +APP -> APP: Add user event callbacks APP -> APP: Set the authentication token APP -> API: Log in to Signaling end group Messages -USR -> APP: Publish message -APP -> API: signalingEngine.publish -APP -> APP: Listen for message events -API -> APP: message +USR -> APP: Send message +APP -> API: sendMessageToPeer +APP -> APP: listen for message events +API -> APP: MessageFromPeer APP -> USR: Receive message end diff --git a/assets/images/signaling/get-started-workflow.svg b/assets/images/signaling/get-started-workflow.svg index c676a605f..f802d5244 100644 --- a/assets/images/signaling/get-started-workflow.svg +++ b/assets/images/signaling/get-started-workflow.svg @@ -1 +1 @@ -Your appAgoraUserUserSignaling SDKSignaling SDKSignalingSignalingInitializeOpen appCreate a signalingEngine instanceAdd event callbacksSet the authentication tokenLog in to SignalingMessagesPublish messagesignalingEngine.publishListen for message eventsmessageReceive messagePresenceChange statuslisten for user eventsConnectionStateChangedInform usersCloseLog outLog out of Signaling \ No newline at end of file +Your appAgoraUserUserSignaling SDKSignaling SDKSignalingSignalingInitializeOpen appCreate a signalingEngine instanceAdd user event callbacksSet the authentication tokenLog in to SignalingMessagesSend messagesendMessageToPeerlisten for message eventsMessageFromPeerReceive messageUsersChange statuslisten for user eventsConnectionStateChangedInform usersCloseLog outLog out of Signaling \ No newline at end of file diff --git a/shared/common/_core-concepts.mdx b/shared/common/_core-concepts.mdx index b2fbddfea..dfb756f46 100644 --- a/shared/common/_core-concepts.mdx +++ b/shared/common/_core-concepts.mdx @@ -36,17 +36,25 @@ The App ID is a random string generated within [](https://cons uses this App ID to identify each app, provide billing and other statistical data services. - - + + + + + + For applications requiring high security in a production environment, you must choose a App ID + Token mechanism for [user authentication](../develop/authentication-workflow) when creating a new project. Without an authentication token, your environment is open to anyone with access to your App ID. + + + + + For applications requiring high security in a production environment, you must choose a App ID + Token mechanism for user authentication when creating a new project. Without an authentication token, your environment is open to anyone with access to your App ID. - + For applications requiring high security in a production environment, you must choose a App ID + Token mechanism for [user authentication](../get-started/authentication-workflow) when creating a new project. Without an authentication token, your environment is open to anyone with access to your App ID. @@ -54,24 +62,36 @@ For applications requiring high security in a production environment, you must c An App certificate is a string generated by to enable token authentication. It is required for generating an or authentication token. To get your app certificate from , see [Manage app certificates](../reference/manage-agora-account#get-the-app-certificate). - + + + + + + To use your App certificate for setting up a token server, see [Create and run a token server.](../develop/authentication-workflow#create-and-run-a-token-server) + + + + + - + To use your App certificate for setting up a token server, see [Create and run a token server.](../get-started/authentication-workflow#create-and-run-a-token-server) + + ## Channel - uses the *channel name* to identify a channel. Users who specify the same *channel name* join a common channel and interact with each other. A channel is created when the first user joins. It ceases to exist when the last user leaves. You create a channel by calling the methods for transmitting real-time data. uses different channels to transmit different types of data. The channel transmits audio or video data, while the channel transmits messaging or signaling data. The and channels are independent of each other. Additional components provided by , such as On-Premise Recording and Cloud Recording, join the channel and provide real-time recording, transmission acceleration, media playback, and content moderation. + + ## Channel profile The SDK applies different optimization methods according to the selected channel profile. supports the following channel profiles: @@ -83,25 +103,11 @@ The SDK applies different optimization methods according to the selected channel - - -A data transfer management mechanism for passing data from one device to another. Any user who subscribes to or joins a channel can receive messages or events transmitted in that channel. Clients can subscribe to or join multiple channels at the same time. - - includes the following types of channels: - -| Channel type | Main features | Applicable scenario| -|---------------|---------------|--------------------| -| Message | Follows the industry-standard pub/sub model. Channels do not need to be created in advance, and there is no upper limit on the number of publishers and subscribers in a channel.|Multi-device management and command exchange in the IoT industry, location tracking in smart devices, etc.| -| Stream |Follows the chat room model. Users need to join the channel to send and receive event notifications. Messages are managed and delivered through topics, and a single channel allows up to 1000 users to join at the same time. Supports channel sharing and synchronous transmission of audio and video data.|High-frequency and large concurrent data transmission or co-channel and synchronous transmission with audio and video data, such as metaverse, cloud games, etc.| - - - ## Device A physical or virtual device that connects to . For example, a mobile device, computer, smart watch, or IoT device. - ## Stream A stream is a sequence of digitally-encoded coherent signals that contains audio or video data. Users in a channel [publish](#publish) local streams and [subscribe](#subscribe) to remote streams from other users. @@ -116,19 +122,25 @@ After successfully publishing a stream, the SDK continues sending media data to Subscribing is the act of receiving media streams published by remote users to the channel. A user receives audio and video data from other users by subscribing to one or more of their streams. You either directly play the subscribed streams or process incoming data for other purposes such as recording or capturing screenshots. For further details, on how to create, manage and update your account, see [Manage your account](../reference/manage-agora-account). - ## Token A token is a dynamic key that is used by the authentication server to check user permissions. You use to generate a temporary token for testing purposes during the development process. In a production environment, you implement a token server in your security infrastructure to control access to your channels. - - - -For more information, see [Secure authentication with tokens](../get-started/authentication-workflow). + + + + + + +For more information, see [Secure authentication with tokens](../develop/authentication-workflow). + + + + + - + For more information, see [Secure authentication with tokens](../get-started/authentication-workflow). diff --git a/shared/common/_supported-platforms.mdx b/shared/common/_supported-platforms.mdx index ce098d589..da6691606 100644 --- a/shared/common/_supported-platforms.mdx +++ b/shared/common/_supported-platforms.mdx @@ -2,7 +2,6 @@ import * as data from '@site/data/variables'; This section lists the platforms and products you use to develop apps that interact with . - - *Android*: @@ -23,7 +22,6 @@ This section lists the platforms and products you use to develop apps that inter |Windows|
  • Chrome
  • Firefox
  • Edge
|Supported |Supported| |ChromeOS |Chrome |Supported |Supported| - To ensure the best user experience, best practice is to use the latest version each browser on the latest version of the operating system. Download the latest version of: - [Chrome](https://www.google.com/intl/en/chrome/) @@ -31,6 +29,7 @@ To ensure the best user experience, best practice is to use the latest version e - [Edge](https://microsoft.com/edge) - [Safari](https://support.apple.com/en-hk/HT201541) + @@ -178,74 +177,3 @@ To ensure the best user experience, best practice is to use the latest version e - [Edge](https://microsoft.com/edge) - [Safari](https://support.apple.com/en-hk/HT201541) - - - -### Supported browsers - - - supports the following browsers: - -- *Android* - | Browser or application | Minimum supported version | - |----------------------------------|---------------------------| - | Chrome | 86.0.4240 | - | Firefox (x64, ARM64, IA-32, ARMv7| 83.0 | - -- *iOS*: - | Browser or application | Minimum supported version | - |------------------------|---------------------------| - | Chrome | 86.0.4240 | - | Firefox | 29.0 | - -- *Desktop*: - |Operating system |Browser |Minimum supported version | - |-----------------|--------------|--------------------------| - |Windows |Firefox |83.0 | - |Windows |Chrome |86.0.4240 | - |Windows |Microsoft Edge|87.0.664.60 | - |macOS |Chrome |86.0.4240 | - |macOS |Firefox |83.0 | - |macOS |Safari |13.0 | - |Linux |Firefox |83.0 | - |Linux |Chrome |86.0.4240 | - |OpenBSD |Firefox |83.0 | - -### Dependencies - -When you integrate features into your , has the following - dependencies: - -| Name | Minimum version | License | Dependency | -|---|---|---|---| -| @thi.ng/cache | 1.0.70 | Apache 2.0 | Transitive | -| @types/format-util | 1.0.1 | MIT | Transitive | -| @types/google-closure-compiler | 0.0.18 | MIT | Transitive | -| @types/node-forge | 1.3.1 | BSD 2-Clause | Transitive | -| abortcontroller-polyfill | 1.7.1 | MIT | Transitive | -| console-polyfill | 0.3.0 | MIT | Transitive | -| core-js | 3.9.0 | MIT | Transitive | -| debug | 4.3.4 | MIT | Transitive | -| dotenv | 8.2.0 | BSD 2-Clause | Transitive | -| events | 3.2.0 | MIT | Transitive | -| format-util | 1.0.5 | MIT | Transitive | -| gud | 1.0.0 | MIT | Transitive | -| is-mobile | 3.1.1 | MIT | Transitive | -| is-what | 3.14.1 | MIT | Transitive | -| lodash | 4.17.21 | MIT | Transitive | -| long | 4.0.0 | Apache 2.0 | Transitive | -| lru-cache | 6.0.0 | ISC | Transitive | -| never throw | 5.0.1 | MIT | Transitive | -| node-forge | 1.3.1 | BSD 3-Clause or GPL 2 | Transitive | -| promise-polyfill | 8.2.0 | MIT | Transitive | -| protobufjs | 6.10.2 | MIT | Transitive | -| regenerator-runtime | 0.13.9 | MIT | Transitive | -| rxjs | 6.6.3 | Apache 2.0 | Transitive | -| rxjs-etc | 10.6.0 | MIT | Transitive | -| rxjs-websockets | 8.0.1 | ISC | Transitive | -| safe-json-stringify | 1.2.0 | MIT | Transitive | -| tslib | 2.1.0 | BSD Zero Clause | Transitive | -| uuid | 3.4.0 | MIT | Transitive | -| webcrypto-shim | 0.1.6 | MIT | Transitive | - - \ No newline at end of file diff --git a/shared/common/manage-agora-account/_get-appid-token.mdx b/shared/common/manage-agora-account/_get-appid-token.mdx index 252a3a1de..7c1d8b57e 100644 --- a/shared/common/manage-agora-account/_get-appid-token.mdx +++ b/shared/common/manage-agora-account/_get-appid-token.mdx @@ -57,31 +57,28 @@ To generate a set of Customer ID and Customer Secret, do the following: #### Generate a temporary token -To ensure communication security, best practice is to use tokens to authenticate the users who log in to - from your . +When a user attempts to join a channel, your app passes an encrypted authentication token to , this token is unique for each channel. It is generated using the App ID of your project and the channel name. In a test or production environment, your app retrieves the token from a token server. However, for local testing, you can generate a temporary token in . -To generate a temporary token: +1. In , open [Project Management](https://console.agora.io/projects), select your project and click **Config**. -1. In [ > Project Management](https://console.agora.io/projects), select your project and click -**Configure**. +2. Under **Features**, click **Generate temp token**. -1. In your browser, navigate to the [ token builder](https://agora-token-generator-demo.vercel.app/). +3. Type the **Channel Name**, then click **Generate**. -1. Choose the product your user wants to log in to. Fill in *App ID* and *App Certificate* with the -details of your project in . + generates a token valid to join **Channel Name** only. -1. Customize the token for each user. The required fields are visible in token builder. +4. Click **Copy**. - - In , each authentication token you create is specific for a user ID in your . You create -a token for each user in the channel. When you call `login` using , ensure that the UID is the same -as you used to create the token. + **Temp Token** is added to the clipboard of your development machine. - +#### Generate an token -1. Click **Generate Token** +Applicable products of tokens include and Flexible Classroom. - The token appears in Token Builder. +To ensure communication security, Agora recommends using tokens to authenticate users logging in to an system. -1. Add the token to your . +For testing purposes, Agora Console supports generating tokens. To generate an token: +1. Visit [token builder](https://webdemo.agora.io/token-builder). + +2. Fill in the App ID, App certificate, and user ID to log in to the system. You need to specify the user ID yourself (for example, "test"). The generated token is showed on the screen. When calling the `login` method later, ensure that the user ID is the same with the one that you use to generate the token. diff --git a/shared/common/project-setup/web.mdx b/shared/common/project-setup/web.mdx index b06a3effb..3c23a8465 100644 --- a/shared/common/project-setup/web.mdx +++ b/shared/common/project-setup/web.mdx @@ -1,23 +1,20 @@ -1. **Clone the repository**: + +1. Clone the [ sample code repository](https://github.com/AgoraIO/signaling-sdk-samples-web) to + `` in your development environment: - To clone the repository to your local machine, open Terminal and navigate to the directory where you want to clone the repository. Then, use the following command: - - ```bash git clone https://github.com/AgoraIO/signaling-sdk-samples-web ``` - - -1. **Install the dependencies**: - Navigate to the root directory of the cloned repository and run the following command: +1. Install the dependencies. Open Terminal in the root directory of the cloned repository and run the following command: ```bash - pnpm install + npm install ``` - By default is installed automatically. However, you can also [Install manually](../reference/downloads#through-the-agora-website). - + + + \ No newline at end of file diff --git a/shared/common/project-test/android.mdx b/shared/common/project-test/android.mdx deleted file mode 100644 index 1015503a3..000000000 --- a/shared/common/project-test/android.mdx +++ /dev/null @@ -1,28 +0,0 @@ - -3. **Set the APP ID** - - In `agora-manager/res/raw/config.json`, set `appId` to the [AppID](../reference/manage-agora-account?platform=android#get-the-app-id) of your project. - -1. **Set the authentication method** - - Choose one of the following authentication methods: - - - **Temporary token**: - 1. Set `rtcToken` with the value of your [temporary token](../reference/manage-agora-account#generate-a-temporary-token). - 1. Set `channelName` - with the name of a channel you used to create the token. - - **Authentication server**: - 1. Setup an [Authentication server](../get-started/authentication-workflow?platform#create-and-run-a-token-server) - 1. In `config.json`, set: - - `channelName` with the name of a channel you want to join. - - `rtcToken` to an empty string. - - `serverUrl` to the base URL of your authentication server. For example, `https://agora-token-service-production-1234.up.railway.app`. - -1. **Start the reference app** - - 1. In Android Studio, connect a physical Android device to your development machine. - - 1. Click **Run** to start the app. - - A moment later you see the project installed on your device. If this is the first time you run the project, you need to grant microphone and camera access to your . - - diff --git a/shared/common/project-test/electron.mdx b/shared/common/project-test/electron.mdx deleted file mode 100644 index 23cb0aff0..000000000 --- a/shared/common/project-test/electron.mdx +++ /dev/null @@ -1,22 +0,0 @@ - - - 1. Take the following steps to setup a new Electron project: - - 1. Open a terminal window and navigate to the directory where you want to create the project. - - 2. Execute the following command in the terminal: - - ``` bash - git clone https://github.com/electron/electron-quick-start - ``` - This command clones the Electron quick-start project that you use to implement . - - 2. Install the - - Open a terminal window in your project folder and execute the following command to download and install the . - - ``` bash - npm i agora-electron-sdk - ``` - Make sure the path to your project folder does not contain any spaces. This might cause error during the installation. - diff --git a/shared/common/project-test/flutter.mdx b/shared/common/project-test/flutter.mdx deleted file mode 100644 index 75bf41d81..000000000 --- a/shared/common/project-test/flutter.mdx +++ /dev/null @@ -1,28 +0,0 @@ - - -3. **Set the APP ID** - In `flutter-reference-app/assets/config/config.json`, set `appId` to the [AppID](../reference/manage-agora-account?platform=android#get-the-app-id) of your project. - -1. **Set the authentication method** - - Choose one of the following authentication methods: - - - **Temporary token**: - 1. Set `rtcToken` with the value of your [temporary token](../reference/manage-agora-account#generate-a-temporary-token). - 1. Set `channelName` - with the name of a channel you used to create the token. - - **Authentication server**: - 1. Setup an [Authentication server](../get-started/authentication-workflow?platform#create-and-run-a-token-server) - 1. In `config.json`, set: - - `channelName` with the name of a channel you want to join. - - `rtcToken` to an empty string. - - `serverUrl` to the base URL of your authentication server. For example, `https://agora-token-service-production-1234.up.railway.app`. - -1. **Start the reference app** - - 1. Connect a physical mobile device to your development machine. - - 1. In your IDE, click **Run** to start the app. - - A moment later you see the project installed on your device. If this is the first time you run the project, you need to grant microphone and camera access to your . - - diff --git a/shared/common/project-test/index.mdx b/shared/common/project-test/index.mdx deleted file mode 100644 index 2d8fac272..000000000 --- a/shared/common/project-test/index.mdx +++ /dev/null @@ -1,21 +0,0 @@ -import Android from './android.mdx'; -import Ios from './ios.mdx'; -import MacOS from './macos.mdx'; -import Web from './web.mdx'; -import ReactNative from './react-native.mdx'; -import ReactJS from './react-js.mdx'; -import Electron from './electron.mdx'; -import Flutter from './flutter.mdx'; -import Unity from './unity.mdx'; -import Windows from './windows.mdx'; - - - - - - - - - - - diff --git a/shared/common/project-test/ios.mdx b/shared/common/project-test/ios.mdx deleted file mode 100644 index f21f0f8b6..000000000 --- a/shared/common/project-test/ios.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import Source from './swift.mdx'; - - - - - - diff --git a/shared/common/project-test/macos.mdx b/shared/common/project-test/macos.mdx deleted file mode 100644 index 74e608cdd..000000000 --- a/shared/common/project-test/macos.mdx +++ /dev/null @@ -1,8 +0,0 @@ -import Source from './swift.mdx'; - - - - - - - \ No newline at end of file diff --git a/shared/common/project-test/react-native.mdx b/shared/common/project-test/react-native.mdx deleted file mode 100644 index e45dcb562..000000000 --- a/shared/common/project-test/react-native.mdx +++ /dev/null @@ -1,61 +0,0 @@ - - -1. **Setup a React Native environment for project** - - In the terminal, run the following command: - - ```bash - npx react-native init ProjectName --template react-native-template-typescript - ``` - - npx creates a new boilerplate project in the `ProjectName` folder. - - For Android projects, enable the project to use Android SDK. In the `android` folder of your project, set the `sdk.dir` in the `local.properties` file. For example: - - - ```bash - sdk.dir=C:\\PATH\\TO\\ANDROID\\SDK - ``` - -1. **Test the setup** - - Launch your Android or iOS simulator and run your project by executing the following command: - - 1. Run `npx react-native start` in the root of your project to start Metro. - 1. Open another terminal in the root of your project and run `npx react-native run-android` to start the Android app, or run `npx react-native run-ios` to start the iOS app. - - You see your new app running in your Android or iOS simulator. You can also run your project on a physical Android or iOS device. For detailed instructions, see [Running on device](https://reactnative.dev/docs/running-on-device). - -1. **Integrate and configure ** - - To integrate on React Native 0.60.0 or later: - 1. Navigate to the root folder of your project in the terminal and integrate with either: - - npm - - ```bash - npm i --save react-native-agora - ``` - - - yarn - - ```bash - // Install yarn. - npm install -g yarn - // Download the Agora React Native SDK using yarn. - yarn add react-native-agora - ``` - - Do not link native modules manually, React Native 0.60.0 and later support [Autolinking](https://github.com/react-native-community/cli/blob/main/docs/autolinking.md). - - 1. If your target platform is iOS, use CocoaPods to install : - - ```bash - npx pod-install - ``` - - 1. uses Swift in native modules, your project must support compiling Swift. To create `File.swift`: - - 1. In Xcode, open `ios/ProjectName.xcworkspace`. - 1. Click **File > New > File, select iOS > Swift File**, then click **Next > Create** . - - \ No newline at end of file diff --git a/shared/common/project-test/swift.mdx b/shared/common/project-test/swift.mdx deleted file mode 100644 index b5d0bb8a6..000000000 --- a/shared/common/project-test/swift.mdx +++ /dev/null @@ -1,28 +0,0 @@ - -3. **Set the APP ID** - - In `DocsAppConfig.swift` set `appId` to the [AppID](../reference/manage-agora-account?platform=android#get-the-app-id) of your project. - -1. **Set the authentication method**: - - - **Temporary token**: - 1. Set `rtcToken` with the value of your [temporary token](../reference/manage-agora-account#generate-a-temporary-token). - 1. Set `channelName` - with the name of a channel you used to create the token. - - **Authentication server**: - 1. Setup an [Authentication server](../get-started/authentication-workflow?platform#create-and-run-a-token-server) - 1. In `DocsAppConfig.swift`: - - 1. Set `rtcToken` to an empty string. - 1. Set `serverUrl` to the base URL of your authentication server. For example, `https://agora-token-service-production-1234.up.railway.app`. - -1. **Run the reference app**: - - If this is the first time you run the project, grant microphone and camera access to your . - -1. **Test ** - - In the dropdown, select this document and test . - - - - \ No newline at end of file diff --git a/shared/common/project-test/unity.mdx b/shared/common/project-test/unity.mdx deleted file mode 100644 index fdfb4e54d..000000000 --- a/shared/common/project-test/unity.mdx +++ /dev/null @@ -1,25 +0,0 @@ - - -3. **Set the APP ID** - - In `Assets/agora-manager/config.json`, set `appId` to the [AppID](../reference/manage-agora-account?platform=android#get-the-app-id) of your project. - -1. **Set the authentication method** - - Choose one of the following authentication methods: - - - **Temporary token**: - 1. Set `rtcToken` with the value of your [temporary token](../reference/manage-agora-account#generate-a-temporary-token). - 1. Set `channelName` - with the name of a channel you used to create the token. - - **Authentication server**: - 1. Setup an [Authentication server](../get-started/authentication-workflow?platform#create-and-run-a-token-server) - 1. In `config.json`, set: - - `channelName` with the name of a channel you want to join. - - `rtcToken` to an empty string. - - `serverUrl` to the base URL of your authentication server. For example, `https://agora-token-service-production-1234.up.railway.app`. - -1. **Run the reference app**: - - In Unity, click **Play**. You see the running on your device. - - \ No newline at end of file diff --git a/shared/common/project-test/web.mdx b/shared/common/project-test/web.mdx deleted file mode 100644 index bcc98dd32..000000000 --- a/shared/common/project-test/web.mdx +++ /dev/null @@ -1,36 +0,0 @@ - - - -1. **Set the AppID** - - In `src/agora_manager/config.json`, set `appId` to the [AppID](../reference/manage-agora-account#get-the-app-id) of your project. - - - In `/src/signaling_manager/config.json`, set `appId` to the [AppID](../reference/manage-agora-account#get-the-app-id) of your project. - -1. **Set the authentication method** - - Choose one of the following authentication methods: - - - **Temporary token**: - 1. Set `token` with the value of your [temporary token](../reference/manage-agora-account#generate-a-temporary-token). - 1. Set `channelName` - with the name of a channel you used to create the token. - - **Authentication server**: - 1. Setup an [Authentication server](../get-started/authentication-workflow?platform#create-and-run-a-token-server) - 1. In `config.json`, set: - - `channelName` with the name of a channel you want to join. - - `token` to an empty string. - - `serverUrl` - with the base URL for your token server. For example: `https://agora-token-service-production-yay.up.railway.app`. - -1. **Run the reference app** - - In Terminal, navigate to ``, then run the following command: - - ```bash - pnpm dev - ``` - - Use the URL displayed in the terminal to open the in your browser. - - - diff --git a/shared/common/project-test/windows.mdx b/shared/common/project-test/windows.mdx deleted file mode 100644 index 45ca55387..000000000 --- a/shared/common/project-test/windows.mdx +++ /dev/null @@ -1,59 +0,0 @@ - - - -1. **Create an MFC dialog-based application** - - 1. From the main menu, choose **File** > **New** > **Project**. - - 1. Enter **MFC** into the search box and then choose **MFC App** from the result list. - - 1. In **Project Name**, input `AgoraImplementation` and press **Create** to open the **MFC Application Wizard**. - - 1. In **MFC Application**, under **Application type** , select **Dialog based**, then click **Finish**. Your project opens in Visual Studio. - - -1. **Integrate ** - - To integrate the into your project. - - 1. Unzip the latest version of [](/sdks) in a local directory. - - 1. Copy the `sdk` directory of the downloaded SDK package to the root of your project, ``. - - 1. Create a new directory `/Debug`. - - 1. Copy the files from `` to `/Debug`. - - -1. **Configure your project properties** - - Right-click the project name In **Solution Explorer**, then click **Properties** to configure the following project properties, and click **OK**. - - 1. In **AgoraImplementation Property pages**, select **Win32** from the **Platform** dropdown list. - - If your targeted platform is `x64`, then select `x64` from the **Platform** dropdown list. - - 1. Go to the **C/C++** > **General** > **Additional Include Directories** menu, click **Edit**, and input the following string in the pop-up window: - - ``` - ;$(SolutionDir)sdk\high_level_api\include;$(ProjectDir) - ``` - - 1. Go to the **Linker** > **General** > **Additional Library Directories** menu, click **Edit**, and input the following string in the pop-up window: - - ``` - ;$(SolutionDir)sdk\x86; - ``` - The sample code uses `x86` platform. If you are using `x64`, then add the following string to the **Additional Library Directories** field: - - ``` - ;$(SolutionDir)sdk\x86_64 - ``` - - 1. Go to the **C/C++** > **Preprocessor** > **Preprocessor Definitions** menu, click **Edit**, and input the following path in the pop-up window: - - ``` - ;_CRT_SECURE_NO_WARNINGS - ``` - - \ No newline at end of file diff --git a/shared/signaling/authentication-workflow/implementation/index.mdx b/shared/signaling/authentication-workflow/implementation/index.mdx index f25927243..1a161b545 100644 --- a/shared/signaling/authentication-workflow/implementation/index.mdx +++ b/shared/signaling/authentication-workflow/implementation/index.mdx @@ -5,7 +5,9 @@ import Unity from './unity.mdx'; import Web from './web.mdx'; import Windows from './windows.mdx'; -In , each authentication token you create is specific for a user ID in your . You create a token for each user who logs in to . When you initiate the , ensure that the UID is the same one you used to create the token. +In , each authentication token you create is specific for a user ID in your . You create +a token for each user in the channel. When you call `login` using , ensure that the UID is the same +as you used to create the token. diff --git a/shared/signaling/authentication-workflow/implementation/web.mdx b/shared/signaling/authentication-workflow/implementation/web.mdx index 3d70cc0bc..fc566d9a4 100644 --- a/shared/signaling/authentication-workflow/implementation/web.mdx +++ b/shared/signaling/authentication-workflow/implementation/web.mdx @@ -15,42 +15,54 @@ To retrieve tokens from the token server and use them to authenticate your { + resolve(response.data.rtmToken); + }) + .catch((error) => { + console.log(error); + }); + }); } else { - return config.token; // Fallback + return config.token; } } ``` -1. **Use the token to login into the ** +1. **Use the token to initialize the ** - Call `fetchToken` to get a fresh RTM token. Use the token in the `RTMConfig` to initiate the . + Call `FetchToken` to get a fresh token before joining a channel. ``` javascript - const fetchTokenAndLogin = async (uid) => { - const token = await fetchToken(uid); - signalingManager.login(uid, token); - }; + try { + const token = await fetchToken(config.uid); + if (rtmConfig !== undefined && rtmConfig.token == undefined) { + rtmConfig.token = token; + } + rtmConfig = rtmConfig || { + token: token, + useStringUserId: config.useStringUserId, + logUpload: config.logUpload, + presenceTimeout: config.presenceTimeout, + }; + signalingEngine = new AgoraRTM.RTM(config.appId, config.uid, rtmConfig); + } catch (error) { + console.log("Error:", error); + } ``` 1. **Retrieve an RTC token** @@ -60,35 +72,37 @@ To retrieve tokens from the token server and use them to authenticate your { + resolve(response.data.rtcToken); + }) + .catch((error) => { + console.log(error); + }); + }); } else { return config.rtcToken; } } + ``` 1. **Use the RTC token to join a stream channel** @@ -98,17 +112,15 @@ To retrieve tokens from the token server and use them to authenticate your { console.log(response); - messageCallback("Left the channel: " + streamChannelName); + messageCallback("left channel: " + streamChannelName); streamChannel = null; }); } @@ -130,7 +142,7 @@ To retrieve tokens from the token server and use them to authenticate your when the token is about to expire** A token expires after the `tokenExpiryTime` specified in the call to the token server. If the expiry time - is not specified the default timeout is 24 hours. The `TokenPrivilegeWillExpire` event receives a callback when + is not specified the default timeout is 24 hours. The `onTokenPrivilegeWillExpire` event receives a callback when the current token is about to expire so that a fresh token may be retrieved and used. ``` javascript @@ -154,7 +166,7 @@ To retrieve tokens from the token server and use them to authenticate your @@ -17,16 +18,8 @@ purposes. To see how to develop your own token generator and integrate it into y ## Understand the tech -An authentication token is a dynamic key that is valid for a maximum of 24 hours. On request, a token server returns an authentication token that is valid for a specific user. A token server generates two types of tokens: - -* To initialize the , you use an RTM token. An RTM token is valid only for the user Id that you use to generate it. -* To join a stream channel, you use an RTC token. An RTC token is valid only for the channel name and the user Id that you use to generate it. - -The following figure shows the call flow you need to implement to create step-up-authentication with : - -![token authentication flow](/images/signaling/authentication-workflow.svg) - -To initiate the engine, your retrieves an RTM token from the token server in your security infrastructure. Your then sends this token to for authentication. validates the token and reads the user and project information stored in the token. +An authentication token is a dynamic key that is valid for a maximum of 24 hours. On request, a token server returns +an authentication token that is valid for a specific user. To join a stream channel you request an RTC token from the server by supplying a user Id and a channel name. You do not need an authentication token to subscribe to a message channel. @@ -42,7 +35,10 @@ A token contains the following information: - The channel name (only for RTC tokens) -When the token is about to expire, sends an event to your and you renew the session with a new token. +The following figure shows the call flow you need to implement to create step-up-authentication with : + +![token authentication flow](/images/signaling/authentication-workflow.svg) + ## Prerequisites @@ -81,4 +77,6 @@ In the , the uses an authentication toke This section contains information that completes the information in this page, or points you to documentation that explains other aspects to this product. + + diff --git a/shared/signaling/authentication-workflow/reference/index.mdx b/shared/signaling/authentication-workflow/reference/index.mdx index ee99b112a..46c097558 100644 --- a/shared/signaling/authentication-workflow/reference/index.mdx +++ b/shared/signaling/authentication-workflow/reference/index.mdx @@ -8,7 +8,7 @@ import Windows from './windows.mdx'; - To ensure communication security in a test or production environment, use a token server to generate token is recommended to ensure communication security, see [Secure authentication with tokens](../develop/authentication-workflow). -- [Downloads](../reference/downloads) +- [Downloads](../reference/downloads) shows you alternative ways to add in your project. - SDK Integration Methods: diff --git a/shared/signaling/authentication-workflow/test/web.mdx b/shared/signaling/authentication-workflow/test/web.mdx index e53740d8a..a0fa304d2 100644 --- a/shared/signaling/authentication-workflow/test/web.mdx +++ b/shared/signaling/authentication-workflow/test/web.mdx @@ -6,20 +6,36 @@ - `appId` - with the value from . - `serverUrl` - with the base URL for your token server. For example: `https://agora-token-service-production-yay.up.railway.app`. +1. **Start the reference app** -1. **Run the reference app**: + 1. In Terminal, navigate to ``. - In Terminal, navigate to ``, then run the following command: + 1. Run the following commands: - ``` bash - pnpm dev - ``` + ``` bash + npm run build + npm run start:dev + ``` -1. **Test the authentication server functionality**: +1. **Run the proxy server** + + For security reasons, browsers restrict cross-origin HTTP requests initiated from scripts. To make requests to your + token server, this sample app uses the [NodeJS corsAnywhere proxy](/src/authentication_guide/proxy.js) which adds [CORS + headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to the proxied requests. To start this server: + + 1. In a new Terminal, navigate to `/src` + + 1. Run the following command: + + ``` bash + node proxy + ``` + +1. **Send messages between users** For each user you want to communicate between: - 1. Use the URL displayed in Terminal to open the app in your browser. + 1. Open a browser tab instance at http://localhost:9000/authentication_workflow/. 1. Enter a numeric user ID. @@ -31,4 +47,4 @@ 1. Send messages between users. - + \ No newline at end of file diff --git a/shared/signaling/cloud-proxy/_cloud-proxy.mdx b/shared/signaling/cloud-proxy/_cloud-proxy.mdx index c2f918486..a2e2a24fc 100644 --- a/shared/signaling/cloud-proxy/_cloud-proxy.mdx +++ b/shared/signaling/cloud-proxy/_cloud-proxy.mdx @@ -26,13 +26,13 @@ The steps you need to implement in your are: ## Prerequisites -To follow this page, you must: +To follow this page, you must have: - Setup the [ reference app](/en/signaling/get-started/get-started-sdk#project-setup) - Contact support@agora.io and enable for your project. -- Configure your firewall to allow communication through the [allowed IP address](../reference/cloud-proxy-allowed-ips). +- Configured your firewall to allow communication through the [allowed IP address](../reference/cloud-proxy-allowed-ips). ## Implement communication using @@ -43,6 +43,10 @@ This section shows how to use the to implement in y ## Test +For each user you use in your tests: + +1. [Generate a temporary token](../reference/manage-agora-account#generate-a--token). + diff --git a/shared/signaling/cloud-proxy/project-implementation/web.mdx b/shared/signaling/cloud-proxy/project-implementation/web.mdx index 4f9ee244a..8e46a90d8 100644 --- a/shared/signaling/cloud-proxy/project-implementation/web.mdx +++ b/shared/signaling/cloud-proxy/project-implementation/web.mdx @@ -15,11 +15,12 @@ ``` javascript // Set cloud proxy const rtmConfig = { + token: config.token, cloudProxy: config.cloudProxy, }; // Extend the SignalingManager by importing it - const signalingManager = await SignalingManagerAuthentication( + const signalingManager = await SignalingManager( messageCallback, eventsCallback, rtmConfig diff --git a/shared/signaling/cloud-proxy/project-test/index.mdx b/shared/signaling/cloud-proxy/project-test/index.mdx index f030391fe..7b1ffffef 100644 --- a/shared/signaling/cloud-proxy/project-test/index.mdx +++ b/shared/signaling/cloud-proxy/project-test/index.mdx @@ -7,11 +7,7 @@ import Flutter from './flutter.mdx'; import MacOS from './macos.mdx' import Unity from './unity.mdx' import Windows from './windows.mdx'; -import Test from '@docs/shared/common/project-test/index.mdx'; -To test this functionality: - - diff --git a/shared/signaling/cloud-proxy/project-test/web.mdx b/shared/signaling/cloud-proxy/project-test/web.mdx index a3e87af40..c85fe8b60 100644 --- a/shared/signaling/cloud-proxy/project-test/web.mdx +++ b/shared/signaling/cloud-proxy/project-test/web.mdx @@ -1,7 +1,20 @@ +2. In `/src/signaling_manager/config.json`: -3. **Test Cloud Proxy** + 1. Replace the value of `token` with the temporary token. - Login to , you send and receive messages through Cloud Proxy. + 1. Replace the values for `uid`, `appId`, and `channelName` with the app ID, + and channel name for the values from . + +1. Open a command prompt in the project folder, and run the following command: + + ``` bash + npm run build + npm run start:dev + ``` + +1. Open the project at http://localhost:9000/cloud_proxy/. + +1. Login to , then send and receive messages through cloud proxy. - + \ No newline at end of file diff --git a/shared/signaling/data-encryption/_data_encryption.mdx b/shared/signaling/data-encryption/_data_encryption.mdx index b9cd07dfd..9fa8ec7b2 100644 --- a/shared/signaling/data-encryption/_data_encryption.mdx +++ b/shared/signaling/data-encryption/_data_encryption.mdx @@ -49,7 +49,7 @@ To implement data encryption, do the following: -## Test data encryption +## Test your implementation diff --git a/shared/signaling/data-encryption/project-implementation/web.mdx b/shared/signaling/data-encryption/project-implementation/web.mdx index e74008532..ad2ffe7a8 100644 --- a/shared/signaling/data-encryption/project-implementation/web.mdx +++ b/shared/signaling/data-encryption/project-implementation/web.mdx @@ -44,16 +44,17 @@ ``` javascript // Convert the encryptionSaltBase64 string to base64ToUint8Array. - encryptionSaltBase64 = base64ToUint8Array(config.salt); + encryptionSaltBase64 = base64ToUint8Array(config.encryptionSaltBase64); // Convert the encryptionKey string to hex2ascii. - encryptionKey = hex2ascii(config.cipherKey); + encryptionKey = hex2ascii(config.encryptionKey); // Set an encryption mode. encryptionMode = config.encryptionMode; // Start channel encryption const rtmConfig = { - logLevel: config.logLevel, - useStringUserId: config.useStringUserId, - encryptionMode: config.encryptionMode, + token: config.token, + logLevel: "debug", + useStringUserId: true, + encryptionMode: encryptionMode, salt: encryptionSaltBase64, cipherKey: encryptionKey, }; @@ -63,11 +64,7 @@ ``` javascript // Signaling Manager creates the signaling engine and channel for you - const signalingManager = await SignalingManagerAuthentication( - messageCallback, - eventsCallback, - rtmConfig - ); + const signalingManager = await SignalingManager(showMessage, handleSignalingEvents, rtmConfig); ``` diff --git a/shared/signaling/data-encryption/project-test/index.mdx b/shared/signaling/data-encryption/project-test/index.mdx index 334e2ed32..7e0d62854 100644 --- a/shared/signaling/data-encryption/project-test/index.mdx +++ b/shared/signaling/data-encryption/project-test/index.mdx @@ -7,10 +7,8 @@ import Flutter from './flutter.mdx'; import ReactNative from './react-native.mdx' import MacOS from './macos.mdx'; import Windows from './windows.mdx'; -import Test from '@docs/shared/common/project-test/index.mdx'; - -To test this functionality: +To ensure that you have implemented data encryption in your : 1. **Create the cypher key and salt** @@ -25,22 +23,7 @@ To test this functionality: ``` bash openssl rand -base64 32 ``` -1. **Configure data encryption** - - In `/src/signaling_manager/config.json`: - - 1. Paste the `-hex 32 key` into the `cipherKey` variable. - - 1. Paste the salt from the `-base64 32` call into the `salt` variable. - - 1. Set `encryptionMode` to 1. - - - - -4. **Test data encryption** - Login to as multiple users, then send and receive secure messages. diff --git a/shared/signaling/data-encryption/project-test/web.mdx b/shared/signaling/data-encryption/project-test/web.mdx index cdd010fd9..92e4c17aa 100644 --- a/shared/signaling/data-encryption/project-test/web.mdx +++ b/shared/signaling/data-encryption/project-test/web.mdx @@ -1,4 +1,31 @@ +2. [Generate a temporary token](../reference/manage-agora-account#generate-a--token). + +1. In `/src/signaling_manager/config.json`: + + 1. Replace the value of `token` with the temporary token. + + 1. Replace the values for `uid`, `appId`, and `channelName` with the app ID, + and channel name for the values from . + + 1. Paste the `-hex 32 key` into the `cipherKey` variable. + + 1. Paste the salt from the `-base64 32` call into the `salt` variable. + + 1. Set `encryptionMode` to 1. + +1. Open a command prompt in the project folder, and run the following command: + + ``` bash + npm run build + npm run start:dev + ``` + +1. **For each user you to test**: + + 1. Open the project at http://localhost:9000/data_encryption/. + + 1. Login to , then send and receive secure messages. diff --git a/shared/signaling/geofencing/index.mdx b/shared/signaling/geofencing/index.mdx index 05c2deedb..b89d4a257 100644 --- a/shared/signaling/geofencing/index.mdx +++ b/shared/signaling/geofencing/index.mdx @@ -54,6 +54,11 @@ If your fails to connect to the specified region of as multiple users, then send and receive messages using geofencing. diff --git a/shared/signaling/geofencing/project-test/web.mdx b/shared/signaling/geofencing/project-test/web.mdx index 5c2aa9d29..b087ae23c 100644 --- a/shared/signaling/geofencing/project-test/web.mdx +++ b/shared/signaling/geofencing/project-test/web.mdx @@ -1,4 +1,20 @@ +2. In `/src/signaling_manager/config.json`: + 1. Replace the value of `token` with the temporary token. + + 1. Replace the values for `uid`, `appId`, and `channelName` with the app ID, + and channel name for the values from . + +1. Open a command prompt in the project folder, and run the following command: + + ``` bash + npm run build + npm run start:dev + ``` + +1. Open the project at http://localhost:9000/geofencing/. + +1. Login to , then send and receive messages using geofencing. - + \ No newline at end of file diff --git a/shared/signaling/get-started-sdk/implementation/web.mdx b/shared/signaling/get-started-sdk/implementation/web.mdx index 28aedcaef..cdd010fd9 100644 --- a/shared/signaling/get-started-sdk/implementation/web.mdx +++ b/shared/signaling/get-started-sdk/implementation/web.mdx @@ -1,203 +1,4 @@ -1. **Declare the variables to create an instance** - - You use these objects to communicate with . - - ``` typescript - // The Signaling RTMEngine instance - let signalingEngine = null; - let signalingChannel = null; - ``` - -1. **Declare the variables to join a channel** - - Best practice is to keep these variables separate from your code. For example, in the - reference app, we use the following JSON configuration file. - - ``` json - { - "uid": "1", - "appId": "", - "channelName": "", - "token": "", - "proxyUrl": "http://localhost:8080/", - "serverUrl": "", - "tokenExpiryTime": "600", - "encryptionMode": 1, - "salt": "", - "cipherKey": "", - "presenceTimeout": 300, - "logUpload": false, - "logLevel": "debug", - "cloudProxy": true, - "useStringUserId": false, - "rtcToken": "" - } - ``` - To learn more about the configuration parameters, see [RTMConfig](/en/signaling/reference/api#rtmconfig). - -3. **Configure a instance** - - Your code reads the parameters from the configuration file, initializes the SignalingEngine instance and adds the event listeners. - - ``` typescript - // Set up the signaling engine with the provided App ID, UID, and configuration - const setupSignalingEngine = async (rtmConfig) => { - try { - rtmConfig = rtmConfig || { - token: config.token, - useStringUserId: config.useStringUserId, - logUpload: config.logUpload, - presenceTimeout: config.presenceTimeout, - }; - signalingEngine = new AgoraRTM.RTM(config.appId, config.uid, rtmConfig); - } catch (error) { - console.log("Error:", error); - } - }; - ``` - -4. **Handle and respond to events** - - The following event listeners handle notification events for features: - - [Messages](/en/signaling/reference/api#messages): send and receive messages between users - - [Presence](/en/signaling/reference/api#presence): monitor user online, offline, subscription and user historical - status change - - [Storage](/en/signaling/reference/api#storage): dynamically set, store, update, and delete channel and user metadata - - [Topics](/en/signaling/reference/api#topics): subscribe and distribute data streams - - [Lock](/en/signaling/reference/api#lock): lock a resource when it is shared between different processes - - [Status](en/signaling/reference/api?platform=web#setstate): add custom statuses such as scores, game status, location, mood, and hosting status for themselves. - - [token expiration](/en/signaling/reference/api#event-listeners): ensure the users is always connected to - - The following code sets up event handlers for events: - - ``` typescript - // Add listeners to handle event notifications - // Message event handler - signalingEngine.addEventListener("message", eventArgs => { - eventsCallback("message", eventArgs); - messageCallback( - "Received message from " + - eventArgs.publisher + - ": " + - eventArgs.message - ); - }); - // State event handler - signalingEngine.addEventListener("status", eventArgs => { - eventsCallback("status", eventArgs); - messageCallback( - "Connection state changed to: " + - eventArgs.state + - ", Reason: " + - eventArgs.reason - ); - }); - // Presence event handler - signalingEngine.addEventListener("presence", eventArgs => { - eventsCallback("presence", eventArgs); - if (eventArgs.eventType === "SNAPSHOT") { - messageCallback( - `User ${eventArgs.snapshot[0].userId} joined channel ${eventArgs.channelName}` - ); - } else { - messageCallback( - "Presence event: " + - eventArgs.eventType + - ", User: " + - eventArgs.publisher - ); - } - }); - // Storage event handler - signalingEngine.addEventListener("storage", eventArgs => { - eventsCallback("storage", eventArgs); - }); - // Topic event handler - signalingEngine.addEventListener("topic", eventArgs => { - eventsCallback("topic", eventArgs); - }); - // Lock event handler - signalingEngine.addEventListener("lock", eventArgs => { - eventsCallback("lock", eventArgs); - }); - // TokenPrivilegeWillExpire event handler - signalingEngine.addEventListener("TokenPrivilegeWillExpire", eventArgs => { - eventsCallback("TokenPrivilegeWillExpire ", eventArgs); - }); - ``` - -1. **Login to ** - - In , each token is specific to a user ID. If `uid` and `token` do not match, your user cannot initiate . - - ``` typescript - // Login to the signaling engine - const login = async (uid, token) => { - try { - if (uid !== undefined) config.uid = uid; - if (token !== undefined) config.token = token; - - await setupSignalingEngine(rtmConfig); - const result = await signalingEngine.login(); - console.log(result); - } catch (error) { - console.log(error); - } - }; - ``` - -1. **Monitor users in channel using presence** - - In , you can use `presence` to get information about users in the channel. To get a list of active users, call `presence.getOnlineUsers()`: - - ``` typescript - // Get list of active members in the channel - const getOnlineMembersInChannel = async (channelName, channelType) => { - const result = await getSignalingEngine().presence.getOnlineUsers( - channelName, - channelType - ); - return result.occupants; - }; - ``` - -1. **Send a message** - - Messages are sent directly to a channel. - - ``` typescript - // Send a message to a channel - const sendChannelMessage = async (channelName, Message) => { - const payload = { type: "text", message: Message }; - const publishMessage = JSON.stringify(payload); - try { - const sendResult = await signalingEngine.publish( - channelName, - publishMessage - ); - messageCallback(`Message sent to channel ${channelName}: ${Message}`); - } catch (error) { - console.log(error); - } - }; - ``` - - You setup the event handlers for messages received from other users during initiation. - - -1. **Logout of ** - - Had enough of the conversation? Just logout. - - ``` typescript - // Logout from the signaling engine - const logout = async () => { - await signalingEngine.logout(); - }; - ``` - -You have just implemented the workflow. Yes, it's as easy as that. diff --git a/shared/signaling/get-started-sdk/index.mdx b/shared/signaling/get-started-sdk/index.mdx index f72bfd54d..c1279fc30 100644 --- a/shared/signaling/get-started-sdk/index.mdx +++ b/shared/signaling/get-started-sdk/index.mdx @@ -7,20 +7,25 @@ import Reference from '@docs/shared/signaling/get-started-sdk/reference/index.md -## Implement +## Implement Signaling -Best practice is to separate the workflows from your UI implementation. The sample -project implements the business logic in the `SignalingManager` object. This class encapsulates the -`signalingEngine`, an instance of the`AgoraRTM`, and core functionality such as logging in to , sending a message, listening for messages from other users and logging out. +The code that goes here must have -The following code examples show how to implement these steps in your : + * Variables: signalingEngine, signalingManager, channelName. In the get started channel name is fixed. APIkey etc as video calling. + * All Agora code in signalingManager, all UI code in another class + * Does the following: + * Login and logout. signalingEngine is initiated at login and destroyed at logout. + * joinChannle, leaveChannel + * listen for events in the channel + * Logging ## Test -This section explains how to run the reference app and see the corresponding features in an . +## Test your implementation + +This section explains how to run the sample project and see the corresponding features in an . Best practice is to run this project on a physical mobile device, as some simulators may not support the full features of this project. diff --git a/shared/signaling/get-started-sdk/reference/index.mdx b/shared/signaling/get-started-sdk/reference/index.mdx index eb6733fc3..0c7d102af 100644 --- a/shared/signaling/get-started-sdk/reference/index.mdx +++ b/shared/signaling/get-started-sdk/reference/index.mdx @@ -5,9 +5,10 @@ import Unity from './unity.mdx'; import Web from './web.mdx'; import Windows from './windows.mdx'; -For more information, see: +- To ensure communication security in a test or production environment, use a token server to generate token is +recommended to ensure communication security, see [Secure authentication with tokens](../get-started/authentication-workflow). -- [Downloads](../reference/downloads) +- [Downloads](../reference/downloads) shows you alternative ways to add in your project. - [API limitations](/en/signaling/reference/limitations) diff --git a/shared/signaling/get-started-sdk/setup/web.mdx b/shared/signaling/get-started-sdk/setup/web.mdx new file mode 100644 index 000000000..4fd4f55b8 --- /dev/null +++ b/shared/signaling/get-started-sdk/setup/web.mdx @@ -0,0 +1,13 @@ + + +1. Clone the [ sample project](https://github.com/AgoraIO/signalign-sdk-samples-js) to + `` on your development machine: + + ```bash + git clone https://github.com/AgoraIO/signaling-sdk-samples-js.git + ``` + +2. Open the sample project in your development environment. + + + \ No newline at end of file diff --git a/shared/signaling/get-started-sdk/test/index.mdx b/shared/signaling/get-started-sdk/test/index.mdx index a79bf06f4..26268c7fb 100644 --- a/shared/signaling/get-started-sdk/test/index.mdx +++ b/shared/signaling/get-started-sdk/test/index.mdx @@ -5,14 +5,11 @@ import Unity from './unity.mdx'; import Web from './web.mdx'; import Windows from './windows.mdx'; -In , each authentication token you create is specific for a user ID. You create a token for each -user in the channel, each user must log in from different instance of your . -To test , you run 2 or more instances of your . When you call `login` using , ensure that the UID is the same as you used to create the token. -For each user in your tests: +1. [Generate a temporary token](../reference/manage-agora-account#generate-a-temporary-token) in . -1. **[Generate a temporary token](../reference/manage-agora-account#generate-a-temporary-token)**. +1. In your browser, navigate to the web demo and update _App ID_, _Channel_, and _Token_ with the values for your temporary token, then click **Join**. diff --git a/shared/signaling/get-started-sdk/test/web.mdx b/shared/signaling/get-started-sdk/test/web.mdx index fbc7e818b..fa69182c6 100644 --- a/shared/signaling/get-started-sdk/test/web.mdx +++ b/shared/signaling/get-started-sdk/test/web.mdx @@ -1,28 +1,4 @@ -2. **Configure the project**: - - In `/src/signaling_manager/config.json`: - - 1. Replace the value for `token` with the token. - - 1. Replace the value for `appId` with the value from . - - 1. Replace the value for UID with the the same value you used to generate the token. - - 1. Channel name can be any string. - -1. **Run the reference app**: - - Open Terminal in the project folder, then run the following command: - - ``` bash - pnpm dev - ``` - - Use the URL displayed in Terminal to open the app in your browser. - -1. **Test this functionality**: - - Choose **SDK quickstart**, then log in to and send and receive messages. When you open the reference app in multiple tabs, after login you see the messages sent and received in the log. + diff --git a/shared/signaling/get-started-sdk/web.mdx b/shared/signaling/get-started-sdk/web.mdx new file mode 100644 index 000000000..851f0a56e --- /dev/null +++ b/shared/signaling/get-started-sdk/web.mdx @@ -0,0 +1,354 @@ + + +## Project setup + +### 1. Create a web project + +Create a new directory named `RTM_quickstart`. Go to the directory, and run `npm init` to create a `package.json` file. Then, create the following files: + +- `index.html` + +- `index.js` + +The project directory now has the following structure: + +``` text +RTM_quickstart +├─ index.html +├─ index.js +└─ package.json +``` + +### 2. Integrate the SDK + +Integrate the Agora for Web into your project through npm, as follows: + +1. In the `package.json` file, add `agora-rtm-sdk` and its version number to the `dependencies` field: + + ``` json + { + "name": "web", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "dependencies": { + "agora-rtm-sdk": "latest" + }, + "author": "", + "license": "ISC" + } + ``` + +2. Import the `AgoraRTM` module in the JS or TS file: + + ```javascript + import AgoraRTM from 'agora-rtm-sdk' + ``` + +## Implement Signaling + +### 1. Create the UI + +Refer to the following code sample to modify the `index.html` file: `` is used to refer to the `bundle.js` file packaged by webpack. A sample webpack configuration is shown in later steps. + +``` html + + + + + <Vg k="MESS" /> Quickstart + + + +

Quickstart

+
+
+
+
+
+ + +
+
+
+ + +
+
+
+ +
+
+
+ + +
+
+
+ + + +
+
+ + +
+
+ + + +
+
+
+
+
+
+
+ + +``` + +### 2. Implement peer-to-peer and channel messaging + +Refer to the following code sample to modify the `index.js` file. Note that to avoid browser-compatibility issues, the sample uses the import command to import the SDK and webpack to package the JS file. You need to replace `""` and `""` with the App ID and token you have acquired in the previous step. + +```javascript +import AgoraRTM from 'agora-rtm-sdk' + +// Params for login +let options = { + uid: "", + token: "" +} + +// Your app ID +const appID = "" +// Your token +options.token = "" + +// Initialize client +const client = AgoraRTM.createInstance(appID) + +// Client Event listeners +// Display messages from peer +client.on('MessageFromPeer', function (message, peerId) { + + document.getElementById("log").appendChild(document.createElement('div')).append("Message from: " + peerId + " Message: " + message) +}) +// Display connection state changes +client.on('ConnectionStateChanged', function (state, reason) { + + document.getElementById("log").appendChild(document.createElement('div')).append("State changed To: " + state + " Reason: " + reason) + +}) + +let channel = client.createChannel("demoChannel") + +channel.on('ChannelMessage', function (message, memberId) { + + document.getElementById("log").appendChild(document.createElement('div')).append("Message received from: " + memberId + " Message: " + message) + +}) +// Display channel member stats +channel.on('MemberJoined', function (memberId) { + + document.getElementById("log").appendChild(document.createElement('div')).append(memberId + " joined the channel") + +}) +// Display channel member stats +channel.on('MemberLeft', function (memberId) { + + document.getElementById("log").appendChild(document.createElement('div')).append(memberId + " left the channel") + +}) + +// Button behavior +window.onload = function () { + + // Buttons + // login + document.getElementById("login").onclick = async function () { + options.uid = document.getElementById("userID").value.toString() + await client.login(options) + } + + // logout + document.getElementById("logout").onclick = async function () { + await client.logout() + } + + // create and join channel + document.getElementById("join").onclick = async function () { + // Channel event listeners + // Display channel messages + await channel.join().then (() => { + document.getElementById("log").appendChild(document.createElement('div')).append("You have successfully joined channel " + channel.channelId) + }) + } + + // leave channel + document.getElementById("leave").onclick = async function () { + + if (channel != null) { + await channel.leave() + } + + else + { + console.log("Channel is empty") + } + + } + + // send peer-to-peer message + document.getElementById("send_peer_message").onclick = async function () { + + let peerId = document.getElementById("peerId").value.toString() + let peerMessage = document.getElementById("peerMessage").value.toString() + + await client.sendMessageToPeer( + { text: peerMessage }, + peerId, + ).then(sendResult => { + if (sendResult.hasPeerReceived) { + + document.getElementById("log").appendChild(document.createElement('div')).append("Message has been received by: " + peerId + " Message: " + peerMessage) + + } else { + + document.getElementById("log").appendChild(document.createElement('div')).append("Message sent to: " + peerId + " Message: " + peerMessage) + + } + }) + } + + // send channel message + document.getElementById("send_channel_message").onclick = async function () { + + let channelMessage = document.getElementById("channelMessage").value.toString() + + if (channel != null) { + await channel.sendMessage({ text: channelMessage }).then(() => { + + document.getElementById("log").appendChild(document.createElement('div')).append("Channel message: " + channelMessage + " from " + channel.channelId) + + } + + ) + } + } +} +``` + +## Test your app + +This article uses [webpack](https://webpack.js.org/) to package the project and `webpack-dev-server` to run the project. + +1. In the `package.json` file, add `webpack`, `webpack-cli`, and `webpack-dev-server` to the `dependencies` field, and the `build` and `start:dev` commands to the `scripts` field. + + ``` json + { + "name": "web", + "version": "1.0.0", + "description": "", + "main": "index.js", + "scripts": { + "build": "webpack --config webpack.config.js", + "start:dev": "webpack serve --open --config webpack.config.js" + }, + "dependencies": { + "agora-rtm-sdk": "latest", + "webpack": "5.28.0", + "webpack-dev-server": "3.11.2", + "webpack-cli": "4.5.0" + }, + "author": "", + "license": "ISC" + } + ``` + +2. Create a file named `webpack.config.js` in the project directory to configure webpack. The JS file should contain the following lines: + + ```javascript + const path = require('path'); + + module.exports = { + entry: './index.js', + output: { + filename: 'bundle.js', + path: path.resolve(__dirname, './dist'), + }, + devServer: { + compress: true, + port: 9000 + } + }; + ``` + + The project directory now has the following structure: + + ``` text + RTM_quickstart + ├─ index.html + ├─ index.js + ├─ package.json + └─ webpack.config.js + ``` + +3. Run the following command in the project directory to install dependencies: + + ``` shell + $ npm install + ``` + +4. Run the following command to build and run the project using webpack: + + ``` shell + # Use webpack to package the project + $ npm run build + ``` + +5. Use webpack-dev-server to run the project + + ``` shell + $ npm run start:dev + ``` + +If the project runs successfully, you can send and receive peer-to-peer messages and channel messages. + +![1618225131946](https://web-cdn.agora.io/docs-files/1618225131946) + +## Considerations + +- The Agora supports creating multiple RtmClient instances that are independent of each other. + +- To send and receive peer-to-peer or channel messages, ensure that you have successfully logged in the Agora . + +- To use any of the channel features, you must first call the createChannel method to create a channel instance. + +- You can create multiple channel instances for each RtmClient instance, but you can only join a maximum of 20 channels at the same time. The `channelId` parameter needs to be channel-specific. + +- When you do not want to use a specific instance any more, you can use the `removeAllListeners` method to remove all its listeners. + +- You cannot reuse a received RtmMessage instance. + +## Next steps + +Generating a token by hand is not helpful in a production context. [Authenticate Your Users with Tokens](../develop/authentication-workflow) shows you how to start Signaling with a token that you retrieve from your server. + +## See also + +### Sample project + +Agora provides an open-source [sample project](https://github.com/AgoraIO//tree/master/Agora--Tutorial-Web) on GitHub for your reference. + +You can also quickly experience Agora Signaling through the [Agora Web sample app](https://webdemo.agora.io/agora-web-showcase/examples/Agora--Tutorial-Web/). + +### SDK Integration Methods + +[Downloads](../reference/downloads) shows you alternative ways to add in your project. + + diff --git a/shared/signaling/reference/web.mdx b/shared/signaling/reference/api-reference-web.mdx similarity index 85% rename from shared/signaling/reference/web.mdx rename to shared/signaling/reference/api-reference-web.mdx index 8cfe36c1c..b6da468c9 100644 --- a/shared/signaling/reference/web.mdx +++ b/shared/signaling/reference/api-reference-web.mdx @@ -1,4 +1,3 @@ - The Signaling SDK API Reference lists the description, methods, basic usage, sample code, and return values. It is divided in to the following sections: * [Setup](#setup) @@ -30,17 +29,7 @@ class RTM( constructor( appId: string, userId: string, - rtmConfig?: { - token: string, - encryptionMode: string, - cipherKey: string, - salt: Uint8Array, - useStringUserId: boolean, - presenceTimeout: number, - logUpload: boolean, - logLevel: string, - cloudProxy: boolean - } + rtmConfig?: RTMConfig ); ) ``` @@ -49,7 +38,7 @@ class RTM( | :---------: | :------------------------------------------------: | :------: | :----: | ------------------------------------------------------------------------------- | | `appId` | string | Required | - | The App ID of your Agora project on the Agora console. | | `userId` | string | Required | - | The unique ID to identify a user or device. | -| `rtmConfig` | `RtmConfig` | Optional | - | The configuration parameters for initialization, see [`RtmConfig`](#rtmconfig). | +| `rtmConfig` | `rtm` | Optional | - | The configuration parameters for initialization, see `rtm`. | #### Basic Usage @@ -102,7 +91,7 @@ const rtmConfig = { cipherKey : "yourCipherKey", presenceTimeout : 300, logUpload : true, - logLevel : 'debug', + logFilter : 'debug', cloudProxy : false, useStringUserId : false }; @@ -130,63 +119,65 @@ In Signaling there are seven types of event as follows: You can add event listeners in the following way: ```javascript -// Add message event listeners -// Message -rtm.addEventListener("message", event => { - const channelType = event.channelType; // Which channel type it is, Should be "STREAM" or "MESSAGE" . - const channelName = event.channelName; // Which channel does this message come from - const topic = event.topicName; // Which Topic does this message come from, it is valid when the channelType is "STREAM". - const messageType = event.messageType; // Which message type it is, Should be "sting" or "binary" . - const customType = event.customType; // User defined type - const publisher = event.publisher; // Message publisher - const message = event.message; // Message payload - const pubTime = event.publishTime; // Message publisher timestamp -}); -// Presence -rtm.addEventListener("presence", event => { - const action = event.eventType; // Which action it is ,should be one of 'SNAPSHOT'、'INTERVAL'、'JOIN'、'LEAVE'、'TIMEOUT、'STATE_CHANGED'、'OUT_OF_SERVICE'. - const channelType = event.channelType; // Which channel type it is, Should be "STREAM" or "MESSAGE" . - const channelName = event.channelName; // Which channel does this event come from - const publisher = event.publisher; // Who trigger this event - const states = event.stateChanged; // User state payload - const interval = event.interval; // Interval payload - const snapshot = event.snapshot; // Snapshot payload -}); -// Topic -rtm.addEventListener("topic", event => { - const action = event.evenType; // Which action it is ,should be one of 'SNAPSHOT'、'JOIN'、'LEAVE'. - const channelName = event.channelName; // Which channel does this event come from - const publisher = event.userId; // Who trigger this event - const topicInfos = event.topicInfos; // Topic information payload - const totalTopics = event.totalTopics; // How many topics -}); -// Storage -rtm.addEventListener("storage", event => { - const channelType = event.channelType; // Which channel type it is, Should be "STREAM" or "MESSAGE" . - const channelName = event.channelName; // Which channel does this event come from - const publisher = event.publisher; // Who trigger this event - const storageType = event.storageType; // Which category the event is, should be 'USER'、'CHANNEL' - const action = event.eventType; // Which action it is ,should be one of "SNAPSHOT"、"SET"、"REMOVE"、"UPDATE" or "NONE" - const data = event.data; // 'USER_METADATA' or 'CHANNEL_METADATA' payload -}); -// Lock -rtm.addEventListener("lock", event => { - const channelType = event.channelType; // Which channel type it is, Should be "STREAM" or "MESSAGE" . - const channelName = event.channelName; // Which channel does this event come from - const publisher = event.publisher; // Who trigger this event - const action = event.evenType; // Which action it is ,should be one of 'SET'、'REMOVED'、'ACQUIRED'、'RELEASED'、'EXPIRED'、'SNAPSHOT' - const lockName = event.lockName; // Which lock it effect - const ttl = event.ttl; // The ttl of this lock - const snapshot = event.snapshot; // Snapshot payload -}); -// Connection State Change -rtm.addEventListener("status", event => { - const currentState = event.state; // Which connection state right now - const changeReason = event.reason; // Why trigger this event -}); -// Token Privilege Will Expire -rtm.addEventListener("TokenPrivilegeWillExpire", (channelName) => { - const channelName = channelName; // Which Channel Token Will Expire +// add message event listeners +rtm.addEventListener({ + // Message + message : event => { + const channelType = event.channelType; // Channel type, 'STREAM' or 'MESSAGE'. + const channelName = event.channelName; // Channel name + const topic = event.topicName; // Topic name, available only when channelType is 'STREAM'. + const messageType = event.messageType; // Message type, "string" or "binary" . + const customType = event.customType; // User-defined type + const publisher = event.publisher; // Message publisher + const message = event.message; // Message payload + const pubTime = event.publishTime; // Message timestamp + }, + // Presence + presence : event => { + const action = event.eventType; // Action type, 'SNAPSHOT','INTERVAL','JOIN','LEAVE','TIMEOUT,'STATE_CHANGED','OUT_OF_SERVICE'. + const channelType = event.channelType; // Channel type, 'STREAM' or 'MESSAGE'. + const channelName = event.channelName; // Channel name + const publisher = event.publisher; // User triggers this event + const states = event.stateChanged; // User state payload + const interval = event.interval; // Interval payload + const snapshot = event.snapshot; // Snapshot payload + }, + // Topic + topic : event => { + const action = event.evenType; // Action type, 'SNAPSHOT','JOIN',or 'LEAVE'. + const channelName = event.channelName; // Channel name + const publisher = event.userId; // User triggers this event + const topicInfos = event.topicInfos; // Topic information payload + const totalTopics = event.totalTopics; // Topic number + }, + // Storage + storage : event => { + const channelType = event.channelType; // Channel type, 'STREAM' or 'MESSAGE'. + const channelName = event.channelName; // Channel name + const publisher = event.publisher; // User triggers this event + const storageType = event.storageType; // Category of the metadata, 'USER or 'CHANNEL' + const action = event.eventType; // Action type, 'SNAPSHOT', 'SET', 'REMOVE', 'UPDATE' or 'NONE' + const data = event.data; // User metadata or channel metadata payload + }, + // Lock + lock : event => { + const channelType = event.channelType; // Channel type, 'STREAM' or 'MESSAGE'. + const channelName = event.channelName; // Channel name + const publisher = event.publisher; // User triggers this event + const action = event.evenType; // Action type, 'SET','REMOVED','ACQUIRED','RELEASED','EXPIRED', or 'SNAPSHOT' + const lockName = event.lockName; // Lock name + const ttl = event.ttl; // The ttl of this lock + const snapshot = event.snapshot; // Snapshot payload + }, + // Connection State Change + status : (states, reason) => { + const currentState = states; // Connection state + const changeReason = reason; // Reason Why the user triggers this event + }, + // Token Privilege Will Expire + TokenPrivilegeWillExpire : (channelName) => { + const channelName = channelName; // Name of the channel in which the token is to expire + }, }); ``` @@ -979,22 +970,22 @@ The presence feature provides the ability to monitor user online, offline, and u Presence applies to both message channels and stream channels. -### `getOnlineUsers` +### `whoNow` #### Description -Call the `getOnlineUsers` method to query user information in real-time such as the number of online users, the list of online users and their temporary user status in the specified channel. +Call the `whoNow` method to query user information in real-time such as the number of online users, the list of online users and their temporary user status in the specified channel. #### Method -You can call the `getOnlineUsers` method in the following way: +You can call the `whoNow` method in the following way: ```javascript -rtm.presence.getOnlineUsers( +rtm.presence.whoNow( channelName: string, channelType: string, options?: object -): Promise; +): Promise; ``` @@ -1021,7 +1012,7 @@ const options = { page : "yourBookMark" } try { - const result = await rtm.presence.getOnlineUsers( "chat_room", 'MESSAGE', options ); + const result = await rtm.presence.whoNow( "chat_room", 'MESSAGE', options ); console.log(result); } catch (status) { console.log(status); @@ -1030,9 +1021,9 @@ try { #### Return Value -If the method call succeeds, a `GetOnlineUsersResponse` is returned. +If the method call succeeds, a `WhoNowResponse` is returned. ```javascript -type GetOnlineUsersResponse = { +type WhoNowResponse = { timeToken: number , // Reserved property, indicating the timestamp of the successful operation. totalOccupancy : number , // Number of the online users in the channel. occupants : Array , // List of the online users in the channel and their temporary user state. @@ -1043,18 +1034,18 @@ type GetOnlineUsersResponse = { If the method call fails, [`ErrorInfo`](#errorinfo) is returned. -### `getUserChannels` +### `whereNow` #### Description -In scenarios such as statistic analytics and debugging, you may need to know all the channels that a specified user has subscribed to or joined. Call the `getUserChannels` method to get the list of channels where the specified user is in real-time. +In scenarios such as statistic analytics and debugging, you may need to know all the channels that a specified user has subscribed to or joined. Call the `whereNow` method to get the list of channels where the specified user is in real-time. #### Method -You can call the `getUserChannels` method in the following way: +You can call the `whereNow` method in the following way: ```javascript -rtm.presence.getUserChannels(userId: string): Promise; +rtm.presence.whereNow(userId: string): Promise; ``` | Parameter | Type | Required | Default | Description | @@ -1065,7 +1056,7 @@ rtm.presence.getUserChannels(userId: string): Promise; ```javascript try { - const result = await rtm.presence.getUserChannels( "Tony" ); + const result = await rtm.presence.whereNow( "Tony" ); console.log(result); } catch (status) { console.log(status); @@ -1074,9 +1065,9 @@ try { #### Return value -If the method call succeeds, a `GetUserChannelsResponse` is returned. +If the method call succeeds, a `WhereNowResponse` is returned. ```javascript -type GetUserChannelsResponse = { +type WhereNowResponse = { timeToken: number , // Reserved property, indicating the timestamp of the successful operation. totalChannel : number , // Number of the channels that the user has joined or subscribed to. channels : Array // List of the channels including channel name and channel type. @@ -2010,7 +2001,7 @@ You can call the `setLock` method in the following way: ```javascript rtm.lock.setLock( channelName: string, - channelType: string, + channelType: ConstantsType.ChannelType, lockName: string, options?: { ttl?: number; @@ -2037,7 +2028,7 @@ rtm.lock.setLock( try { const result = await rtm.Lock.setLock( channel:"my_channel", - channelType:"STREAM", + channelType:1, lockName: "my_lock", { ttl: 30 } ); @@ -2251,7 +2242,7 @@ You can call the `getLock` method in the following way: ```javascript rtm.lock.getLock( channelName: string, - channelType: string + channelType: ConstantsType.ChannelType ): Promise; ``` @@ -2282,11 +2273,7 @@ type GetLockResponse = { channelName : string , // Channel name. channelType : string , // Channel type. totalLocks : string, // Total lock number. - lockDetails : [{ - lockName: string, // Lock name. - owner: string, // Lock owner. - ttl: number // Time to live in seconds of the lock. - }] + lockDetails : Array // Details of the lock, consisting of an abject that contains lock name, lock owner, and time to live } ``` If the method call fails, [`ErrorInfo`](#errorinfo) is returned. @@ -2304,7 +2291,7 @@ You can call the `removeLock` method in the following way: ```javascript rtm.lock.removeLock( channelName: string, - channelType: string, + channelType: ConstantsType.ChannelType, lockName: string ): Promise; ``` @@ -2444,103 +2431,13 @@ If the method call fails, [`ErrorInfo`](#errorinfo) is returned. | `REMOTE_LEAVE` | A remote user left the channel. | -## Troubleshooting - -Refer to the following information for troubleshooting API calls. - ### ErrorInfo -If an API call fails, the SDK reports the error code and error description through the `errorCode` and `reason` attributes of `ErrorInfo`. - -```javascript +```JavaScript type ErrorInfo = { error: boolean; // Whether an error occurs. operation: string; // Operation type of this method call. errorCode: number; // Error code. reason: string; // Reason for the error. } -``` - -### Error codes table - -Refer to the following error codes table to identify and troubleshoot the problem: - -| Error code| Error description| Cause and solution | -| :------: | :-----------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `0` | RTM_ERROR_OK | Correct call | -| `-2` | RTM_ERROR_INVALID_ARGUMENT | Invalid argument:
- Check if the parameter type is correct
- Check if the parameter is out of range | -| `-12` | RTM_ERROR_TOO_OFTEN | API call QPS exceeded limit. See API usage limits for details:
- Improve business logic and reduce API calls frequency.
- Contact us for technical support. | -| `-10001` | RTM_ERROR_NOT_INITIALIZED | SDK not initialized. Please initialize the RTM instance before performing other operations. | -| `-10002` | RTM_ERROR_NOT_LOGIN | The user calls the API after not logging in to the RTM system, disconnecting for timeout, or actively logging out. Please log in to the RTM system first. | -| `-10003` | RTM_ERROR_INVALID_APP_ID | Invalid App ID:
- Check if the App ID is wrong.
- Check whether the App ID has activated the RTM service. | -| `-10005` | RTM_ERROR_INVALID_TOKEN | Invalid Token:
- The token is invalid, check whether the Token Provider generates an RTM Token. | -| `-10006` | RTM_ERROR_INVALID_USER_ID | Invalid User ID:
- Check if username is empty.
- Check if the username contains illegal characters. | -| `-10008` | RTM_ERROR_INVALID_CHANNEL_NAME | Invalid channel name:
- Check if the channel name is empty.
- Check if the channel name contains illegal characters. | -| `-10009` | RTM_ERROR_TOKEN_EXPIRED | Token expired. You need to call `renewToken` to reacquire the Token. | -| `-10011` | RTM_ERROR_LOGIN_TIMEOUT | Login timeout. You need to check whether the current network is stable and switch to a stable network environment. | -| `-10012` | RTM_ERROR_LOGIN_REJECTED | SDK login rejected by the server:
- Check whether the App ID has activated the RTM service.
- Check if Token or `userId` is banned. | -| `-10013` | RTM_ERROR_LOGIN_ABORTED | SDK login interrupted due to unknown problem:
- Check whether the current network is stable and switch to a stable network environment.
- The current `userId` is logged in at other end. | -| `-11001` | RTM_ERROR_CHANNEL_NOT_JOINED | The user has not joined the channel:
- The user is not online, offline or has not joined the channel
- Check for typos in `userId`. | -| `-11002` | RTM_ERROR_CHANNEL_NOT_SUBSCRIBED | The user has not subscribed to the channel:
- The user is not online, offline or has not joined the channel
- Check for typos in `userId`. | -| `-11003` | RTM_ERROR_CHANNEL_EXCEED_TOPIC_USER_LIMITATION | The number of subscribers to this topic exceeds the limit. | -| `-11005` | RTM_ERROR_CHANNEL_INSTANCE_EXCEED_LIMITATION | The number of created or subscribed channels exceeds the limit. See API usage limits for details. | -| `-11007` | RTM_ERROR_CHANNEL_JOIN_FAILED | Failed to join this channel:
- Check whether the number of joined channels exceeds the limit.
- Check if the channel name is illegal.
- Check if the network is disconnected. | -| `-11008` | RTM_ERROR_CHANNEL_INVALID_TOPIC_NAME | Invalid topic name:
- Check whether the topic name contains illegal characters.
- Check if the Topic name is empty. | -| `-11009` | RTM_ERROR_CHANNEL_INVALID_MESSAGE | Invalid message. Check whether the message type is legal, RTM only supports `string`, `Uint8Array` type messages. | -| `-11010` | RTM_ERROR_CHANNEL_MESSAGE_LENGTH_EXCEED_LIMITATION | Message length exceeded limit. Check whether the message payload size exceeds the limit:
- Message Channel single message package is less than 32 KB.
- Stream Channel single message package is less than 1 KB. | -| `-11011` | RTM_ERROR_CHANNEL_INVALID_USER_LIST | Invalid user list:
- Check if the user list is empty
- Check if the user list contains illegal item. | -| `-11013` | RTM_ERROR_CHANNEL_TOPIC_NOT_SUBSCRIBED | The topic is not subscribed. | -| `-11014` | RTM_ERROR_CHANNEL_EXCEED_TOPIC_LIMITATION | The number of topics exceeds the limit. | -| `-11015` | RTM_ERROR_CHANNEL_JOIN_TOPIC_FAILED | Failed to join this topic. Check whether the number of added topics exceeds the limit. | -| `-11016` | RTM_ERROR_CHANNEL_TOPIC_NOT_JOINED | The topic has not been joined. To send a message without joining the Topic, you need to join the Topic first. | -| `-11017` | RTM_ERROR_CHANNEL_TOPIC_NOT_EXIST | The topic does not exist. Check whether the topic name is wrong. | -| `-11019` | RTM_ERROR_CHANNEL_SUBSCRIBE_TIMEOUT | Channel subscription timed out. Check for broken connections. | -| `-11021` | RTM_ERROR_CHANNEL_SUBSCRIBE_FAILED | Channel subscription failed. Check if the number of subscribed channels exceeds the limit. | -| `-11022` | RTM_ERROR_CHANNEL_UNSUBSCRIBE_FAILED | Failed to unsubscribe from the channel. Check for broken connections. | -| `-11023` | RTM_ERROR_CHANNEL_ENCRYPT_MESSAGE_FAILED | Message encryption failed:
- Check whether the `cipherKey` field is valid.
- Check that the `salt` field is valid.
- Check if `encryptionMode` mode matches `cipherKey`, `salt`. | -| `-11024` | RTM_ERROR_CHANNEL_PUBLISH_MESSAGE_FAILED | Message publishing failed. Check for broken connections. | -| `-11026` | RTM_ERROR_CHANNEL_PUBLISH_MESSAGE_TIMEOUT | Message publishing timed out. Check for broken connections. | -| `-11028` | RTM_ERROR_CHANNEL_LEAVE_FAILED | Failed to leave the channel. Check for broken connections. | -| `-11029` | RTM_ERROR_CHANNEL_CUSTOM_TYPE_LENGTH_OVERFLOW | Custom type length overflow. The length of the `customType` field needs to be within 32 characters. | -| `-11030` | RTM_ERROR_CHANNEL_INVALID_CUSTOM_TYPE | `customType` field is invalid. Check the `customType` field for illegal characters. | -| `-12001` | RTM_ERROR_STORAGE_OPERATION_FAILED | Storage operation failed. | -| `-12002` | RTM_ERROR_STORAGE_METADATA_ITEM_EXCEED_LIMITATION | The number of Storage Metadata Items exceeds the limit. | -| `-12003` | RTM_ERROR_STORAGE_INVALID_METADATA_ITEM | Invalid Metadata Item。 | -| `-12004` | RTM_ERROR_STORAGE_INVALID_ARGUMENT | Invalid argument. | -| `-12005` | RTM_ERROR_STORAGE_INVALID_REVISION | Invalid Revision parameter. | -| `-12006` | RTM_ERROR_STORAGE_METADATA_LENGTH_OVERFLOW | Metadata length overflow. | -| `-12007` | RTM_ERROR_STORAGE_INVALID_LOCK_NAME | Invalid Lock name. | -| `-12008` | RTM_ERROR_STORAGE_LOCK_NOT_ACQUIRED | The Lock was not acquired. | -| `-12009` | RTM_ERROR_STORAGE_INVALID_KEY | Invalid Metadata key. | -| `-12010` | RTM_ERROR_STORAGE_INVALID_VALUE | Invalid Metadata value. | -| `-12011` | RTM_ERROR_STORAGE_KEY_LENGTH_OVERFLOW | Metadata key length overflow. | -| `-12012` | RTM_ERROR_STORAGE_VALUE_LENGTH_OVERFLOW | Metadata value length overflow. | -| `-12014` | RTM_ERROR_STORAGE_OUTDATED_REVISION | Outdated Revision parameter. | -| `-12015` | RTM_ERROR_STORAGE_NOT_SUBSCRIBE | This channel is not subscribed. | -| `-12017` | RTM_ERROR_STORAGE_SUBSCRIBE_USER_EXCEED_LIMITATION | The number of subscriber Metadata exceeds the limit. | -| `-12018` | RTM_ERROR_STORAGE_OPERATION_TIMEOUT | Storage operation timed out. | -| `-12019` | RTM_ERROR_STORAGE_NOT_AVAILABLE | The Storage service is not available. | -| `-13001` | RTM_ERROR_PRESENCE_NOT_CONNECTED | The user is not connected to the system. | -| `-13002` | RTM_ERROR_PRESENCE_NOT_WRITABLE | Presence Service is unavailable. | -| `-13003` | RTM_ERROR_PRESENCE_INVALID_ARGUMENT | Invalid argument. | -| `-13004` | RTM_ERROR_PRESENCE_CACHED_TOO_MANY_STATES | The temporary user state cached before joining the channel exceeds the limit. See API usage limits for details. | -| `-13005` | RTM_ERROR_PRESENCE_STATE_COUNT_OVERFLOW | The number of temporary user state key/value pairs exceeds the limit. See API usage limits for details. | -| `-13006` | RTM_ERROR_PRESENCE_INVALID_STATE_KEY | Invalid state key. | -| `-13007` | RTM_ERROR_PRESENCE_INVALID_STATE_VALUE | Invalid state value. | -| `-13008` | RTM_ERROR_PRESENCE_STATE_KEY_SIZE_OVERFLOW | Presence key length overflow. | -| `-13009` | RTM_ERROR_PRESENCE_STATE_VALUE_SIZE_OVERFLOW | presence value overflow | -| `-13011` | RTM_ERROR_PRESENCE_USER_NOT_EXIST | The user does not exist. | -| `-13012` | RTM_ERROR_PRESENCE_OPERATION_TIMEOUT | Presence operation timed out. | -| `-13013` | RTM_ERROR_PRESENCE_OPERATION_FAILED | Presence operation failed. | -| `-14001` | RTM_ERROR_LOCK_OPERATION_FAILED | Lock operation failed. | -| `-14002` | RTM_ERROR_LOCK_OPERATION_TIMEOUT | Lock operation timed out. | -| `-14003` | RTM_ERROR_LOCK_OPERATION_PERFORMING | Lock operation in progress. | -| `-14004` | RTM_ERROR_LOCK_ALREADY_EXIST | Lock already exists. | -| `-14005` | RTM_ERROR_LOCK_INVALID_NAME | Invalid Lock name. | -| `-14006` | RTM_ERROR_LOCK_NOT_ACQUIRED | The Lock was not acquired. | -| `-14007` | RTM_ERROR_LOCK_ACQUIRE_FAILED | Failed to acquire the Lock. | -| `-14008` | RTM_ERROR_LOCK_NOT_EXIST | The Lock does not exist. | -| `-14009` | RTM_ERROR_LOCK_NOT_AVAILABLE | Lock service is not available. | - - - +``` \ No newline at end of file diff --git a/shared/signaling/reference/index.mdx b/shared/signaling/reference/index.mdx deleted file mode 100644 index 47d8fe822..000000000 --- a/shared/signaling/reference/index.mdx +++ /dev/null @@ -1,3 +0,0 @@ -import Web from './web.mdx'; - - diff --git a/shared/signaling/release-notes/android.mdx b/shared/signaling/release-notes/android.mdx new file mode 100644 index 000000000..f794e64ae --- /dev/null +++ b/shared/signaling/release-notes/android.mdx @@ -0,0 +1,754 @@ + +This page contains information on the following releases: + +## v1.6.0 + +v1.6.0 was released on February 12, 2023. + +#### New features + +**User and channel metadata** + +This release adds easy-to-use, serverless storage for user and channel metadata. +You can store any custom attribute, for example, user name or nickname, as metadata. Signaling SDK +generates events when the metadata associated with a particular user or channel is set or deleted. + +#### API changes + +**Added** + +- `addLocalUserMetadata`: Adds to the local user’s metadata. +- `updateLocalUserMetadata`: Updates the local user’s metadata. +- `deleteLocalUserMetadata`: Deletes the local user’s metadata. +- `setLocalUserMetadata`: Sets the local user’s metadata. +- `clearLocalUserMetadata`: Deletes all local user’s metadata. +- `getUserMetadata`: Gets the metadata of a specified user. +- `subscribeUserMetadata`: Subscribes to metadata update events of a specific user. +- `unsubscribeUserMetadata`: Unsubscribes from metadata update events of a specific user. +- `onUserMetadataUpdated`: Occurs when a user's metadata is updated. +- `addChannelMetadata`: Adds to channel metadata. +- `updateChannelMetadata`: Updates channel metadata. +- `deleteChannelMetadata`: Deletes channel metadata. +- `setChannelMetadata`: Sets channel metadata. +- `clearChannelMetadata`: Deletes channel metadata. +- `getChannelMetadata`: Gets the metadata of a specified channel. +- `onMetadataUpdated`: Occurs when channel metadata is updated. + +## v1.5.3 + +v1.5.3 was released on October 17, 2022. In this release, OpenSSL is upgraded to v1.1.1q. + + +## v1.5.2 + +v1.5.2 was released on October 12, 2022 and improves the stability of the SDK. + + +## v1.5.1 + +v1.5.1 was released on September 1, 2022 and improved the stability of the SDK. + + +## v1.5.0 +v1.5.0 was released on July 27, 2022. + +#### Sunset features +Image or file messages, historical messages, and offline messages are deprecated as of this release. If you have integrated these features in a previous release, you can continue to use them. + +#### API changes + + +The following methods are deprecated: + +- createFileMessageByMediaId +- createFileMessageByUploading +- createImageMessageByMediaId +- createImageMessageByUploading +- cancelMediaUpload +- cancelMediaDownload +- downloadMediaToFile +- downloadMediaToMemory +- onFileMessageReceived +- onFileMessageReceivedFromPeer +- onImageMessageReceived +- onImageMessageReceivedFromPeer +- onMediaUploadingProgress +- onMediaDownloadingProgress +- enableOfflineMessaging +- enableHistoricalMessaging + +## v1.4.10 + +v1.4.10 was released on March 01, 2022. + +#### Compatibility changes + +As of v1.4.10, You don’t need to add the following permission to the `AndroidManifest.xml` file of an Android project: + +``` java + +``` + +#### Issues fixed + +Fixed some rich media related crashes. + +## v1.4.9 + +v1.4.9 was released on November 19, 2021. + +#### Compatibility changes + +- As of v1.4.9, you can automatically integrate the Agora Android SDK through Maven Central. To integrate the SDK with Maven Central, see [Integrate the SDK](../get-started/get-started-sdk). + +- As of v1.4.9, you need to add the following permission to the `AndroidManifest.xml` file of an Android project to check the connection status of the WIFI network: + +#### Improvements + +Improved the login success rate and connection stability under the IPv4/IPv6 dual-stack network. + +## v1.4.7 + +v1.4.7 was released on July 19, 2021. + +Improved the success rate of logins and message delivery for the in poor network conditions. + +## v1.4.6 + +v1.4.6 was released on June 21, 2021. + +Fixed some issues that may cause crashes to improve stability. + +## v1.4.5 + +v1.4.5 was released on April 30, 2021. + +#### Improvements + +Fixed some issues that may cause crashes to improve stability. + +## v1.4.4 + +v1.4.4 was released on April 20, 2021. + +#### Compatibility changes + +**Integration changes** + +Because JCenter is about to retire, as of this release, Agora publishes the SDK package to JitPack instead of JCenter. To integrate the SDK with JitPack, see [Integrate the SDK](../get-started/get-started-sdk). + +#### Improvements + +Improved the success rate of logins and message delivery for the in poor network conditions. + +#### Issues fixed + +Fixed some issues that might cause the system to crash. + +## v1.4.3 + +v1.4.3 was released on February 10, 2021. + +#### Issues fixed + +This release fixed the following issues: + +- Crash issues caused by occasional multi-thread access conflict. + +- High timeout rate for login operations. + +## v1.4.2 + +v1.4.2 was released on November 23, 2020. + +#### Improvements + +Improved performance of login and messaging operations. + +## v1.4.1 + +v1.4.1 was released on September 30, 2020. + +#### Improvements + +Improved the log file. + +## v1.4.0 + +v1.4.0 was released on September 1, 2020. + +#### Compatibility changes + +- You need to add new ports to the firewall whitelist. See [Firewall Requirements](../reference/firewall). + + - New TCP ports: 8443, 9136, 9137, 9141. New UDP port: 8443. Reason: Support real-time transport encryption. + + - New UDP ports: 8130, 9120, 9121. Reason: Support UDP path to improve the SDK’s performance in sub-optimal network conditions. + + - New UDP port: 9700. Reason: Support data reporting. + +- In `setLogFileSize`, the default log file size increases from 512 KB to 10 MB. The maximum log file size increases from 10 MB to 1 GB. + +#### New features + +- Geofencing. You can call `setRtmServiceContext` to set the region of the Agora . The can only connect to Agora servers within the specified region. + +- Transport encryption. The encryption is enabled by default. To disable the feature, contact support@agora.io. + +#### Improvements + +- Improved the success rate of login and message delivery of the in poor network conditions. + +- Optimized the reconnection mechanism. + +#### API changes + +**New methods** + +setRtmServiceContext + +## v1.3.0 + +v1.3.0 was released on May 8, 2020. + +#### Compatibility changes + +- You need to add a new TCP port, 9140, to the firewall whitelist. The port is for sending and receiving image or file messages. See [Firewall Requirements](../reference/firewall). + +- The Agora server blocks any file message or image message that you send to 1.2.2 or earlier, or to the Signaling SDK. + +#### New features + +1. Send and receive file messages + + v1.3.0 supports downloading non-empty files that are smaller than 30 MB. You can cancel an ongoing upload or download process at any time. Each file you upload to the Agora server corresponds to a media ID. The file stays on the Agora server for seven days. You can use the media ID to download the file as long as the file is still on the Agora server. + + v1.3.0 adds the `RtmFileMessage` message class for saving and transferring a media ID. The `RtmFileMessage` class inherits from the `RtmMessage` class, so you can use the existing peer-to-peer or channel messaging methods to transfer the `RtmFileMessage` instance. You can use the `RtmFileMessage` object to complete the following tasks: + + - Set the filename and thumbnail of the uploaded file. + + - Get the size of the uploaded file. + +2. Send and receive image messages + + v1.3.0 supports downloading non-empty image files that are smaller than 30 MB. You can cancel an ongoing upload or download process at any time. Each image you upload to the Agora server corresponds to a media ID. The image file stays in the Agora server for seven days. You can use the media ID to download the image file as long as it is still on the Agora server. + + v1.3.0 adds the `RtmImageMessage` message class for saving and transferring a media ID. The `RtmImageMessage` class inherits from the `RtmMessage` class, so you can use the existing peer-to-peer or channel messaging methods to transfer the `RtmImageMessage` instance. You can use the `RtmImageMessage` object to complete the following tasks: + + - Set the filename and thumbnail of the uploaded image file. + + - Get the size of the uploaded image file. + + - Get the SDK-calculated width or height of image files in JPEG, JPG, BMP, or PNG format. + + - Set the width or height of image files. The width or height you set overwrites the width or height that the SDK calculates. + +3. Report the progress of upload or download + + The SDK returns the progress of an upload or download by callback every second during a task in progress. If the upload or download task pauses, the SDK ceases to return any further callback until the task continues. + +#### Bug fixes + +- Login failure caused by the SDK’s incorrect identification of user’s network type. + +- Other problems that may cause the system to crash. + +#### API changes + +**New methods** + +- createFileMessageByMediaId +- createImageMessageByMediaId +- createFileMessageByUploading +- createImageMessageByUploading +- downloadMediaToMemory +- downloadMediaToFile +- cancelMediaUpload +- cancelMediaDownload + +**New callbacks** +- onImageMessageReceived +- onFileMessageReceived +- onImageMessageReceivedFromPeer +- onFileMessageReceivedFromPeer +- onMediaUploadingProgress +- onMediaDownloadingProgress + +**Deprecated methods** +- sendMessage (RtmMessage message, ResultCallback\ resultCallback) is deprecated. Use sendMessage (RtmMessage message instead. + +## v1.2.2 + +v1.2.2 was released on December 13, 2019. + +**Issues Fixed** + +Occasionally fails to receive any callback after a channel attribute operation. + +## v1.2.1 + +v1.2.1 was released on November 29, 2019. + +**New Feature** + +*Compatible with the endCall method of the Agora Signaling SDK* + +If you use the `sendMessageToPeer` method to send a text message in the format of AgoraRTMLegacyEndcallCompatibleMessagePrefix_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore) in your additional information but you can set \ as empty "". + +**Issues Fixed** + +- The SDK fails to reconnect to the Agora system if the user disables VPN. + +- If a channel member reconnects to the Agora server after being interrupted, chances are the rest members of the channel can receive `onMemberJoined` twice. + +## v1.2.0 + +v1.2.0 was released on November 6, 2019. + +**New Features** + +#### Subscribe to the online status of the specified user(s) + +When the method call succeeds, the SDK returns the onPeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe. +When the online status of the peers, to whom you subscribe, changes, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed. +If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server. + +#### Unsubscribe from the online status of the specified user(s) + +Allows you to unsubscribe from the online status of the specified user(s). + +#### Get a list of the peers, to whose specific status you have subscribed + +Allows you to get a list of the peers, to whose specific status you have subscribed. + +#### Create a raw message + +Creates and initializes a raw message to be sent. + +If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB. + +**Issues Fixed** + +- The system returns `rtm native not ready`, if one creates multiple channels with the same `channelId` and then calls `join` or `leave`. + +## v1.1.0 + +v1.1.0 is released on September 18, 2019. It adds the following features: + +- Gets the member count of specified channel(s). + +- Automatically returns the latest numer of members in the current channel + +- Channel attribute operations + +**Compatibility Changes** + +1. Deprecates the sendMessageToPeer method, and uses sendMessageToPeer(const char \*, const IMessage \*, const SendMessageOptions &) instead. + +2. The getServerReceivedTs method of the RtmMessage object supports both peer-to-peer and channel messages. + +3. Timeout for sending a peer-to-peer message is 10 seconds from this release, compared to 5 seconds in previous versions. See PEER_MESSAGE_ERR_TIMEOUT. + +4. Puts a limit on the frequency of join the same channel: Two times every five seconds. + +**New Features** + +1. Gets the member count of specified channel(s). + + You can now get the member count of specified channel(s) without the need to join, by calling the getChannelMemberCount method. You can get the member counts of a maximum of 32 channels in one method call. + +2. Automatically returns the latest numer of members in the current channel + + If you are already in a channel, you do not have to call the `getChannelMemberCount` method to get the member count of the current channel. We also do not recommend using `onMemberJoined` and `onMemberLeft` to keep track of the member counts. As of this release, the SDK returns to the channel members onMemberCountUpdated the latest channel member count when the number of channel members changes. Note that: + + - When the number of channel members ≤ 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once per second. + + - When the number of channel members exceeds 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once every three seconds. + + Please treat this callback and the getMembers method separately: + + - The former is an active callback. It returns the current numer of channel members; + + - The latter relies on the onSuccess callback to return a member list of the current channel. If the number of channel members exceeds 512, the SDK only returns a list of 512 randomly-selected channel members. + +3. Channel attribute operations + + Supports setting or getting the attribute(s) of a specified channel. You can use this feature to create group anouncement. + + Each channel attribute comes as a key-value pair. See RtmChannelAttribute for more information. Where: + + - The key of each channel attribute must be visible characters and not exceed 8 KB. + + - Each channel attribute must not exceed 8 KB in length. + + - The overall size of the attributes of a channel must not exceed 32 KB. + + - The number of attributes of a channel must not exceed 32. + + Specific features: + + - Sets the attributes of a specified channel with new ones. + + - Adds or updates the attribute(s) of a specified channel. + + - Deletes the attributes of a specified channel by attribute keys. + + - Clears all attributes of a specified channel. + + - Gets all attributes of a specified channel. + + - Gets the attributes of a specified channel by attribute keys. + + When updating attributes of a channel, you can use the setEnableNotificationToChannelMembers flag to decide whether or not to notify all members of the channel about this attribute change. + + The SDK caches the channel attributes. If multiple users have the privilege to update the channel attributes, then we recommend calling the getChannelAttributes to update the cache before updating the channel attributes. + +**Improvements** + +#### Resends peer-to-peer messages + +This release improves the resending mechanism of peer-to-peer messages, and extends the timeout for sending a peer-to-peer message from five to 10 seconds, greatly improving the success rate of peer-to-peer message sending under weak network conditions. + +#### Caches channel messages + +The Agora system will resend a maximum of 32 channel messages of up to 30 seconds to channel members, when they manage to reconnect to the system from poor network conditions. This greatly improves the overall arrival rate of channel messages under weak network conditions. + +**API Changes** + +#### Added Methods + +- setChannelAttributes: Sets the attributes of a specified channel with new ones. + +- addOrUpdaeChannelAttributes: Adds or updates the attribute(s) of a specified channel. + +- deleteChannelAttributesByKeys: Deletes the attributes of a specified channel by attribute keys. + +- clearChannelAttributes: Clears all attributes of a specified channel. + +- getChannelAttributes: Gets all attributes of a specified channel. + +- getChannelAttributesByKeys : Gets the attributes of a specified channel by attribute keys. + +- getChannelMemberCount : Gets the member count of specified channel(s). + +#### Added Callbacks + +- onAttributesUpdated: Returns all attributes of the channel when the channel attributes are updated. + +- onMemberCountUpdated : Occurs when the number of the channel members changes, and returns the new number. + +#### Added Error Codes + +- GetChannelMemberCountErrCode : Error codes related to retrieving the channel member count of specified channel(s). + +- JOIN_CHANNEL_ERR_JOIN_SAME_CHANNEL_TOO_OFTEN : The frequency of joining the same channel exceeds two times every five seconds. + +#### Deprecated Methods + +- sendMessageToPeer: Replaced by the sendMessageToPeer(const char \*, const IMessage \*, const SendMessageOptions &) method. + +#### Deprecated Error Codes + +- ATTRIBUTE_OPERATION_ERR_NOT_READY: Replaced by ATTRIBUTE_OPERATION_ERR_USER_NOT_LOGGED_IN. + +## v1.0.1 + +v1.0.1 is released on August 1st, 2019. + +**Issues Fixed** + +- When the connection to the Agora system is interrupted, the SDK does not return the `onConnectionStateChanged` callback. + +## v1.0.0 + +v1.0.0 is released on July 24th, 2019. + +**New Features** + +#### Interconnects with the legacy Agora Signaling SDK + +v1.0.0 implements the `LocalInvitation.setChannelId` and `LocalInvitation.getChannelId` methods. + +- To intercommunicate with the legacy Agora Signaling SDK, you MUST set the channel ID. However, even if the callee successfully accepts the call invitation, the Agora does not join the channel of the specified channel ID. + +- If your App does not involve the legacy Agora Signaling SDK, we recommend using the `LocalInvitation.setContent` method or the `RemoteInvitation.setResponse` method to set customized contents. + +#### Specifies the default path to the SDK log file + +Supports changing the default path to the SDK log file using the `setLogFile` method. To avoid creating an incomplete log file, we recommend calling this method once you have created and initialized an `RtmClient` instance. + +#### Sets the output log level of the SDK + +Supports setting the output log level of the SDK using the `setLogFilter` method. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING. + +You can call this method once you have created and initializd an `RtmClient` instance. You do not have to call this method after calling the `login` method. + +#### Sets the log file size in KB + +Supports setting the log file size using the `setLogFileSize` method. The log file has a default size of 512 KB. File size settings of less than 512 KB or greater than 10 MB will not take effect. + +You can call this method once you have created and initializd an `RtmClient` instance. You do not have to call this method after calling the `login` method. + +**Improvements** + +Adds error codes based on the following scenarios: + +- The Agora service is not initialized. + +- The method call frequency exceeds the limit. + +- The user does not call the `login` method or the method call of `login` does not succeed before calling any of the core APIs. + +**Issues Fixed** + +- One can log in the Agora system with a static App ID and an token, which is generated from a dynamic App ID. + +**API Changes** + +- setLogFile: Specifies the default path to the SDK log file. + +- setLogFilter: Sets the output log level of the SDK. + +- setLogFileSize: Sets the log file size in KB. + +- getSdkVersion : Gets the SDK version. + +## v0.9.3 + +v0.9.3 was released on June 7th, 2019. + +**New Features** + +#### Sends an (offline) peer-to-peer message to a specified user (receiver) + +This version allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one. + +#### User attribute-related operations + +This version allows you to set or update a user’s attributes. You can: + +- Substitutes the local user’s attributes with new ones. + +- Adds or updates the local user’s attribute(s). + +- Deletes the local user’s attributes using attribute keys. + +- Clears all attributes of the local user. + +- Gets all attributes of a specified user. + +- Gets the attributes of a specified user using attribute keys. + +Please note that: + +- Only after you successfully loggin in the Agora system can you execute user attribute-related operations. Otherwise, the SDK triggers the `ATTRIBUTE_OPERATION_ERR_NOT_READY` error code. + +- The attributes you set will be clears when you log out of . + +- You can only set a maximum of 16 KB attributes in a single method call. Otherwise, the SDK triggers the `ATTRIBUTE_OPERATION_ERR_SIZE_OVERFLOW` error code. + +**Improvements** + +- Supports creating an channel before logging in the Agora system. + +- Supports creating multiple channels. But a user can only join a maximum of 20 channels at the same time. When the number of the joined channels exceeds 20, the SDK triggers the `JOIN_CHANNEL_ERR_FAILURE` error code. + +**Issues Fixed** + +- Occasional system crashes. + +- A user who has logged out of the Agora system appears online to the other users until 30 seconds later. + +## v0.9.2 + +v0.9.2 is released on May 5th, 2019. + +This release does not support creating an RtmChannel instance before logging in the Agora system + +**New Features** + +#### Queries the Online Status of the Specified Users + +This release introduces a new concept: online and offline. + +- Online: The user has logged in the Agora system. + +- Offline: The user has logged out of the Agora system. + +This release adds the function of querying the online status of the specified users. After logging in the Agora system, you can get the online status of a maximum of 256 specified users. See queryPeersOnlineStatus. + +Please note that: + +- The sequence of the returned user IDs is identical to the input sequence. + +- The call frequency of this method is 10 times every five seconds. + +#### Renews the Token + +In the production environment, you need to use a token to log in the Agora system. Each token expires 24 hours after it is created. This release allows you to renew a token. + +- If you are logging in the Agora system and if your token has expired, the SDK returns the LOGIN_ERR_TOKEN_EXPIRED error code. + +- if you are logged in the Agora system, you will not be kicked out immediately when your token expires. But you need to renew your token the next time you log in the Agora system. Therefore, we still recommend that you renew your token when you receive the onTokenExpired callback. + +Please note that: + +- The renewToken method must be called before creating an RtmClient. + +- The call frequency of the renewToken method is two times every second. + +**Improvements** + +- Supports a `userId` that starts with a space. + +**API Changes** + +#### Queries the Online Status of the Specified Users + +#### Adds + +- Method: queryPeersOnlineStatus + +- Error Code: QueryPeersOnlineStatusError + +#### Renews the Token + +#### Adds + +- Method: renewToken + +- Callback: onTokenExpired + +- Error Codes: + +- RenewTokenError + +#### Call Invitation + +Adds the following error code for when a user sends a call invitation without logging in the Agora system. + +- LOCAL_INVITATION_ERR_NOT_LOGGEDIN + +## v0.9.1 + +v0.9.1 is released on April 4th, 2019. + +Please note that this version does not come with the `setLogFile` and `setLogFilter` method. The default log file location is at **/sdcard/\/agorartm.log**. + +**New Features** + +This release adds the call invitation feature, allowing you to create, send, cancel, accept, and decline a call invitation in a one-to-one or one-to-many voice/video call. + +**Improvements** + +- Optimizes the object relations to facilitate understanding. + +- Renames some interfaces to conform to Java naming conventions. + +- Removes `ChannelMessageState` and `PeerMessageState` to simplify the process of sending a channel or peer-to-peer message. Uses `ChannelMessageError` and `PeerMessageError` instead. + +- Removes `IStateListener` for listening to message states. Uses the generic `ResultCallback` instead. + +**API Changes** + +#### Adds + +- LocalInvitation.setContent(): allows the caller to set the content of an outgoing call invitation. + +- LocalInvitation.getContent(): allows the caller to retrieve the content of an outgoing call invitation. + +- LocalInvitation.getResponse(): allows the caller to retrieve the response set by the callee. + +- LocalInvitation.getState(): allows the caller to retrieve the state of an outgoing call invitation. + +- RemoteInvitation.getCallerId() : allows the callee to retrieve the user ID of the caller. + +- RemoteInvitation.getContent() : allows the callee to retrieve the content set by the caller. + +- RemoteInvitation.setResponse(): allows the callee to set the response to the caller. + +- RemoteInvitation.getResponse(): allows the callee to retrieve the response to the caller. + +- RemoteInvitation.getState(): allows the callee to retrieve the state of the incoming call invitation + +- RtmCallEventListener.onLocalInvitationReceivedByPeer(): occurs when the callee receives the call invitation. + +- RtmCallEventListener.onLocalInvitationAccepted(): occurs when the callee accepts the call invitation. + +- RtmCallEventListener.onLocalInvitationRefused(): occurs when the callee declines the call invitation. + +- RtmCallEventListener.onLocalInvitationCanceled(): occurs when the caller cancels the call invitation. + +- RtmCallEventListener.onLocalInvitationFailure(): occurs when the outgoing call invitation fails. + +- RtmCallEventListener.onRemoteInvitationReceived(): occurs when the callee receives a call invitation. + +- RtmCallEventListener.onRemoteInvitationAccepted(): occurs when the callee accepts a call invitation. + +- RtmCallEventListener.onRemoteInvitationRefused(): occurs when the callee declines a call invitation. + +- RtmCallEventListener.onRemoteInvitationCanceled(): occurs when the caller cancels the call invitation. + +- RtmCallEventListener.onRemoteInvitationFailure(): occurs when the incoming call invitation fails. + +- RtmCallManager.setEventListener(): sets the event listener to the `RtmCallManager` instance. + +- RtmCallManager.createLocalInvitation(): creates a call invitation. + +- RtmCallManager.sendLocalInvitation(): sends a call invitation to a specified user. + +- RtmCallManager.acceptRemoteInvitation() : accepts an incoming call invitation. + +- RtmCallManager.refuseRemoteInvitation(): declines an incoming call invitation. + +- RtmCallManager.cancelLocalInvitation(): allows the caller to cancel an outgoing call invitation. + +- RtmStatusCode#LocalInvitationState: states of an outgoing call invitation. + +- RtmStatusCode#RemoteInvitationState : states of an incoming call invitation. + +- RtmStatusCode#LocalInvitationError: error codes of an outgoing call invitation. + +- RtmStatusCode#RemoteInvitationError: error codes of an incoming call invitation. + +- RtmStatusCode#InvitationApiCallError: error codes of the invitation-specific API calls. + +- ConnectionChangeReason#CONNECTION_CHANGE_REASON_REMOTE_LOGIN: another instance has logged in the Agora system with the same user ID. + +#### Renames + +- The `RtmClient.destroy()` method, which releases all resources used by the `RtmClient` instance, to: RtmClient.release(). + +- The `IResultCallback` class to: ResultCallback + +#### Deletes + +- Deletes `PEER_MESSAGE_RECEIVED_BY_SERVER` from PeerMessageError, uses `PEER_MESSAGE_ERR_OK` instead. + +- Deletes `CHANNEL_MESSAGE_RECEIVED_BY_SERVER` from ChannelMessageError, uses `CHANNEL_MESSAGE_OK` instead. + +- Deletes the `PeerMessageState` interface, uses PeerMessageError instead. + +- Deletes the `ChannelMessageState` interface, uses ChannelMessageError instead. + +- Deletes the `IStateListener` class for listening to message states, uses the ResultCallback class instead for listening to the peer or channel message results. + +- Success: the SDK returns the ResultCallback.onSuccess() callback. + +- Failure: the SDK returns the ResultCallback.onFailure() callback with the corresponding error codes. + +## v0.9.0 + +v0.9.0 is released on February 4th, 2019. + +Initial version. + +Key features: + +- Sends or receives peer-to-peer messages. + +- Joins or leaves a channel. + +- Sends or receives channel messages. + + diff --git a/shared/signaling/release-notes/cocos-creator.mdx b/shared/signaling/release-notes/cocos-creator.mdx new file mode 100644 index 000000000..1074f4db7 --- /dev/null +++ b/shared/signaling/release-notes/cocos-creator.mdx @@ -0,0 +1,4 @@ + + + + diff --git a/shared/signaling/release-notes/cpp.mdx b/shared/signaling/release-notes/cpp.mdx new file mode 100644 index 000000000..a07144582 --- /dev/null +++ b/shared/signaling/release-notes/cpp.mdx @@ -0,0 +1,533 @@ + + + +## v1.5.1 + +v1.5.1 was released on September 1, 2022 and improved the stability of the SDK. + + +### v1.5.0 +v1.5.0 was released on July 27, 2022. + +#### Sunset features +Image or file messages, historical messages, and offline messages are deprecated as of this release. If you have integrated these features in a previous release, you can continue to use them. + +#### API changes + +The following methods are deprecated: + +- createFileMessageByMediaId +- createFileMessageByUploading +- createImageMessageByMediaId +- createImageMessageByUploading +- cancelMediaUpload +- cancelMediaDownload +- downloadMediaToMemory +- downloadMediaToFile +- enableOfflineMessaging +- enableHistoricalMessaging +- onFileMessageReceived +- onFileMessageReceivedFromPeer +- onImageMessageReceived +- onImageMessageReceivedFromPeer +- onMediaUploadingProgress +- onMediaDownloadingProgress + +### v1.4.10 +v1.4.10 was released on March 01, 2022. + +#### Issues fixed + +Fixed some rich media related crashes. + +### v1.4.9 +v1.4.9 was released on November 26, 2021. + +#### Improvements + +Improved the login success rate and connection stability under the IPv4/IPv6 dual-stack network. + +### v1.4.7 +v1.4.7 was released on July 19, 2021. + +Improved the success rate of logins and message delivery for the in poor network conditions. + +### v1.4.6 + +v1.4.6 was released on June 21, 2021. + +Fixed some issues that may cause crashes to improve stability. + +### v1.4.5 + +v1.4.5 was released on April 30, 2021. + +#### Improvements + +Fixed some issues that may cause crashes to improve stability. + +### v1.4.4 + +v1.4.4 was released on April 20, 2021. + +#### Improvements + +Improved the success rate of logins and message delivery for the in poor network conditions. + +#### Issues fixed + +Fixed some issues that might cause the system to crash. + +### v1.4.3 + +v1.4.3 was released on February 10, 2021. + +#### Issues fixed + +This release fixed the following issues: + +- Crash issues caused by occasional multi-thread access conflict. +- High timeout rate for login operations. + +### v1.4.2 + +v1.4.2 was released on November 23, 2020. + +**Compatibility changes** + +- For CentOS, v1.4.2 does not support CentOS 7 or earlier. If your CentOS is 7 or earlier, Agora recommends that you use v1.4.1. +- In `setLogFileSize`, the default log file size increases from 10 MB to 100 MB. + +**Improvements** + +- Improved the performance of login and messaging operations. +- Added the `AGORA_SDK_BOTH_RTM_AND_RTC` macro for the `RTM_AREA_CODE` enum type. You can use the macro to resolve naming conflicts when using and together. + +### v1.4.1 + +v1.4.1 was released on September 30, 2020. + +**Improvements** + +Improved the log file. + + +### v1.4.0 + +v1.4.0 was released on September 1, 2020. + +**Compatibility changes** + +- You need to add new ports to the firewall whitelist. See [Firewall Requirements](../reference/firewall). + - New TCP ports: 8443, 9136, 9137, 9141. New UDP port: 8443. Reason: Support real-time transport encryption. + - New UDP ports: 8130, 9120, 9121. Reason: Support UDP path to improve the SDK's performance in sub-optimal network conditions. + - New UDP port: 9700. Reason: Support data reporting. +- In `setLogFileSize`, the default log file size increases from 512 KB to 10 MB. The maximum log file size increases from 10 MB to 1 GB. + +**New features** + +- Geofencing. You can call `setRtmServiceContext` to set the region of the Agora . The can only connect to Agora servers within the specified region. +- Transport Layer Security (TLS) encryption. + +**Improvements** + +- Improved the success rate of login and message delivery of the in poor network conditions. +- The call frequency limit has increased for the following operations. See [Limitations](../reference/limitations). + +| Operation | Call frequency limit change | +| :---------------------------------------- | :----------------------------------------------------------- | +| Send peer-to-peer or channel messages | Increased from 300 calls every three seconds to 1,500 calls every three seconds | +| Query user online status | Increased from 20 calls every five seconds to 100 calls every five seconds | +| Add, delete, or update user attributes | Increased from 20 calls every five seconds to 100 calls every five seconds | +| Query user attributes | Increased from 80 calls every five seconds to 400 calls every five seconds | +| Add, delete, or update channel attributes | Increased from 20 calls every five seconds to 100 calls every five seconds | +| Query channel attributes | Increased from 80 calls every five seconds to 400 calls every five seconds | + +- Optimized the reconnection mechanism. + +**API changes** + +#### New methods + +setRtmServiceContext. + +### v1.3.0 + +v1.3.0 was released on June 12. + +**Compatibility changes** + +- You need to add a new TCP port, 9140, to the firewall whitelist. The port is for sending and receiving image or file messages. See [Firewall Requirements](../reference/firewall). +- The Agora server blocks any file message or image message that you send to 1.2.2 or earlier, or to the Signaling SDK. + +**New features** + +#### 1. Send and receive file messages or image messages + +You can call `createFileMessageByUploading` or `createImageMessageByUploading` to upload non-empty files or image files no greater than 30 MB. Each uploaded file or image stays in the Agora server for seven days. The SDK returns a media ID as the unique indentifier of the file or image file. You can use the `IFileMessage` class or the `IImageMessage` class to save the media ID. The `IFileMessage` class and the `IImageMessage` class inherit from the `IMessage` class, so you can send and receive file or image messages via peer-to-peer or channel message methods. You can call `downloadMediaToMemory` or `downloadMediaToFile` to download the received file or image file. + +#### 2. Manage upload or download tasks + +You can call `cancelMediaUpload` or `cancelMediaDownload` to cancel an upload or download task. You also can use the `onMediaUploadingProgress` callback or the `onMediaDownloadingProgress` callback to return upload or download progress. + +**Improvements** + +The call limits of the following operations have increased. See [Limitations](../reference/limitations). + +| Operation | Call limit increase | +| :---------------------------------------- | :----------------------------------------------------------- | +| Send peer-to-peer or channel messages | From 180 calls every three seconds to 300 calls every three seconds | +| Query user online status | From 10 calls every five seconds to 20 calls every five seconds | +| Add, delete, or update user attributes | From 10 calls every five seconds to 20 calls every five seconds | +| Query user attributes | From 40 calls every five seconds to 80 calls every five seconds | +| Add, delete, or update channel attributes | From 10 calls every five seconds to 20 calls every five seconds | +| Query channel attributes | From 10 calls every five seconds to 80 calls every five seconds | + +**Fixed issues** + +- Login failure caused by the SDK's incorrect identification of user's network type. +- Other problems that may cause the system to crash. + +**API changes** + +#### New methods + +- createFileMessageByUploading +- createImageMessageByUploading +- cancelMediaUpload +- cancelMediaDownload +- createFileMessageByMediaId +- createImageMessageByMediaId +- downloadMediaToMemory +- downloadMediaToFile + +#### New callbacks + +- onMediaUploadingProgress +- onMediaDownloadingProgress +- onMediaCancelResult +- onFileMediaUploadResult +- onImageMediaUploadResult +- onFileMessageReceivedFromPeer +- onImageMessageReceivedFromPeer +- onFileMessageReceived +- onImageMessageReceived +- onMediaDownloadToMemoryResult +- onMediaDownloadToFileResult + +#### Deprecated methods + +sendMessage is deprecated. Use sendMessage (const IMessage *message, const SendMessageOptions &options) instead. + +### v1.2.2 + +v1.2.2 was released on December 13, 2019. + + +**Compatibility Changes** + +This release deprecates the createAgoraService method, which creates an IAgoraService instance, and the initialize method, which initializes the created IAgoraService instance. As of this relase, you only need to call the createRtmService method and the initialize method to initialize it before being able to call its functions. + + +**Issues Fixed** + +Occasionally fails to receive any callback after a channel attribute operation. + +### v1.2.1 + +v1.2.1 was released on November 29, 2019. + +**New Feature** + +*Compatible with the endCall method of the Agora Signaling SDK* + +If you use the `sendMessageToPeer` method to send a text message in the format of AgoraRTMLegacyEndcallCompatibleMessagePrefix_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore) in your additional information but you can set \ as empty "". + +**Issues Fixed** + + +- The SDK fails to reconnect to the Agora system if the user disables VPN. +- If a channel member reconnects to the Agora server after being interrupted, chances are the rest members of the channel can receive `onMemberJoined` twice. + +### v1.2.0 + +v1.2.0 was released on November 6, 2019. + +**Compatibility Changes** + +Deprecated the `isOnline` property of the `PeerOnlineStatus`. Use `onlineState` instead. + + +**New Features** + +#### Subscribe to the online status of the specified user(s) + +When the method call succeeds, the SDK returns the onPeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe. +When the online status of the peers, to whom you subscribe, changes, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed. +If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server. + +#### Unsubscribe from the online status of the specified user(s) + +Allows you to unsubscribe from the online status of the specified user(s). + +#### Get a list of the peers, to whose specific status you have subscribed + +Allows you to get a list of the peers, to whose specific status you have subscribed. + +#### Create a raw message + +Creates and initializes a raw message to be sent. + + If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB. + +### v1.1.0 + +v1.1.0 was released on October 14, 2019. It adds the following features: + +- [Gets the member count of specified channel(s).](#getcount) +- [Automatically returns the latest numer of members in the current channel](#oncount) +- [Channel attribute operations](#channelattributes) + + + +**Compatibility Changes** + +1. Deprecates the sendMessageToPeer method, and uses sendMessageToPeer(const char \*, const IMessage \*, const SendMessageOptions \&) instead. +2. The getServerReceivedTs method of the IMessage object supports both peer-to-peer and channel messages. +3. Timeout for sending a peer-to-peer message is 10 seconds from this release, compared to 5 seconds in previous versions. See PEER_MESSAGE_ERR_SENT_TIMEOUT. +4. Puts a limit on the frequency of join the same channel: Two times every five seconds. + +**New Features** + + +#### 1. Gets the member count of specified channel(s). + +You can now get the member count of specified channel(s) without the need to join, by calling the getChannelMemberCount method. You can get the member counts of a maximum of 32 channels in one method call. + + +#### 2. Automatically returns the latest numer of members in the current channel + +If you are already in a channel, you do not have to call the `getChannelMemberCount` method to get the member count of the current channel. We also do not recommend using `onMemberJoined` and `onMemberLeft` to keep track of the member counts. As of this release, the SDK returns to the channel members onMemberCountUpdated the latest channel member count when the number of channel members changes. Note that: + +- When the number of channel members ≤ 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once per second. +- When the number of channel members exceeds 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once every three seconds. + + + +> Please treat this callback and the onGetMembers callback separately: +> - The former is an automatic callback. It returns the current numer of channel members; +> - The latter is triggered by the getMembers method. It returns a member list of the current channel. If the number of channel members exceeds 512, the SDK only returns a list of 512 randomly-selected channel members. + + +#### 3. Channel attribute operations + +Supports setting or getting the attribute(s) of a specified channel. You can use this feature to create group anouncement. + +Each channel attribute comes as a key-value pair. See IRtmChannelAttribute for more information. Where: + +- The key of each channel attribute must be visible characters and not exceed 8 KB. +- Each channel attribute must not exceed 8 KB in length. +- The overall size of the attributes of a channel must not exceed 32 KB. +- The number of attributes of a channel must not exceed 32. + +Specific features: + +- Sets the attributes of a specified channel with new ones. +- Adds or updates the attribute(s) of a specified channel. +- Deletes the attributes of a specified channel by attribute keys. +- Clears all attributes of a specified channel. +- Gets all attributes of a specified channel. +- Gets the attributes of a specified channel by attribute keys. + +When updating attributes of a channel, you can use the enableNotificationToChannelMembers flag to decide whether or not to notify all members of the channel about this attribute change. + +> The SDK caches the channel attributes. If multiple users have the privilege to update the channel attributes, then we recommend calling the getChannelAttributes to update the cache before updating the channel attributes. + +**Improvements** + +#### Resends peer-to-peer messages + +This release improves the resending mechanism of peer-to-peer messages, and extends the timeout for sending a peer-to-peer message from five to 10 seconds, greatly improving the success rate of peer-to-peer message sending under weak network conditions. + +#### Caches channel messages + +The Agora system will resend a maximum of 32 channel messages of up to 30 seconds to channel members, when they manage to reconnect to the system from poor network conditions. This greatly improves the overall arrival rate of channel messages under weak network conditions. + + +**API Changes** + +#### Added Methods + +- createChannelAttribute: Creates and returns an IRtmChannelAttribute instance. +- setChannelAttributes: Substitutes the attributes of a specified channel with new ones. +- addOrUpdaeChannelAttributes: Adds or updates the attribute(s) of a specified channel. +- deleteChannelAttributesByKeys: Deletes the attributes of a specified channel by attribute keys. +- clearChannelAttributes: Clears all attributes of a specified channel. +- getChannelAttributes: Gets all attributes of a specified channel. +- getChannelAttributesByKeys: Gets the attributes of a specified channel by attribute keys. +- getChannelMemberCount: Gets the member count of specified channel(s). + +#### Added Callbacks + +- onSetChannelAttributesResult: Returns the result of the setChannelAttributes method call. +- onAddOrUpdateChannelAttributesResult: Returns the result of the addOrUpdaeChannelAttributes method call. +- onDeleteChannelAttributesResult: Returns the result of the deleteChannelAttributesByKeys method call. +- onClearChannelAttributesResult: Returns the result of the clearChannelAttributes method call. +- onGetChannelAttributesResult: Returns the result of the getChannelAttributes or getChannelAttributesByKeys method call. +- onAttributesUpdated: Returns all attributes of the channel when the channel attributes are updated. +- onGetChannelMemberCountResult: Returns the result of the getChannelMemberCount method call. +- onMemberCountUpdated: Occurs when the number of the channel members changes, and returns the new number. + +#### Added Error Codes + +- GET_CHANNEL_MEMBER_COUNT_ERR_CODE: Error codes related to retrieving the channel member count of specified channel(s). +- JOIN_CHANNEL_ERR_JOIN_SAME_CHANNEL_TOO_OFTEN: The frequency of joining the same channel exceeds two times every five seconds. + +#### Deprecated Methods + +- sendMessageToPeer: Replaced by the sendMessageToPeer method. + +#### Deprecated Error Codes + +- ATTRIBUTE_OPERATION_ERR_NOT_READY: Replaced by ATTRIBUTE_OPERATION_ERR_USER_NOT_LOGGED_IN. + + + + +### v1.0.1 + +v1.0.1 was released on August 1st, 2019. + +**Issues Fixed** + +- When the connection to the Agora system is interrupted, the SDK does not return the `onConnectionStateChanged` callback. + +### v1.0.0 + +v1.0.0 was released on July 24th, 2019. + +**New Features** + +#### Interconnects with the legacy Agora Signaling SDK + +v1.0.0 implements the `ILocalCallinvitation::setChannelId` and `ILocalCallinvitation::getChannelId` methods. + +> - To intercommunicate with the legacy Agora Signaling SDK, you MUST set the channel ID. However, even if the callee successfully accepts the call invitation, the Agora does not join the channel of the specified channel ID. +> - If your App does not involve the legacy Agora Signaling SDK, we recommend using the `ILocalCallInvitation::setContent` method or the `IRemoteCallInvitation::setResponse` method to set customized contents. + +#### Specifies the default path to the SDK log file + +Supports changing the default path to the SDK log file using the `setLogFile` method. To avoid creating an incomplete log file, we recommend calling this method once you have created and initialized an `IRtmService` instance. + + + +#### Sets the output log level of the SDK + +Supports setting the output log level of the SDK using the `setLogFilter` method. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING. See also LOG_FILTER_TYPE. + +> You can call this method once you have created and initializd an `IRtmService` instance. You do not have to call this method after calling the `login` method. + +#### Sets the log file size in KB + +Supports setting the log file size using the `setLogFileSize` method. The log file has a default size of 512 KB. File size settings of less than 512 KB or greater than 10 MB will not take effect. + + +> You can call this method once you have created and initializd an `IRtmService` instance. You do not have to call this method after calling the `login` method. + +**Improvements** + +Adds error codes based on the following scenarios: + +- The Agora service is not initialized. +- The method call frequency exceeds the limit. +- The user does not call the `login` method or the method call of `login` does not succeed before calling any of the core APIs. + +**Issues Fixed** + +- One can log in the Agora system with a static App ID and an token, which is generated from a dynamic App ID. + + +**API Changes** + +- setLogFile: Specifies the default path to the SDK log file. +- setLogFilter: Sets the output log level of the SDK. +- setLogFileSize: Sets the log file size in KB. + + + +### v0.9.3 + +v0.9.3 was released on June 7th, 2019. + +**New Features** + +#### Sends an (offline) peer-to-peer message to a specified user (receiver) + +This version allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one. + + +#### User attribute-related operations + +This version allows you to set or update a user's attributes. You can: + +- Substitutes the local user's attributes with new ones. +- Adds or updates the local user's attribute(s). +- Deletes the local user's attributes using attribute keys. +- Clears all attributes of the local user. +- Gets all attributes of a specified user. +- Gets the attributes of a specified user using attribute keys. + +> - Only after you successfully loggin in the Agora system can you execute user attribute-related operations. Otherwise, the SDK triggers the `ATTRIBUTE_OPERATION_ERR_NOT_READY` error code. +> - The attributes you set will be clears when you log out of the system. +> - You can only set a maximum of 16 KB attributes in a single method call. Otherwise, the SDK triggers the `ATTRIBUTE_OPERATION_ERR_SIZE_OVERFLOW` error code. + +**Improvements** + +- Supports creating an channel before logging in the Agora system. +- Supports creating multiple channels. But a user can only join a maximum of 20 channels at the same time. When the number of the joined channels exceeds 20, the SDK triggers the `JOIN_CHANNEL_ERR_FAILURE` error code. + +**Issues Fixed** + +- Occasional system crashes. +- A user who has logged out of the Agora system appears online to the other users until 30 seconds later. + +### v0.9.2 + +v0.9.2 was released on May 8th, 2019. + +**New Features** + +- Queries the Online Status of the Specified Users. +- Renews the Token. + +**Improvements** + +- Supports a `userId` that starts with a space. + + + + +### v0.9.1 + +v0.9.1 is released on April 4th, 2019. + +**New Features** + +This release adds the call invitation feature, allowing you to create, send, cancel, accept, and decline a call invitation in a one-to-one or one-to-many voice/video call. + + +### v0.9.0 + +v0.9.0 is released on February 4th, 2019. + +Initial version. + +**Key features** + +- Sends or receives peer-to-peer messages. +- Joins or leaves a channel. +- Sends or receives channel messages. + + + + \ No newline at end of file diff --git a/shared/signaling/release-notes/electron.mdx b/shared/signaling/release-notes/electron.mdx new file mode 100644 index 000000000..43851d807 --- /dev/null +++ b/shared/signaling/release-notes/electron.mdx @@ -0,0 +1,4 @@ + + + + diff --git a/shared/signaling/release-notes/flutter.mdx b/shared/signaling/release-notes/flutter.mdx new file mode 100644 index 000000000..0d1f726f5 --- /dev/null +++ b/shared/signaling/release-notes/flutter.mdx @@ -0,0 +1,4 @@ + + + + diff --git a/shared/signaling/release-notes/index.mdx b/shared/signaling/release-notes/index.mdx index e9edf22ec..ab602fe9b 100644 --- a/shared/signaling/release-notes/index.mdx +++ b/shared/signaling/release-notes/index.mdx @@ -1,13 +1,9 @@ +import Android from './android.mdx'; +import Ios from './ios.mdx'; +import Linux from './linux.mdx'; +import Macos from './macos.mdx'; +import Unity from './unity.mdx'; import Web from './web.mdx'; - - -This release is for Web only. - - - - -This page contains information on the following releases: +import Windows from './windows.mdx'; - - diff --git a/shared/signaling/release-notes/ios.mdx b/shared/signaling/release-notes/ios.mdx new file mode 100644 index 000000000..32fa8c746 --- /dev/null +++ b/shared/signaling/release-notes/ios.mdx @@ -0,0 +1,16 @@ +import Text from './oc.mdx'; + + + +This page contains information on the following releases: + + +## Known issues and limitations + +#### Compatibility with iOS 15 + +As of v1.4.6, the SDK supports iOS 15. For the SDK versions v1.4.4 and v1.4.5, crashes occur on iOS 15. To fix this issue, upgrade the SDK to v1.4.6 or later. + + + + \ No newline at end of file diff --git a/shared/signaling/release-notes/java.mdx b/shared/signaling/release-notes/java.mdx new file mode 100644 index 000000000..8ff6242d2 --- /dev/null +++ b/shared/signaling/release-notes/java.mdx @@ -0,0 +1,617 @@ + +## v1.5.1 + +v1.5.1 was released on September 1, 2022 and improved the stability of the SDK. + + +### v1.5.0 + +v1.5.0 was released on July 27, 2022. + +#### Sunset features +Image or file messages, historical messages, and offline messages are deprecated as of this release. If you have integrated these features in a previous release, you can continue to use them. + + +#### API changes + +The following methods are deprecated + +- createFileMessageByMediaId +- createFileMessageByUploading +- createImageMessageByMediaId +- createImageMessageByUploading +- cancelMediaUpload +- cancelMediaDownload +- downloadMediaToFile +- downloadMediaToMemory +- onFileMessageReceived +- onFileMessageReceivedFromPeer +- onImageMessageReceived +- onImageMessageReceivedFromPeer +- onMediaUploadingProgress +- onMediaDownloadingProgress +- enableOfflineMessaging +- enableHistoricalMessaging + + +### v1.4.10 +v1.4.10 was released on March 01, 2022. + +#### Issues fixed + +Fixed some rich media related crashes. + +### v1.4.9 +v1.4.9 was released on November 26, 2021. + +#### Improvements + +Improved the login success rate and connection stability under the IPv4/IPv6 dual-stack network. + +### v1.4.7 +v1.4.7 was released on July 19, 2021. + +Improved the success rate of logins and message delivery for the in poor network conditions. + +### v1.4.6 + +v1.4.6 was released on June 21, 2021. + +Fixed some issues that may cause crashes to improve stability. + +### v1.4.5 + +v1.4.5 was released on April 30, 2021. + +#### Improvements + +Fixed some issues that may cause crashes to improve stability. + +### v1.4.4 + +v1.4.4 was released on April 20, 2021. + +#### Improvements + +Improved the success rate of logins and message delivery for the in poor network conditions. + +#### Issues fixed + +Fixed some issues that might cause the system to crash. + +### v1.4.3 + +v1.4.3 was released on February 10, 2021. + +#### Issues fixed + +This release fixed the following issues: + +- Crash issues caused by occasional multi-thread access conflict. +- High timeout rate for login operations. + +### v1.4.2 + +v1.4.2 was released on November 23, 2020. + +**Compatibility changes** + +- For CentOS, v1.4.2 does not support CentOS 7 or earlier. If your CentOS is 7 or earlier, Agora recommends that you use v1.4.1. +- In `setLogFileSize`, the default log file size increases from 10 MB to 100 MB. + +**Improvements** + +Improved the performance of login and messaging operations. + +**Bug fixes** + +Fixed the issue that `java.lang.UnsatisfiedLinkError: no agora-rtm-sdk-jni in java.library.path` occurred when integrating the v1.4.0 and the v1.4.1 SDK. + +### v1.4.1 + +v1.4.1 was released on September 30, 2020. + +**Improvements** + +Improved the log file. + + +### v1.4.0 + +v1.4.0 was released on September 1, 2020. + +**Compatibility changes** + +- You need to add new ports to the firewall whitelist. See [Firewall Requirements](../reference/firewall). + - New TCP ports: 8443, 9136, 9137, 9141. New UDP port: 8443. Reason: Support real-time transport encryption. + - New UDP ports: 8130, 9120, 9121. Reason: Support UDP path to improve the SDK's performance in sub-optimal network conditions. + - New UDP port: 9700. Reason: Support data reporting. +- In `setLogFileSize`, the default log file size increases from 512 KB to 10 MB. The maximum log file size increases from 10 MB to 1 GB. + +**New features** + +- Geofencing. You can call `setRtmServiceContext` to set the region of the Agora . The can only connect to Agora servers within the specified region. +- Transport Layer Security (TLS) encryption. + +**Improvements** + +- Improved the success rate of login and message delivery of the in poor network conditions. +- The call frequency limit has increased for the following operations. See [Limitations](../reference/limitations). + +| Operation | Call frequency limit change | +| :---------------------------------------- | :----------------------------------------------------------- | +| Send peer-to-peer or channel messages | Increased from 300 calls every three seconds to 1,500 calls every three seconds | +| Query user online status | Increased from 20 calls every five seconds to 100 calls every five seconds | +| Add, delete, or update user attributes | Increased from 20 calls every five seconds to 100 calls every five seconds | +| Query user attributes | Increased from 80 calls every five seconds to 400 calls every five seconds | +| Add, delete, or update channel attributes | Increased from 20 calls every five seconds to 100 calls every five seconds | +| Query channel attributes | Increased from 80 calls every five seconds to 400 calls every five seconds | + +- Optimized the reconnection mechanism. + +**API changes** + +#### New methods + + + +### v1.3.0 + +v1.3.0 was released on June 12. + +**Compatibility changes** + +- You need to add a new TCP port, 9140, to the firewall whitelist. The port is for sending and receiving image or file messages. See [Firewall Requirements](../reference/firewall). +- The Agora server blocks any file message or image message that you send to 1.2.2 or earlier, or to the Signaling SDK. + +**New features** + +#### 1. Send and receive file messages or image messages + +You can call `createFileMessageByUploading` or `createImageMessageByUploading` to upload non-empty files or image files no greater than 30 MB. Each uploaded file or image stays in the Agora server for seven days. The SDK returns a media ID as the unique indentifier of the file or image file. You can use the `RtmFileMessage` class or the `RtmImageMessage` class to save the media ID. The `RtmFileMessage` class and the `RtmImageMessage` class inherit from the `RtmMessage` class, so you can send and receive file or image messages via peer-to-peer or channel message methods. You can call `downloadMediaToMemory` or `downloadMediaToFile` to download the received file or image file. + +#### 2. Manage upload or download tasks + +You can call `cancelMediaUpload` or `cancelMediaDownload` to cancel an upload or download task. You also can use the `onMediaUploadingProgress` callback or the `onMediaDownloadingProgress` callback to return upload or download progress. + +**Improvements** + +The call limits of the following operations have increased. See [Limitations](../reference/limitations). + +| Operation | Call limit increase | +| :---------------------------------------- | :----------------------------------------------------------- | +| Send peer-to-peer or channel messages | From 180 calls every three seconds to 300 calls every three seconds | +| Query user online status | From 10 calls every five seconds to 20 calls every five seconds | +| Add, delete, or update user attributes | From 10 calls every five seconds to 20 calls every five seconds | +| Query user attributes | From 40 calls every five seconds to 80 calls every five seconds | +| Add, delete, or update channel attributes | From 10 calls every five seconds to 20 calls every five seconds | +| Query channel attributes | From 10 calls every five seconds to 80 calls every five seconds | + + +**Fixed issues** + +- Login failure caused by the SDK's incorrect identification of user's network type. +- Other problems that may cause the system to crash. + +**API changes** + +#### New methods + +- createFileMessageByMediaId +- createImageMessageByMediaId +- createFileMessageByUploading +- createImageMessageByUploading +- downloadMediaToMemory +- downloadMediaToFile +- cancelMediaUpload +- cancelMediaDownload + +#### New callbacks + +- onImageMessageReceived +- onFileMessageReceived +- onImageMessageReceivedFromPeer +- onFileMessageReceivedFromPeer +- onMediaUploadingProgress +- onMediaDownloadingProgress + + +#### Deprecated methods + +sendMessage (RtmMessage message, ResultCallback\ resultCallback) is deprecated. Use sendMessage (RtmMessage message, SendMessageOptions options, ResultCallback\ resultCallback) instead. + +### v1.2.2 + +v1.2.2 was released on December 13, 2019. + + + +**Issues Fixed** + +Occasionally fails to receive any callback after a channel attribute operation. + +### v1.2.1 + +v1.2.1 was released on November 29, 2019. + +**New Feature** + +*Compatible with the endCall method of the Agora Signaling SDK* + +If you use the `sendMessageToPeer` method to send a text message in the format of AgoraRTMLegacyEndcallCompatibleMessagePrefix_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore) in your additional information but you can set \ as empty "". + +**Issues Fixed** + + +- The SDK fails to reconnect to the Agora system if the user disables VPN. +- If a channel member reconnects to the Agora server after being interrupted, chances are the rest members of the channel can receive `onMemberJoined` twice. + +### v1.2.0 + +v1.2.0 was released on November 6, 2019. + +**New Features** + +#### Subscribe to the online status of the specified user(s) + +When the method call succeeds, the SDK returns the onPeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe. +When the online status of the peers, to whom you subscribe, changes, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed. +If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server. + +#### Unsubscribe from the online status of the specified user(s) + +Allows you to unsubscribe from the online status of the specified user(s). + +#### Get a list of the peers, to whose specific status you have subscribed + +Allows you to get a list of the peers, to whose specific status you have subscribed. + +#### Create a raw message + +Creates and initializes a raw message to be sent. + + If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB. + +**Issues Fixed** + + - The system returns `rtm native not ready`, if one creates multiple channels with the same `channelId` and then calls `join` or `leave`. + +### v1.1.0 + +v1.1.0 was released on October 14, 2019. It adds the following features: + +- [Gets the member count of specified channel(s).](#getcount) +- [Automatically returns the latest numer of members in the current channel](#oncount) +- [Channel attribute operations](#channelattributes) + + + +**Compatibility Changes** + +1. Deprecates the sendMessageToPeer method, and uses sendMessageToPeer(const char \*, const IMessage \*, const SendMessageOptions \&) instead. +2. The getServerReceivedTs method of the RtmMessage object supports both peer-to-peer and channel messages. +3. Timeout for sending a peer-to-peer message is 10 seconds from this release, compared to 5 seconds in previous versions. See PEER_MESSAGE_ERR_TIMEOUT. +4. Puts a limit on the frequency of join the same channel: Two times every five seconds. + +**New Features** + + +#### 1. Gets the member count of specified channel(s). + +You can now get the member count of specified channel(s) without the need to join, by calling the getChannelMemberCount method. You can get the member counts of a maximum of 32 channels in one method call. + + +#### 2. Automatically returns the latest numer of members in the current channel + +If you are already in a channel, you do not have to call the `getChannelMemberCount` method to get the member count of the current channel. We also do not recommend using `onMemberJoined` and `onMemberLeft` to keep track of the member counts. As of this release, the SDK returns to the channel members onMemberCountUpdated the latest channel member count when the number of channel members changes. Note that: + +- When the number of channel members ≤ 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once per second. +- When the number of channel members exceeds 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once every three seconds. + +> Please treat this callback and the getMembers method separately: +> - The former is an active callback. It returns the current numer of channel members; +> - The latter relies on the onSuccess callback to return a member list of the current channel. If the number of channel members exceeds 512, the SDK only returns a list of 512 randomly-selected channel members. + + +#### 3. Channel attribute operations + +Supports setting or getting the attribute(s) of a specified channel. You can use this feature to create group anouncement. + +Each channel attribute comes as a key-value pair. See RtmChannelAttribute for more information. Where: + +- The key of each channel attribute must be visible characters and not exceed 8 KB. +- Each channel attribute must not exceed 8 KB in length. +- The overall size of the attributes of a channel must not exceed 32 KB. +- The number of attributes of a channel must not exceed 32. + +Specific features: + +- Sets the attributes of a specified channel with new ones. +- Adds or updates the attribute(s) of a specified channel. +- Deletes the attributes of a specified channel by attribute keys. +- Clears all attributes of a specified channel. +- Gets all attributes of a specified channel. +- Gets the attributes of a specified channel by attribute keys. + +When updating attributes of a channel, you can use the setEnableNotificationToChannelMembers flag to decide whether or not to notify all members of the channel about this attribute change. + +> The SDK caches the channel attributes. If multiple users have the privilege to update the channel attributes, then we recommend calling the getChannelAttributes to update the cache before updating the channel attributes. + +**Improvements** + +#### Resends peer-to-peer messages + +This release improves the resending mechanism of peer-to-peer messages, and extends the timeout for sending a peer-to-peer message from five to 10 seconds, greatly improving the success rate of peer-to-peer message sending under weak network conditions. + +#### Caches channel messages + +The Agora system will resend a maximum of 32 channel messages of up to 30 seconds to channel members, when they manage to reconnect to the system from poor network conditions. This greatly improves the overall arrival rate of channel messages under weak network conditions. + + +**API Changes** + +#### Added Methods + +- setChannelAttributes: Sets the attributes of a specified channel with new ones. +- addOrUpdaeChannelAttributes: Adds or updates the attribute(s) of a specified channel. +- deleteChannelAttributesByKeys: Deletes the attributes of a specified channel by attribute keys. +- clearChannelAttributes: Clears all attributes of a specified channel. +- getChannelAttributes: Gets all attributes of a specified channel. +- getChannelAttributesByKeys: Gets the attributes of a specified channel by attribute keys. +- getChannelMemberCount: Gets the member count of specified channel(s). + +#### Added Callbacks + +- onAttributesUpdated: Returns all attributes of the channel when the channel attributes are updated. +- onMemberCountUpdated: Occurs when the number of the channel members changes, and returns the new number. + +#### Added Error Codes + +- GetChannelMemberCountErrCode: Error codes related to retrieving the channel member count of specified channel(s). +- JOIN_CHANNEL_ERR_JOIN_SAME_CHANNEL_TOO_OFTEN: The frequency of joining the same channel exceeds two times every five seconds. + +#### Deprecated Methods + +- sendMessageToPeer: Replaced by the sendMessageToPeer(const char \*, const IMessage \*, const SendMessageOptions \&) method. + +#### Deprecated Error Codes + +- ATTRIBUTE_OPERATION_ERR_NOT_READY: Replaced by ATTRIBUTE_OPERATION_ERR_USER_NOT_LOGGED_IN. + +### v1.0.1 + +v1.0.1 was released on August 1st, 2019. + +**Issues Fixed** + +- When the connection to the Agora system is interrupted, the SDK does not return the `onConnectionStateChanged` callback. + +### v1.0.0 + +v1.0.0 was released on July 24th, 2019. + +**New Features** + +#### Interconnects with the legacy Agora Signaling SDK + +v1.0.0 implements the `LocalInvitation.setChannelId` and `LocalInvitation.getChannelId` methods. + +> - To intercommunicate with the legacy Agora Signaling SDK, you MUST set the channel ID. However, even if the callee successfully accepts the call invitation, the Agora does not join the channel of the specified channel ID. +> - If your App does not involve the legacy Agora Signaling SDK, we recommend using the `LocalInvitation.setContent` method or the `RemoteInvitation.setResponse` method to set customized contents. + +#### Specifies the default path to the SDK log file + +Supports changing the default path to the SDK log file using the `setLogFile` method. To avoid creating an incomplete log file, we recommend calling this method once you have created and initialized an `RtmClient` instance. + + + +#### Sets the output log level of the SDK + +Supports setting the output log level of the SDK using the `setLogFilter` method. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING. + +> You can call this method once you have created and initializd an `RtmClient` instance. You do not have to call this method after calling the `login` method. + +#### Sets the log file size in KB + +Supports setting the log file size using the `setLogFileSize` method. The log file has a default size of 512 KB. File size settings of less than 512 KB or greater than 10 MB will not take effect. + + +> You can call this method once you have created and initializd an `RtmClient` instance. You do not have to call this method after calling the `login` method. + +**Improvements** + +Adds error codes based on the following scenarios: + +- The Agora service is not initialized. +- The method call frequency exceeds the limit. +- The user does not call the `login` method or the method call of `login` does not succeed before calling any of the core APIs. + +**Issues Fixed** + +- One can log in the Agora system with a static App ID and an token, which is generated from a dynamic App ID. + + +**API Changes** + +- setLogFile: Specifies the default path to the SDK log file. +- setLogFilter: Sets the output log level of the SDK. +- setLogFileSize: Sets the log file size in KB. +- getSdkVersion: Gets the SDK version. + + + + +### v0.9.3 + +v0.9.3 was released on June 7th, 2019. + +**New Features** + +#### Sends an (offline) peer-to-peer message to a specified user (receiver) + +This version allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one. + + +#### User attribute-related operations + +This version allows you to set or update a user's attributes. You can: + +- Substitutes the local user's attributes with new ones. +- Adds or updates the local user's attribute(s). +- Deletes the local user's attributes using attribute keys. +- Clears all attributes of the local user. +- Gets all attributes of a specified user. +- Gets the attributes of a specified user using attribute keys. + +> - Only after you successfully loggin in the Agora system can you execute user attribute-related operations. Otherwise, the SDK triggers the `ATTRIBUTE_OPERATION_ERR_NOT_READY` error code. +> - The attributes you set will be clears when you log out of . +> - You can only set a maximum of 16 KB attributes in a single method call. Otherwise, the SDK triggers the `ATTRIBUTE_OPERATION_ERR_SIZE_OVERFLOW` error code. + +**Improvements** + +- Supports creating an channel before logging in the Agora system. +- Supports creating multiple channels. But a user can only join a maximum of 20 channels at the same time. When the number of the joined channels exceeds 20, the SDK triggers the `JOIN_CHANNEL_ERR_FAILURE` error code. + +**Issues Fixed** + +- Occasional system crashes. +- A user who has logged out of the Agora system appears online to the other users until 30 seconds later. + +### v0.9.2 + +v0.9.2 was released on May 5th, 2019. + +**New Features** + +#### Queries the Online Status of the Specified Users + +This release introduces a new concept: online and offline. + +- Online: The user has logged in the Agora system. +- Offline: The user has logged out of the Agora system. + +This release adds the function of querying the online status of the specified users. After logging in the Agora system, you can get the online status of a maximum of 256 specified users. See queryPeersOnlineStatus. + +> - The sequence of the returned user IDs is identical to the input sequence. +> - The call frequency of this method is 10 queries every five seconds. See [Limitations](../reference/limitations). + +#### Renews the Token + +In the production environment, you need to use a token to log in the Agora system. Each token expires 24 hours after it is created. This release allows you to renew a token. + +- If you are logging in the Agora system and if your token has expired, the SDK returns the LOGIN_ERR_TOKEN_EXPIRED error code. +- if you are logged in the Agora system, you will not be kicked out immediately when your token expires. But you need to renew your token the next time you log in the Agora system. Therefore, we still recommend that you renew your token when receiving the onTokenExpired callback. + +> - The renewToken method must be called before creating an RtmClient. +> - The call freqency of the `RenewToken` method is two queries every second. See [Limitations](../reference/limitations). + +**Improvements** + +- Supports a `userId` that starts with a space. + +**API Changes** + +#### Queries the Online Status of the Specified Users + +##### Adds + +- Method: queryPeersOnlineStatus +- Error Code: [QueryPeersOnlineStatusError + +#### Renews the Token + +##### Adds + +- Method: renewToken +- Callback: onTokenExpired +- Error Codes: + - RenewTokenError + +#### Call Invitation + +Adds the following error code for when a user sends a call invitation without logging in the Agora system. + +- LOCAL_INVITATION_ERR_NOT_LOGGEDIN + +### v0.9.1 + +v0.9.1 was released on April 4th, 2019. + +**New Features** + +This release adds the call invitation feature, allowing you to create, send, cancel, accept, and decline a call invitation in a one-to-one or one-to-many voice/video call. + +**Improvements** + +- Optimizes the object relations to facilitate understanding. +- Renames some interfaces to conform to Java naming conventions. +- Removes `ChannelMessageState` and `PeerMessageState` to simplify the process of sending a channel or peer-to-peer message. Uses `ChannelMessageError` and `PeerMessageError` instead. +- Removes `IStateListener` for listening to message states. Uses the generic `ResultCallback` instead. + +**API Changes** + +#### Adds + +- LocalInvitation.setContent(): allows the caller to set the content of an outgoing call invitation. +- LocalInvitation.getContent(): allows the caller to retrieve the content of an outgoing call invitation. +- LocalInvitation.getResponse(): allows the caller to retrieve the response set by the callee. +- LocalInvitation.getState(): allows the caller to retrieve the state of an outgoing call invitation. +- RemoteInvitation.getCallerId(): allows the callee to retrieve the user ID of the caller. +- RemoteInvitation.getContent(): allows the callee to retrieve the content set by the caller. +- RemoteInvitation.setResponse(): allows the callee to set the response to the caller. +- RemoteInvitation.getResponse(): allows the callee to retrieve the response to the caller. +- RemoteInvitation.getState(): allows the callee to retrieve the state of the incoming call invitation +- RtmCallEventListener.onLocalInvitationReceivedByPeer(): occurs when the callee receives the call invitation. +- RtmCallEventListener.onLocalInvitationAccepted(): occurs when the callee accepts the call invitation. +- RtmCallEventListener.onLocalInvitationRefused(): occurs when the callee declines the call invitation. +- RtmCallEventListener.onLocalInvitationCanceled(): occurs when the caller cancels the call invitation. +- RtmCallEventListener.onLocalInvitationFailure(): occurs when the outgoing call invitation fails. +- RtmCallEventListener.onRemoteInvitationReceived(): occurs when the callee receives a call invitation. +- RtmCallEventListener.onRemoteInvitationAccepted(): occurs when the callee accepts a call invitation. +- RtmCallEventListener.onRemoteInvitationRefused(): occurs when the callee declines a call invitation. +- RtmCallEventListener.onRemoteInvitationCanceled(): occurs when the caller cancels the call invitation. +- RtmCallEventListener.onRemoteInvitationFailure(): occurs when the incoming call invitation fails. +- RtmCallManager.setEventListener(): sets the event listener to the `RtmCallManager` instance. +- RtmCallManager.createLocalInvitation(): creates a call invitation. +- RtmCallManager.sendLocalInvitation(): sends a call invitation to a specified user. +- RtmCallManager.acceptRemoteInvitation(): accepts an incoming call invitation. +- RtmCallManager.refuseRemoteInvitation(): declines an incoming call invitation. +- RtmCallManager.cancelLocalInvitation(): allows the caller to cancel an outgoing call invitation. +- RtmStatusCode#LocalInvitationState states of an outgoing call invitation. +- RtmStatusCode#RemoteInvitationState: states of an incoming call invitation. +- RtmStatusCode#LocalInvitationError: error codes of an outgoing call invitation. +- RtmStatusCode#RemoteInvitationError: error codes of an incoming call invitation. +- RtmStatusCode#InvitationApiCallError: error codes of the invitation-specific API calls. +- ConnectionChangeReason#CONNECTION_CHANGE_REASON_REMOTE_LOGIN: another instance has logged in the Agora system with the same user ID. + +#### Renames + +- The `RtmClient.destroy()` method, which releases all resources used by the `RtmClient` instance, to: RtmClient.release(). +- The `IResultCallback` class to: ResultCallback + +#### Deletes + +- Deletes `PEER_MESSAGE_RECEIVED_BY_SERVER` from PeerMessageError, uses `PEER_MESSAGE_ERR_OK` instead. +- Deletes `CHANNEL_MESSAGE_RECEIVED_BY_SERVER` from ChannelMessageError, uses `CHANNEL_MESSAGE_OK` instead. +- Deletes the `PeerMessageState` interface, uses PeerMessageError instead. +- Deletes the `ChannelMessageState` interface, uses ChannelMessageError instead. +- Deletes the `IStateListener` class for listening to message states, uses the ResultCallback class instead for listening to the peer or channel message results. + - Success: the SDK returns the ResultCallback.onSuccess() callback. + - Failure: the SDK returns the ResultCallback.onFailure() callback with the corresponding error codes. + +### v0.9.0 + +v0.9.0 was released on February 4th, 2019. + +Initial version. + +Key features: + +- Sends or receives peer-to-peer messages. +- Joins or leaves a channel. +- Sends or receives channel messages. + + + + + diff --git a/shared/signaling/release-notes/linux.mdx b/shared/signaling/release-notes/linux.mdx new file mode 100644 index 000000000..6824f0a06 --- /dev/null +++ b/shared/signaling/release-notes/linux.mdx @@ -0,0 +1,9 @@ +import CPP from './cpp.mdx'; +import JAVA from './java.mdx'; + +This page contains information on the following releases: + + + + + diff --git a/shared/signaling/release-notes/macos.mdx b/shared/signaling/release-notes/macos.mdx new file mode 100644 index 000000000..d1063cc48 --- /dev/null +++ b/shared/signaling/release-notes/macos.mdx @@ -0,0 +1,13 @@ +import Text from './oc.mdx'; + + + +## Known issues and limitations + +#### Compatibility with macOS Monterey 12 + +As of v1.4.6, the SDK supports macOS Monterey 12. For the SDK versions v1.4.4 and v1.4.5, crashes occur on macOS Monterey 12. To fix this issue, upgrade the SDK to v1.4.6 or later. + + + + \ No newline at end of file diff --git a/shared/signaling/release-notes/oc.mdx b/shared/signaling/release-notes/oc.mdx new file mode 100644 index 000000000..7e43e3620 --- /dev/null +++ b/shared/signaling/release-notes/oc.mdx @@ -0,0 +1,703 @@ + + +## v1.6.0 + +v1.6.0 was released on February 12, 2023. + +#### New features + +**User and channel metadata** + +This release adds easy-to-use, serverless storage for user and channel metadata. +You can store any custom attribute, for example, user name or nickname, as metadata. +Signaling SDK generates events when the metadata associated with a particular user or channel +is set or deleted. + +#### API changes + +**Added** + +- `addLocalUserMetadata`: Adds to the local user’s metadata. +- `updateLocalUserMetadata`: Updates the local user’s metadata. +- `deleteLocalUserMetadata`: Deletes the local user’s metadata. +- `setLocalUserMetadata`: Sets the local user’s metadata. +- `clearLocalUserMetadata`: Deletes all local user’s metadata. +- `getUserMetadata`: Gets the metadata of a specified user. +- `subscribeUserMetadata`: Subscribes to metadata update events of a specific user. +- `unsubscribeUserMetadata`: Unsubscribes from metadata update events of a specific user. +- `onUserMetadataUpdated`: Occurs when a user's metadata is updated. +- `addChannelMetadata`: Adds to channel metadata. +- `updateChannelMetadata`: Updates channel metadata. +- `deleteChannelMetadata`: Deletes channel metadata. +- `setChannelMetadata`: Sets channel metadata. +- `clearChannelMetadata`: Deletes channel metadata. +- `getChannelMetadata`: Gets the metadata of a specified channel. +- `onMetadataUpdated`: Occurs when channel metadata is updated. + + + +## v1.5.1 + +v1.5.1 was released on September 1, 2022 and improved the stability of the SDK. + +## v1.5.0 + +v1.5.0 was released on July 27, 2022. + +#### Sunset features +Image or file messages, historical messages, and offline messages are deprecated as of this release. If you have integrated these features in a previous release, you can continue to use them. + +#### API changes + +The following methods are deprecated: + +- createFileMessageByMediaId +- createFileMessageByUploading +- createImageMessageByMediaId +- createImageMessageByUploading +- cancelMediaUpload +- cancelMediaDownload +- downloadMedia +- downloadMediaToMemory +- fileMessageReceived +- imageMessageReceived +- uploadingProgress +- downloadingProgress +- enableOfflineMessaging +- enableHistoricalMessaging + + +## v1.4.10 +v1.4.10 was released on March 01, 2022. + +#### Compatibility changes + +This release adds supports for running the iOS simulator on devices with M1 chips. + +#### Issues fixed + +Fixed some rich media related crashes. + + +## v1.4.9 + +v1.4.9 was released on November 19, 2021. + +#### Improvements + +Improved the login success rate and connection stability under the IPv4/IPv6 dual-stack network. + +#### Bug fixes + +This release fixed the following issues: + +- The internal class name conflicts when used together with the Agora , causing unexpected prompts when running the app. +- A crash occurred occasionally when exiting the app. + +## v1.4.8 + +v1.4.8 was released on July 23, 2021. + +This release update the SDK version in the Info.plist file to the latest version. + +## v1.4.7 +v1.4.7 was released on July 19, 2021. + +#### Improvement + +- Fixed the potential crashes caused by adding support for iOS 15, and improved the stability of the SDK. +- Improved the success rate of logins and message delivery for the in poor network conditions. + +## v1.4.6 +v1.4.6 was released on June 21, 2021. This release supports iOS 15. + +## v1.4.5 + +v1.4.5 was released on April 30, 2021. + +#### Compatibility changes + +As of v1.4.4, the SDK has been upgraded from a static library to a dynamic library, and the format of all dynamic libraries changes from framework to XCFramework. +If you are using a build tool that does not support the dynamic library in XCFramework format, Agora provides the following scripts to help you integrate: + +- Use the [change_to_all_arch.sh](https://web-cdn.agora.io/docs-files/1621391958917) script to convert the XCFramework to the universal framework. +- If you need to publish an iOS/macOS app on the App Store, use the [remove_simulator_arch.sh](https://web-cdn.agora.io/docs-files/1621392005121) script to remove the simulator before packaging the app. + +#### Improvements + +Fixed some issues that might cause crashes to improve stability. + +#### Fixed issues + +The iOS app integrated with the SDK v1.4.4 cannot be published on the App Store due to review issues. + +## v1.4.4 + +v1.4.4 was released on April 20, 2021. + +#### Compatibility changes + +This release replaces the static library with a dynamic library for the following reasons: + +- Improving overall security. +- Avoiding compatibility issues with other third-party libraries. +- Making it easier to upload the app to the App Store. + +To upgrade the Native SDK, you must re-integrate the dynamic library, **AgoraRtmKit.xcframework.** And there is no need to integrate dependent libraries. + +The format of all dynamic libraries changes from Framework to XCFramework. A dynamic library in XCFramework format supports running a project on both physical devices and simulators. + +#### Improvements + +Improved the success rate of logins and message delivery for the in poor network conditions. + +#### Issues Fixed + +This release fixed the following issues: + +- A memory leak issue with the SDK. +- Some issues that may cause the system to crash. + +## v1.4.3 + +v1.4.3 was released on February 10, 2021. + +#### Issues fixed + +This release fixed the following issues: + +- Naming conflict between the values in the `AgoraAreaCode` constant of the Agora and the `AgoraRtmAreaCode` constant of the Agora when using Swift. As of v1.4.3, Agora Objective-C SDK for iOS/macOS provides `AgoraRtmKit_swift.h`, which updates the constant values of `AgoraRtmAreaCode`, to avoid this naming conflict. +- Crash issues caused by OpenSSL upgrade in Agora v1.4.2. +- Crash issues caused by occasional multi-thread access conflict. +- High timeout rate for login operations. + +## v1.4.2 + +v1.4.2 was released on November 23, 2020. + +#### Improvements + +- Improved performance of login and messaging operations. +- Added the `AGORA_SDK_BOTH_RTM_AND_RTC` macro for the `AgoraRtmAreaCode` enum type. You can use the macro to resolve naming conflicts when using and together. + +## v1.4.1 + +v1.4.1 was released on September 30, 2020. + +#### Improvements + +Improved the log file. + +#### Bug fixes + +Fixed the pop up issue in iOS 14. + +## v1.4.0 + +v1.4.0 was released on September 1, 2020. + +#### Compatibility changes + +- You need to add new ports to the firewall whitelist. See [Firewall Requirements](../reference/firewall). + - New TCP ports: 8443, 9136, 9137, 9141. New UDP port: 8443. Reason: Support real-time transport encryption. + - New UDP ports: 8130, 9120, 9121. Reason: Support UDP path to improve the SDK's performance in sub-optimal network conditions. + - New UDP port: 9700. Reason: Support data reporting. +- In `setLogFileSize`, the default log file size increases from 512 KB to 10 MB. The maximum log file size increases from 10 MB to 1 GB. +- Before destroying an `AgoraRtmKit` instance, you must call `destroyChannelWithId` to destroy all existing `AgoraRtmChannel` instances. Otherwise, the SDK may crash. + +#### New features + +- Geofencing. You can call `setRtmServiceContext` to set the region of the Agora . The can only connect to Agora servers within the specified region. +- Transport Layer Security (TLS) encryption. + +#### Improvements + +- Improved the success rate of login and message delivery of the in poor network conditions. +- Optimized the reconnection mechanism. + +#### API changes + +**New methods** + +setRtmServiceContext + +## v1.3.0 + +v1.3.0 was released on May 8, 2020. + +**Compatibility changes** + +- You need to add a new TCP port, 9140, to the firewall whitelist. The port is for sending and receiving image or file messages. See [Firewall Requirements](../reference/firewall). +- The Agora server blocks any file message or image message that you send to 1.2.2 or earlier, or to the Signaling SDK. + +**New features** + +#### 1. Send and receive file messages + +v1.3.0 supports downloading non-empty files that are smaller than 30 MB. You can cancel an ongoing upload or download process at any time. Each file you upload to the Agora server corresponds to a media ID. The file stays on the Agora server for seven days. You can use the media ID to download the file as long as it is is still on the Agora server. + +
You can only download files using the download methods provided by the SDK.
+ +v1.3.0 adds the `AgoraRtmFileMessage` interface for saving and transferring a media ID. The `AgoraRtmFileMessage` interface inherits from the `AgoraRtmMessage` interface, so you can use existing peer-to-peer or channel messaging methods to transfer the `AgoraRtmFileMessage` instance. You can use the `AgoraRtmFileMessage` interface to complete the following tasks: + +- Set the filename and thumbnail of the uploaded file. +- Get the size of the uploaded file. + +
The total size of the message content, the filename, and the thumbnail must not exceed 32 KB.
+ +#### 2. Send and receive image messages + +v1.3.0 supports downloading non-empty image files that are smaller than 30 MB. You can cancel an ongoing upload or download process at any time. Each image file you upload to the Agora server corresponds to a media ID. The image file stays on the Agora server for seven days. You can use media ID to download the image file as long as the image file is still on the Agora server. + +
You can only download images using the download methods provided by the SDK.
+ +v1.3.0 adds the `AgoraRtmImageMessage` interface for saving and transferring a media ID. The `AgoraRtmImageMessage` interface inherits from the `AgoraRtmMessage` interface, so you can use existing peer-to-peer or channel messaging methods to transfer the `AgoraRtmImageMessage` instance. You can use the `AgoraRtmImageMessage` interface to complete the following tasks: + +- Set the filename and thumbnail of the uploaded image. +- Get the size of the uploaded image. +- Get the SDK-calculated width and height of images in JPEG, JPG, BMP, or PNG format. +- Set the width or height of images. The width or height you set overwrite the width or height that the SDK calculates. + +
The total size of the message content, the filename, and the thumbnail must not exceed 32 KB.
+ +#### 3. Report the progress of upload or download + +SDK returns the progress of an upload or download by callback every second during a task in progress. If the upload or download task pauses, the SDK ceases to return any further callback until the task continues. + +**Bug fixes** + +- Login failure caused by the SDK's incorrect identification of user's network type. +- Other problems that may cause the system to crash. + +**API changes** + +#### New methods + +- createFileMessageByUploading:withRequest:completion: +- createImageMessageByUploading:withRequest:completion: +- cancelMediaUpload:completion: +- cancelMediaDownload:completion: +- createFileMessageByMediaId: +- createImageMessageByMediaId: +- downloadMediaToMemory:withRequest:completion: +- downloadMedia:toFile:withRequest:completion: + +#### New callbacks + +- rtmKit:media:uploadingProgress: +- rtmKit:media:downloadingProgress: +- kAgoraRtmUploadFileMediaBloc +- AgoraRtmUploadImageMediaBlock +- AgoraRtmCancelMediaBlock +- AgoraRtmDownloadMediaToMemoryBlock +- AgoraRtmDownloadMediaToFileBlock +- rtmKit:fileMessageReceived:fromPeer: +- rtmKit:imageMessageReceived:fromPeer: +- channel:fileMessageReceived:fromMember: +- channel:imageMessageReceived:fromMember: + +#### Deprecated methods + +sendMessage:completion: is deprecated. Use sendMessage:sendMessageOptions:completion: instead. + +## v1.2.2 + +v1.2.2 was released on December 13, 2019. + + + +**Issues Fixed** + +Occasionally fails to receive any callback after a channel attribute operation. + +## v1.2.1 + +v1.2.1 was released on November 29, 2019. + +**New Feature** + +*Compatible with the endCall method of the Agora Signaling SDK* + +If you use the `sendMessageToPeer` method to send a text message in the format of AgoraRTMLegacyEndcallCompatibleMessagePrefix_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore) in your additional information but you can set \ as empty "". + +**Issues Fixed** + + +- The SDK fails to reconnect to the Agora system if the user disables VPN. +- If a channel member reconnects to the Agora server after being interrupted, chances are the rest members of the channel can receive `MemberJoined` twice. + +## v1.2.0 + +v1.2.0 was released on November 6, 2019. + +**Compatibility Changes** + +Deprecated the `isOnline` property of the `AgoraRtmPeerOnlineStatus`. Use `state` instead. + + +**New Features** + +#### Subscribe to the online status of the specified user(s) + +When the method call succeeds, the SDK returns the PeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe. +When the online status of the peers, to whom you subscribe, changes, the SDK returns the PeersOnlineStatusChanged callback to report whose online status has changed. +If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the PeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server. + +#### Unsubscribe from the online status of the specified user(s) + +Allows you to unsubscribe from the online status of the specified user(s). + +#### Get a list of the peers, to whose specific status you have subscribed + +Allows you to get a list of the peers, to whose specific status you have subscribed. + +#### Create a raw message + +Creates and initializes a raw message to be sent. + + If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB. + +## v1.1.0 + +v1.1.0 is released on September 18, 2019. It adds the following features: + +- [Gets the member count of specified channel(s).](#getcount) +- [Automatically returns the latest numer of members in the current channel](#oncount) +- [Channel attribute operations](#channelattributes) + + + +**Compatibility Changes** + +1. Deprecates the sendMessage:toPeer:completion: method, and uses sendMessage:toPeer:sendMessageOptions:completion: instead +2. The serverReceivedTs property of the AgoraRtmMessage instance supports both peer-to-peer and channel messages. +3. Timeout for sending a peer-to-peer message is 10 seconds from this release, compared to 5 seconds in previous versions. See AgoraRtmSendPeerMessageErrorTimeout +4. Puts a limit on the frequency of joinWithCompletion the same channel: Two times every five seconds. + +**New Features** + + +#### 1. Gets the member count of specified channel(s). + +You can now get the member count of specified channel(s) without the need to join, by calling the getChannelMemberCount method. You can get the member counts of a maximum of 32 channels in one method call. + + +#### 2. Automatically returns the latest numer of members in the current channel + +If you are already in a channel, you do not have to call the `getChannelMemberCount` method to get the member count of the current channel. We also do not recommend using `onMemberJoined` and `onMemberLeft` to keep track of the member counts. As of this release, the SDK returns to the channel members memberCount the latest channel member count when the number of channel members changes. Note that: + +- When the number of channel members ≤ 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once per second. +- When the number of channel members exceeds 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once every three seconds. + +> Please treat this callback and the AgoraRtmGetMembersBlock callback separately: +> - The former is an automatic callback. It returns the current numer of channel members; +> - The latter is triggered by the getMembersWithCompletion method. It returns a member list of the current channel. If the number of channel members exceeds 512, the SDK only returns a list of 512 randomly-selected channel members. + + +#### 3. Channel attribute operations + +Supports setting or getting the attribute(s) of a specified channel. You can use this feature to create group anouncement. + +Each channel attribute comes as a key-value pair. See AgoraRtmChannelAttribute. Where: + +- The key of each channel attribute must be visible characters and not exceed 8 KB. +- Each channel attribute must not exceed 8 KB in length. +- The overall size of the attributes of a channel must not exceed 32 KB. +- The number of attributes of a channel must not exceed 32. + +Specific features: + +- Sets the attributes of a specified channel with new ones. +- Adds or updates the attribute(s) of a specified channel. +- Deletes the attributes of a specified channel by attribute keys. +- Clears all attributes of a specified channel. +- Gets all attributes of a specified channel. +- Gets the attributes of a specified channel by attribute keys. + +When updating attributes of a channel, you can use the enableNotificationToChannelMembers flag to decide whether or not to notify all members of the channel about this attribute change. + +> The SDK caches the channel attributes. If multiple users have the privilege to update the channel attributes, then we recommend calling the getChannelAllAttributes to update the cache before updating the channel attributes. + +**Improvements** + +#### Resends peer-to-peer messages + +This release improves the resending mechanism of peer-to-peer messages, and extends the timeout for sending a peer-to-peer message from five to 10 seconds, greatly improving the success rate of peer-to-peer message sending under weak network conditions. + +#### Caches channel messages + +The Agora system will resend a maximum of 32 channel messages of up to 30 seconds to channel members, when they manage to reconnect to the system from poor network conditions. This greatly improves the overall arrival rate of channel messages under weak network conditions. + + +**API Changes** + +#### Added Methods + +- setChannelAttributes：Substitutes the attributes of a specified channel with new ones. +- addOrUpdaeChannelAttributes：Adds or updates the attribute(s) of a specified channel. +- deleteChannelAttributesByKeys：Deletes the attributes of a specified channel by attribute keys. +- clearChannelAttributes：Clears all attributes of a specified channel. +- getChannelAllAttributes: Gets all attributes of a specified channel. +- getChannelAttributesByKeys: Gets the attributes of a specified channel by attribute keys. +- getChannelMemberCount: Gets the member count of specified channel(s). + +#### Added Callbacks + +- attributesUpdate: Returns all attributes of the channel when the channel attributes are updated. +- memberCount: Occurs when the number of the channel members changes, and returns the new number. + +#### Added Error Codes + +- AgoraRtmChannelMemberCountErrorCode: Error codes related to retrieving the channel member count of specified channel(s). +- AgoraRtmJoinSameChannelErrorTooOften: The frequency of joining the same channel exceeds two times every five seconds. + +#### Deprecated Methods + +- sendMessage:toPeer:completion:: Replaced by the sendMessage:toPeer:sendMessageOptions:completion: method. + +#### Deprecated Error Codes + +- AgoraRtmAttributeOperationErrorNotReady: Replaced by AgoraRtmAttributeOperationErrorNotLoggedIn. + + + + + + +## v1.0.1 + +v1.0.1 is released on August 1st, 2019. + +#### Issues Fixed + +- When the connection to the Agora system is interrupted, the SDK does not return the `connectionStateChanged` callback. +- Occasional crashes on iOS. + +## v1.0.0 + +v1.0.0 is released on July 24th, 2019. + +#### New Features + +#### Interconnects with the legacy Agora Signaling SDK + +v1.0.0 implements the `channelId` property in the `AgoraRtmLocalInvitation` class. + +> - To intercommunicate with the legacy Agora Signaling SDK, you MUST set the channel ID. However, even if the callee successfully accepts the call invitation, the Agora does not join the channel of the specified channel ID. +> - If your App does not involve the legacy Agora Signaling SDK, we recommend using the `content` property of the `AgoraRtmLocalInvitation` class or the `response` property of the `AgoraRtmRemoteInvitation` class to set customized contents. + +#### Specifies the default path to the SDK log file + +Supports changing the default path to the SDK log file using the `setLogFile` method. To avoid creating an incomplete log file, we recommend calling this method once you have created and initialized an `AgoraRtmKit` instance. + + + +#### Sets the output log level of the SDK + +Supports setting the output log level of the SDK using the `setLogFilter` method. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING. See also AgoraRtmLogFilter. + +> You can call this method once you have created and initializd an `AgoraRtmKit` instance. You do not have to call this method after calling the `loginByToken` method. + +#### Sets the log file size in KB + +Supports setting the log file size using the `setLogFileSize` method. The log file has a default size of 512 KB. File size settings of less than 512 KB or greater than 10 MB will not take effect. + + +> You can call this method once you have created and initializd an `AgoraRtmKit` instance. You do not have to call this method after calling the `loginByToken` method. + +#### Improvements + +Adds error codes based on the following scenarios: + +- The Agora service is not initialized. +- The method call frequency exceeds the limit. +- The user does not call the `loginByToken` method or the method call of `loginByToken` does not succeed before calling any of the core APIs. + +#### Issues Fixed + +- Occasional crashes on iOS. +- One can log in the Agora system with a static App ID and an token, which is generated from a dynamic App ID. + + +#### API Changes + +- setLogFile: Specifies the default path to the SDK log file. +- setLogFilter: Sets the output log level of the SDK. +- setLogFileSize: Sets the log file size in KB. +- getSDKVersion: Gets the version of the Agora . + + + + +## v0.9.3 + +v0.9.3 is released on June 7th, 2019. + +#### New Features + +#### Sends an (offline) peer-to-peer message to a specified user (receiver) + +This version allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one. + + +#### User attribute-related operations + +This version allows you to set or update a user's attributes. You can: + +- Substitutes the local user's attributes with new ones. +- Adds or updates the local user's attribute(s). +- Deletes the local user's attributes using attribute keys. +- Clears all attributes of the local user. +- Gets all attributes of a specified user. +- Gets the attributes of a specified user using attribute keys. + +> - Only after you successfully loggin in the Agora system can you execute user attribute-related operations. Otherwise, the SDK triggers the `AgoraRtmAttributeOperationErrorNotReady` error code. +> - The attributes you set will be clears when you log out of . +> - You can only set a maximum of 16 KB attributes in a single method call. Otherwise, the SDK triggers the `AgoraRtmAttributeOperationErrorSizeOverflow` error code. + +#### Improvements + +- Supports creating an channel before logging in the Agora system. +- Supports creating multiple channels. But a user can only join a maximum of 20 channels at the same time. When the number of the joined channels exceeds 20, the SDK triggers the `AgoraRtmJoinChannelErrorFailure` error code. + +#### Issues Fixed + +- Occasional system crashes. +- A user who has logged out of the Agora system appears online to the other users until 30 seconds later. + +## v0.9.2 + +v0.9.2 is released on May 5th, 2019. + +> This release does not support creating an RtmChannel instance before logging in the Agora system + +#### New Features + +#### Queries the Online Status of the Specified Users + +This release introduces a new concept: online and offline. + +- Online: The user has logged in the Agora system. +- Offline: The user has logged out of the Agora system. + +This release adds the function of querying the online status of the specified users. After logging in the Agora system, you can get the online status of a maximum of 256 specified users. See queryPeersOnlineStatus. + +> - The sequence of the returned user IDs is identical to the input sequence. +> - The call frequency of this method is 10 times every five seconds. See [Limitations](../reference/limitations). + + +#### Renews the Token + +In the production environment, you need to use a token to log in the Agora system. Each token expires 24 hours after it is created. This release allows you to [renew a token. + +- If you are logging in the Agora system and if your token has expired, the SDK returns the AgoraRtmLoginErrorTokenExpired error code. +- if you are logged in the Agora system, you will not be kicked out immediately when your token expires. But you need to renew your token the next time you log in the Agora system. Therefore, we still recommend that you renew your token when you receive the rtmKitTokenDidExpire: callback. + + +> - The renewToken method must be called before creating an RtmClient. +> - The call frequency of the renewToken method is two times every second. See [Limitations](../reference/limitations). + +#### Improvements + +- Supports a `userId` that starts with a space. + + +#### API Changes + +#### Queries the Online Status of the Specified User(s) + +##### Adds + +- Method: queryPeersOnlineStatus:completion: +- Error Code: QueryPeersOnlineStatusError + +#### Renews the Token + +##### Adds + +- Method: renewToken +- Callback: onTokenExpired +- Error Code: AgoraRtmRenewTokenErrorCode + +#### Call Invitation + +Adds the following error code for when a user sends a call invitation without logging in the Agora system. + +- AgoraRtmLocalInvitationErrorNotLoggedIn + +## v0.9.1 + +v0.9.1 is released on April 4th, 2019. + +#### New Features + +This release adds the call invitation feature, allowing you to create, send, cancel, accept, and decline a call invitation in a one-to-one or one-to-many voice/video call. + +> This version does not come with the `setLogFile` or `setLogFilter` method. +> - For iOS platforms, all log information is kept at **/Library/Caches/agorartm.log** by default. +> - For macOS platforms, all log information is kept at **~/Library/Logs/agorartm.log** by default. + +#### Improvements + +- Optimizes the object relations to facilitate understanding. +- Simplifies the process of sending a channel or peer-to-peer message. + +#### API Changes + +#### Adds + +- initWithCalleeId: allows the caller to create an AgoraRtmLocalInvitation instance. +- AgoraRtmLocalInvitation: the caller's call invitation object. +- localInvitationReceivedByPeer: occurs when the callee receives the call invitation. +- localInvitationAccepted: occurs when the callee accepts the call invitation. +- localInvitationRefused: occurs when the callee declines the call invitation. +- localInvitationCanceled: occurs when the caller cancels the call invitation. +- localInvitationFailure: occurs when the life cycle of the outgoing call invitation ends in failure. +- remoteInvitationReceived: occurs when the callee receives a call invitation. +- remoteInvitationAccepted: occurs when the callee accepts a call invitation. +- remoteInvitationRefused: occurs when the callee declines a call invitation. +- remoteInvitationCanceled: occurs when the caller cancels the call invitation. +- remoteInvitationFailure: occurs when the life cyle of the incoming call invitation ends in failure. +- AgoraRtmCallDelegate: enables Agora call callback event notifications to your app. +- sendLocalInvitation: sends a call invitation to a specified user. +- acceptRemoteInvitation: accepts an incoming call invitation. +- refuseRemoteInvitation: declines an incoming call invitation. +- cancelLocalInvitation: allows the caller to cancel an outgoing call invitation. +- AgoraRtmLocalInvitationState: states of an outgoing call invitation. +- AgoraRtmRemoteInvitationState: states of an incoming call invitation. +- AgoraRtmLocalInvitationErrorCode: error codes of an outgoing call invitation. +- AgoraRtmRemoteInvitationErrorCode: error codes of an incoming call invitation. +- AgoraRtmInvitationApiCallErrorCode: error codes of the invitation-specific API calls. +- AgoraRtmConnectionChangeReasonRemoteLogin: another instance has logged in the Agora system with the same user ID. +- AgoraRtmSendPeerMessageErrorCode: error codes of sending a peer-to-peer message. +- AgoraRtmSendChannelMessageErrorCode: error codes of sending a channel message. +- AgoraRtmConnectionChangeReasonRemoteLogin: error codes of the connection state change. + + + +#### Deletes + +- Deletes the `AgoraRtmSendMessageErrorCode` constants, uses AgoraRtmSendPeerMessageErrorCode and AgoraRtmSendChannelMessageErrorCode instead. + +#### Modifies + +- Sets `channelDelegate` as a property so that developers can freely update it. +- Removes rtmKit from the callbacks under `AgoraRtmChannelDelegate`. +- Changes the parameter of the setParameters method, which configures the SDK with JSON options. +- Deletes AgoraRtmSendChannelMessageStateReceivedByServer from AgoraRtmSendChannelMessageErrorCode. +- Deletes the AgoraRtmSendPeerMessageState interface, uses AgoraRtmSendPeerMessageErrorCode instead. +- Deletes the AgoraRtmSendChannelMessageState interface, uses AgoraRtmSendChannelMessageErrorCode instead. + +## v0.9.0 + +v0.9.0 is released on February 4th, 2019. + +Initial version. + +Key features: + +- Sends or receives peer-to-peer messages. +- Joins or leaves a channel. +- Sends or receives channel messages. + + diff --git a/shared/signaling/release-notes/react-native.mdx b/shared/signaling/release-notes/react-native.mdx new file mode 100644 index 000000000..dc59b730e --- /dev/null +++ b/shared/signaling/release-notes/react-native.mdx @@ -0,0 +1,4 @@ + + + + diff --git a/shared/signaling/release-notes/unity.mdx b/shared/signaling/release-notes/unity.mdx new file mode 100644 index 000000000..f50565e07 --- /dev/null +++ b/shared/signaling/release-notes/unity.mdx @@ -0,0 +1,21 @@ + + +This page contains information on the following releases: + +## v1.4.10 +v1.4.10 was released on August 17, 2022. + +Fixed some issues that may cause crashes when working in tandem with . + +## v1.4.8 +v1.4.8 was released on August 24, 2021. + +This release is the first release of Unity SDK. You can refer to the following documents to integrate the SDK and implement sending and receiving functions: + +- [Peer-to-peer or Channel Messaging](../get-started/get-started-sdk) + +- API Reference + +Agora provides an open-source sample project [Agora-Unity--SDK](https://github.com/AgoraIO-Community/Agora-Unity--SDK/) , you can download and experience it. + + \ No newline at end of file diff --git a/shared/signaling/release-notes/web.mdx b/shared/signaling/release-notes/web.mdx index 105e5d722..2d88520d4 100644 --- a/shared/signaling/release-notes/web.mdx +++ b/shared/signaling/release-notes/web.mdx @@ -1,202 +1,974 @@ -## v2.1.4 +## v1.6.0 -v2.1.4 was released on September 8, 2023 +v1.6.0 was released on February 12, 2023. + +#### New features + +**User and channel metadata** + +This release adds easy-to-use, serverless storage for user and channel metadata. +You can store any custom attribute, for example, user name or nickname, as metadata. +Signaling SDK generates events when the metadata associated with a particular user or channel +is set or deleted. + +#### API changes + +**Added** + +- `addLocalUserMetadata`: Adds to the local user’s metadata. +- `updateLocalUserMetadata`: Updates the local user’s metadata. +- `deleteLocalUserMetadata`: Deletes the local user’s metadata. +- `setLocalUserMetadata`: Sets the local user’s metadata. +- `clearLocalUserMetadata`: Deletes all local user’s metadata. +- `getUserMetadata`: Gets the metadata of a specified user. +- `subscribeUserMetadata`: Subscribes to metadata update events of a specific user. +- `unsubscribeUserMetadata`: Unsubscribes from metadata update events of a specific user. +- `onUserMetadataUpdated`: Occurs when a user's metadata is updated. +- `addChannelMetadata`: Adds to channel metadata. +- `updateChannelMetadata`: Updates channel metadata. +- `deleteChannelMetadata`: Deletes channel metadata. +- `setChannelMetadata`: Sets channel metadata. +- `clearChannelMetadata`: Deletes channel metadata. +- `getChannelMetadata`: Gets the metadata of a specified channel. +- `onMetadataUpdated`: Occurs when channel metadata is updated. + +## v1.5.1 + +v1.5.1 was released on September 1, 2022. + +In previous versions, when users fail to send a channel message because they either could not log in to Signaling, or not join a channel, the `CHANNEL_MESSAGE_ERR_NOT_IN_CHANNEL = 5` error code was returned. + +As of this version, the circumstances that trigger this error are further refined. Users can now easily identify and troubleshoot. When a failure of sending a channel message occurs: + +* The `CHANNEL_MESSAGE_ERR_USER_NOT_LOGGED_IN = 102` error code is returned if users do not log in to the . +* The `CHANNEL_MESSAGE_ERR_NOT_IN_CHANNEL = 5` error code is returned if users log in to the SDK whereas do not join the channel. + +## v1.5.0 + +v1.5.0 was released on July 27, 2022. + +#### Sunset features + +Image or file messages, historical messages, and offline messages are deprecated as of this release. If you have integrated these features in a previous release, you can continue to use them. + +#### Bug fixes +This release fixed the unit of timeout in output logs from milliseconds (ms) to seconds (s). + +#### API changes + +The following methods are deprecated: + +- createMediaMessageByUploading +- downloadMedia +- IMAGE and FILE in messageType +- RtmImageMessage +- RtmFileMessage +- MediaTransferHandler +- MediaOperationProgress +- UploadMediaError +- DownloadMediaError +- SendMessageOptions + +## v1.4.4 +v1.4.4 was released on December 24, 2021. + +Fixed an issue where the Agora Web SDK could reconnect to (with the connection status RECONNECTING) when the browser or tab was running in the background, if the Web SDK was used in Chrome 88 or higher. + +## v1.4.3 +v1.4.3 was released on May 27, 2021. #### Compatibility changes -This release changes the writing style of event listeners. After upgrading, you need to modify your implementation code as follows: +**Firewall domain whitelist** + +As of v1.4.3, the list of destination domains required for your firewall whitelist changes to the following: + + +- `.edge.agora.io` +- `.edge.sd-rtn.com` +- `web-1.ap.sd-rtn.com`` +- `web-2.ap.sd-rtn.com` +- `ap-web-1.agora.io` +- `ap-web-2.agora.io` +- `webcollector-rtm.agora.io` +- `logservice-rtm.agora.io` +- `rtm.statscollector.sd-rtn.com` +- `rtm.logservice.sd-rtn.com` + +If you upgrade the SDK to v1.4.3, update your firewall domain whitelist to ensure you can use Agora products in environments with restricted network access. + +#### New features + +**Regional connection** + +This release adds the `AgoraRTM.setArea` method for specifying the region for connection. After specifying the region, the SDK connects to the Agora servers within that region. The following regions are supported: + +- Mainland China +- North America +- Europe +- Asia, excluding Mainland China +- Japan +- India +- Global + +If you specify the region for connection as GLOBAL, you can use the excludeArea parameter in the AgoraRTM.setArea method to remove individual region from the regions for connection possibilities. + +#### API changes + +**Added** + +createInstance + + +**Deprecated** + +`createInstance`. Use createInstance. + +## v1.4.2 + +v1.4.2 was released on March 2, 2021. + +#### Compatibility changes -- Before v2.1.4: +**Behavioral changes** - ```javascript - rtmClient.addEventListener({ - message: msgEvent => { - // Message event notification processing logic - }, +- To better describe the behavior of the `setParameters` method in terms of naming, this version adds the `updateConfig` method, which is a duplicate of the `setParameters` method. The `updateConfig` method deprecates the `setParameters` method. +- When the size of `content` is greater than 8 KB, the `INVITATION_API_CALL_ERR_INVALID_ARGUMENT` error code is triggered when calling `send` instead of calling `setContent`. - presence: presenceEvent => { - // Presence event notification processing logic - }, +**Integration changes** - // Add other event listeners - }); - ``` +- As of this version, you must include the [js-sha1](https://www.npmjs.com/package/js-sha1) library in order to use the SDK to upload files or images in Microsoft Edge legacy or Internet Explorer 11 by one of the following methods: + - In the HTML file, expose js-sha1 to the global `sha1` variable: -- Since v2.1.4: + ``` xml + + ``` - ```javascript - rtmClient.addEventListener('message', msgEvent => { - // Message event notification processing logic - }); + - Add the following line to the JS file: - rtmClient.addEventListener('presence', presenceEvent => { - // Presence event notification processing logic - }); + ```javascript + window.sha1 = require('js-sha1') + ``` - // Add other event listeners - ``` +- The `isHistoricalMessage` member variable is removed from the `ReceivedMessageProperties` object. #### Improvements -This release reduces the response time of the `logout` method. +- The size of the decompressed SDK decreases by about 20%. +- (SDK from NPM only) The TS file in the SDK adds the following exports: + - `LocalInvitation` + - `RemoteInvitation` + - `RtmMessage` + - `RtmRawMessage` + - `RtmTextMessage` + - `RtmFileMessage` + - `RtmImageMessage` +- The SDK automatically adds the corresponding MIME type to the Blob type from `downloadMedia`. The SDK supports automatically detecting and adding the following MIME types: + - image/png + - image/gif + - application/pdf + - image/jpeg + - application/zip +#### API changes -#### Issues fixed +**Added** -This release fixes the following issues: +updateConfig -- The SDK version information was lost in the log file. -- The `userId` property of the `GetStateResponse` data type was null. -- After calling the `removeState` method, the SDK returned the `RemoveStateResponse` data type before the removing operation. +**Deprecated** -## v2.1.3 +`setParameters` -v2.1.3 was released on July 12, 2023. +**Removed** -This is the first release of the Signaling SDK for Web 2.x, which brings innovation in functional coverage, performance improvement, and experience optimization. +`isHistoricalMessage` member variable in `ReceivedMessageProperties` -- 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. +## v1.4.1 -- 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. +v1.4.1 was released on November 5, 2020. -- Experience optimization: v2.x includes the revamped and streamlined APIs that support the widely adopted Async/Await programming model. 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. +**New features** + +Fixed the performance issue when communicating with the Native SDK. + +## v1.4.0 + +v1.4.0 was released on September 25, 2020. + +**Compatibility changes** + +v1.4.0 supports only TypeScript 3.8 or higher. + + +**New features** + +Geofencing. You can use the `areaCodes` parameter in `createInstance` to set the region of the Agora . The can only connect to Agora servers within the specified region. + + +**API changes** + +#### Added + +The `areaCodes` parameter is added to createInstance. + + +## v1.3.1 + +v1.3.1 was released on August 7, 2020. + +**Fixed issues** + +- Connection stability issue between the Agora and the Agora system. +- The same offline message might be delivered multiple times. +- Login stability issue of the . +- Stability issue of sending and receiving peer-to-peer messages. +- The TokenExpired. callback could not be triggered in time. + + +## v1.3.0 + +v1.3.0 was released on June 16, 2020. + +**Compatibility changes** + +- The Agora server blocks any file message or image message that you send to 1.2.2 or earlier, or to the Signaling SDK. +- The typical timeout for asynchronously calling a method changes from 5 seconds to 10 seconds. +- You need to add port 9601 to the TCP protocol of the firewall whitelist to support sending and receiving file or image messages. See [Firewall Requirements](../reference/firewall). + +**New features** + +#### 1. Send and receive file messages or image messages + +You can call `createMediaMessageByUploading` to upload non-empty files or image files no greater than 30 MB. Each uploaded file or image stays in the Agora server for seven days. The SDK returns a media ID as the unique identifier of the file or image file. You can use the `RtmFileMessage` interface or the `RtmImageMessage` interface to save the media ID. The `RtmFileMessage` interface and the `RtmImageMessage` interface are type aliases of the `RtmMessage` interface, so you can send and receive file or image messages via peer-to-peer or channel message methods. You can call `downloadMedia` to download the received file or image file. + +#### 2. Manage upload or download tasks + +You can use the `mediaTransferHandler` interface to cancel or report the progress of an upload or download task. + +**Fixed issues** + +Fixed the login issues for some users. + +**API changes** + +#### Added + +- createMediaMessageByUploading. +- downloadMedia. +- createMessage. +- RtmImageMessage. +- RtmFileMessage. +- mediaTransferHandler. +- mediaOperationProgress. + + +## v1.2.2 + +v1.2.2 was released on February 21, 2020. + +**Compatibility Changes** + + +| Timeout | Before v1.2.2 | v1.2.2 | +| ---------------- | ---------------- | ---------------- | +| Send a channel message. | 5 s | 10 s | + + + +**Issues fixed** + +The SDK occasionally returns `LOGIN_ERR_UNKNOWN` when logging in from a recent version of Chrome on a Windows platform. + +## v1.2.1 + +v1.2.1 was released on December 17, 2019. + +**New Feature** + +*Compatible with the endCall method of the Agora Signaling SDK* + +If you use the `sendMessageToPeer` method to send a text message in the format of AgoraRTMLegacyEndcallCompatibleMessagePrefix_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore) in your additional information but you can set \ as empty "". + +**Issues Fixed** + + +- If a channel member reconnects to the Agora server after being interrupted, chances are the rest members of the channel can receive `MemberJoined` twice. + +## v1.2.0 + +v1.2.0 was released on November 15, 2019. + +**New Features** + +#### Subscribe to the online status of the specified user(s) + +When the method call succeeds, the SDK returns the PeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe. +When the online status of the peers, to whom you subscribe, changes, the SDK returns the PeersOnlineStatusChanged callback to report whose online status has changed. +If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the PeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server. + +#### Unsubscribe from the online status of the specified user(s) + +Allows you to unsubscribe from the online status of the specified user(s). + +#### Get a list of the peers, to whose specific status you have subscribed + +Allows you to get a list of the peers, to whose specific status you have subscribed. + +#### Create a raw message + +Creates and initializes a raw message to be sent. + + If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB. + +**Issues fixed** + +The SDK is occasionally kicked by the server: When the issue occurs, the Client instance receives the `ConnectionStateChange` callback, which indicates the connection state is `ABORTED` and the reason for the connection state change `INTERRUPTED`. The log file shows the error code from the server is 10001. + + +## v1.1.0 + +v1.1.0 was released on September 18, 2019. It adds the following features: + +- [Gets the member count of specified channel(s).](#getcount) +- [Automatically returns the latest numer of members in the current channel](#oncount) +- [Channel attribute operations](#channelattributes) + + + +**Compatibility Changes** + +1. The getServerReceivedTs method of the RtmMessage object supports both peer-to-peer and channel messages. +2. Timeout for sending a peer-to-peer message is 10 seconds from this release, compared to 5 seconds in previous versions. See PEER_MESSAGE_ERR_TIMEOUT. + +**New Features** + + +#### 1. Gets the member count of specified channel(s). + +You can now get the member count of specified channel(s) without the need to join, by calling the `getChannelMemberCount` method. You can get the member counts of a maximum of 32 channels in one method call. + + +#### 2. Automatically returns the latest numer of members in the current channel + +If you are already in a channel, you do not have to call the `getChannelMemberCount` method to get the member count of the current channel. We also do not recommend using `onMemberJoined` and `onMemberLeft` to keep track of the member counts. As of this release, the SDK returns to the channel members `MemberCountUpdated` the latest channel member count when the number of channel members changes. Note that: + +- When the number of channel members ≤ 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once per second. +- When the number of channel members exceeds 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once every three seconds. + + +#### 3. Channel attribute operations + +Supports setting or getting the attribute(s) of a specified channel. You can use this feature to create group anouncement. + +Each channel attribute comes as a key-value pair. Where: + +- The key of each channel attribute must be visible characters and not exceed 8 KB. +- Each channel attribute must not exceed 8 KB in length. +- The overall size of the attributes of a channel must not exceed 32 KB. +- The number of attributes of a channel must not exceed 32. + +Specific features: + +- Sets the attributes of a specified channel with new ones. +- Adds or updates the attribute(s) of a specified channel. +- Deletes the attributes of a specified channel by attribute keys. +- Clears all attributes of a specified channel. +- Gets all attributes of a specified channel. +- Gets the attributes of a specified channel by attribute keys. + +When updating attributes of a channel, you can use the `enableNotificationToChannelMembers` flag to decide whether or not to notify all members of the channel about this attribute change. + +**Improvements** + +#### Resends peer-to-peer messages + +This release improves the resending mechanism of peer-to-peer messages, and extends the timeout for sending a peer-to-peer message from five to 10 seconds, greatly improving the success rate of peer-to-peer message sending under weak network conditions. + +#### Caches channel messages + +The Agora system will resend a maximum of 32 channel messages of up to 30 seconds to channel members, when they manage to reconnect to the system from poor network conditions. This greatly improves the overall arrival rate of channel messages under weak network conditions. + + +**API Changes** + +#### Added Methods + +- setChannelAttributes: Sets the attributes of a specified channel with new ones. +- addOrUpdateChannelAttributes: Adds or updates the attribute(s) of a specified channel. +- deleteChannelAttributesByKeys: Deletes the attributes of a specified channel by attribute keys. +- clearChannelAttributes: Clears all attributes of a specified channel. +- getChannelAttributes: Gets all attributes of a specified channel. +- getChannelAttributesByKeys: Gets the attributes of a specified channel by attribute keys. +- getChannelMemberCount: Gets the member count of specified channel(s). + +#### Added Callbacks + +- AttributesUpdated: Returns all attributes of the channel when the channel attributes are updated. +- MemberCountUpdated: Occurs when the number of the channel members changes, and returns the new number. + +#### Added Error Codes + +- GetChannelMemberCountErrCode: Error codes related to retrieving the channel member count of specified channel(s). +- JOIN_CHANNEL_ERR_JOIN_SAME_CHANNEL_TOO_OFTEN: The frequency of joining the same channel exceeds two times every five seconds. +- JOIN_CHANNEL_ERR_ALREADY_JOINED_CHANNEL_OF_SAME_ID: You have already joined another channel instance of the same channel ID. + + + + + + + +## v1.0.1 + +v1.0.1 was released on September 5, 2019. + +**Issues Fixed** + +- Peer-to-peer messages have a chance to become offline messages even if enableOfflineMessaging is not set. +- The local user has a chance of not being able to retrieve the latest user attributes of a remote user, if the remote user updates his/her attributes immediately after logging in the Agora system. + +**Improvements** + +- Caches up to six seconds of peer-to-peer messages sent when the network is interrupted, and resends the cached messages immediately after the SDK reconnects to the Agora system. +- Timeout for sending a peer-to-peer message is reset to 10 seconds. + +## v1.0.0 + +v1.0.0 was released on August 5th, 2019. + +**New Features** + +#### Interconnects with the legacy Agora Signaling SDK + +v1.0.0 implements the `LocalInvitation.channelId` and `LocalInvitation.channelId` property. + +> - To intercommunicate with the legacy Agora Signaling SDK, you MUST set the channel ID. However, even if the callee successfully accepts the call invitation, the Agora does not join the channel of the specified channel ID. +> - If your App does not involve the legacy Agora Signaling SDK, we recommend using the `LocalInvitation.content` or the `RemoteInvitation.response` property to set customized contents. + + +#### Sets the output log level of the SDK + +Supports setting the output log level of the SDK using the `logFilter` parameter. The log level follows the sequence of OFF, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels ERROR and WARNING. + + +#### API Changes + +#### Adds + +- logFilter +- setParameters + + + +## v0.9.3 + +v0.9.3 was released on July 24th, 2019. + +**New Features** + +#### Sends an (offline) peer-to-peer message to a specified user (receiver) + +This version allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one. + + +#### User attribute-related operations + +This version allows you to set or update a user's attributes. You can: + +- Substitutes the local user's attributes with new ones. +- Adds or updates the local user's attribute(s). +- Deletes the local user's attributes using attribute keys. +- Clears all attributes of the local user. +- Gets all attributes of a specified user. +- Gets the attributes of a specified user using attribute keys. + +> The attributes you set will be cleard when you log out of . + + +#### Queries the Online Status of the Specified Users + +This release introduces a new concept: online and offline. + +- Online: The user has logged in the Agora system. +- Offline: The user has logged out of the Agora system. + +This release adds the function of querying the online status of the specified users. After logging in the Agora system, you can get the online status of a maximum of 256 specified users. + + +#### Renews the Token + +This release allows you to renew a token. + +**API Changes** + +#### Adds + +- sendMessageToPeer +- setLocalUserAttributes +- addOrUpdateLocalUserAttributes +- deleteLocalUserAttributesByKeys +- clearLocalUserAttributes +- getUserAttributes +- getUserAttributesByKeys +- queryPeersOnlineStatus +- renewToken + +## v0.9.1 + +v0.9.1 was released on May 20th, 2019. + +**New Features** + +This release adds the call invitation feature, allowing you to create, send, cancel, accept, and decline a call invitation in a one-to-one or one-to-many voice/video call. + + + +**API Changes** + +#### Adds + +- createLocalInvitation: Creates a call invitation. +- LocalInvitation.send: Allows the caller to send a call invitation to a specified user (callee). +- LocalInvitation.cancel Allows the caller to cancel a sent call invitation. +- LocalInvitationState: **RETURNED TO THE CALLER** Call invitation status codes. +- LocalInvitationFailureReason: **RETURNED TO THE CALLER** Reason for failure of the outgoing call invitation. +- RemoteInvitationReceived: Occurs when the callee receives a call invitation. +- RemoteInvitation.accept: Allows the callee to accept an incoming call invitation. +- RemoteInvitation.refuse: Allows the callee to declien an incoming call invitation. +- RemoteInvitationState: **RETURNED TO THE CALLEE**: Call invitation status codes. +- RemoteInvitationFailureReason: **RETURNED TO THE CALLEE**: Reason for the failure of the incoming call invitation. + +#### Renames + +- `RtmClient.ConnectionStateChange` to ConnectionStateChanged . + +#### Deletes + +- The `RtmChannel.getId()` method. Uses the channelId property instead. + +## v0.9.0 + +v0.9.0 was released on February 14th, 2019. + +Initial version. + +**Key features** + +- Sends or receives peer-to-peer messages. +- Joins or leaves a channel. +- Sends or receives channel messages. + + + +- The size of the decompressed SDK decreases by about 20%. +- (SDK from NPM only) The TS file in the SDK adds the following exports: + - `LocalInvitation` + - `RemoteInvitation` + - `RtmMessage` + - `RtmRawMessage` + - `RtmTextMessage` + - `RtmFileMessage` + - `RtmImageMessage` +- The SDK automatically adds the corresponding MIME type to the Blob type from `downloadMedia`. The SDK supports automatically detecting and adding the following MIME types: + - image/png + - image/gif + - application/pdf + - image/jpeg + - application/zip + +#### API changes + +**Added** + +updateConfig + +**Deprecated** + +`setParameters` + +**Removed** + +`isHistoricalMessage` member variable in `ReceivedMessageProperties` + +## v1.4.1 + +v1.4.1 was released on November 5, 2020. + +**New features** + +Fixed the performance issue when communicating with the Native SDK. + +## v1.4.0 + +v1.4.0 was released on September 25, 2020. + +**Compatibility changes** + +v1.4.0 supports only TypeScript 3.8 or higher. + + +**New features** + +Geofencing. You can use the `areaCodes` parameter in `createInstance` to set the region of the Agora . The can only connect to Agora servers within the specified region. + + +**API changes** + +#### Added + +The `areaCodes` parameter is added to createInstance. + + +## v1.3.1 + +v1.3.1 was released on August 7, 2020. + +**Fixed issues** + +- Connection stability issue between the Agora and the Agora system. +- The same offline message might be delivered multiple times. +- Login stability issue of the . +- Stability issue of sending and receiving peer-to-peer messages. +- The TokenExpired. callback could not be triggered in time. + + +## v1.3.0 + +v1.3.0 was released on June 16, 2020. + +**Compatibility changes** + +- The Agora server blocks any file message or image message that you send to 1.2.2 or earlier, or to the Signaling SDK. +- The typical timeout for asynchronously calling a method changes from 5 seconds to 10 seconds. +- You need to add port 9601 to the TCP protocol of the firewall whitelist to support sending and receiving file or image messages. See [Firewall Requirements](../reference/firewall). + +**New features** + +#### 1. Send and receive file messages or image messages + +You can call `createMediaMessageByUploading` to upload non-empty files or image files no greater than 30 MB. Each uploaded file or image stays in the Agora server for seven days. The SDK returns a media ID as the unique identifier of the file or image file. You can use the `RtmFileMessage` interface or the `RtmImageMessage` interface to save the media ID. The `RtmFileMessage` interface and the `RtmImageMessage` interface are type aliases of the `RtmMessage` interface, so you can send and receive file or image messages via peer-to-peer or channel message methods. You can call `downloadMedia` to download the received file or image file. + +#### 2. Manage upload or download tasks + +You can use the `mediaTransferHandler` interface to cancel or report the progress of an upload or download task. + +**Fixed issues** + +Fixed the login issues for some users. + +**API changes** + +#### Added + +- createMediaMessageByUploading. +- downloadMedia. +- createMessage. +- RtmImageMessage. +- RtmFileMessage. +- mediaTransferHandler. +- mediaOperationProgress. + + +## v1.2.2 + +v1.2.2 was released on February 21, 2020. + +**Compatibility Changes** + + +| Timeout | Before v1.2.2 | v1.2.2 | +| ---------------- | ---------------- | ---------------- | +| Send a channel message. | 5 s | 10 s | + + + +**Issues fixed** + +The SDK occasionally returns `LOGIN_ERR_UNKNOWN` when logging in from a recent version of Chrome on a Windows platform. + +## v1.2.1 + +v1.2.1 was released on December 17, 2019. + +**New Feature** + +*Compatible with the endCall method of the Agora Signaling SDK* + +If you use the `sendMessageToPeer` method to send a text message in the format of AgoraRTMLegacyEndcallCompatibleMessagePrefix_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore) in your additional information but you can set \ as empty "". + +**Issues Fixed** + + +- If a channel member reconnects to the Agora server after being interrupted, chances are the rest members of the channel can receive `MemberJoined` twice. + +## v1.2.0 + +v1.2.0 was released on November 15, 2019. + +**New Features** + +#### Subscribe to the online status of the specified user(s) + +When the method call succeeds, the SDK returns the PeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe. +When the online status of the peers, to whom you subscribe, changes, the SDK returns the PeersOnlineStatusChanged callback to report whose online status has changed. +If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the PeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server. + +#### Unsubscribe from the online status of the specified user(s) + +Allows you to unsubscribe from the online status of the specified user(s). + +#### Get a list of the peers, to whose specific status you have subscribed + +Allows you to get a list of the peers, to whose specific status you have subscribed. + +#### Create a raw message + +Creates and initializes a raw message to be sent. + + If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB. + +**Issues fixed** + +The SDK is occasionally kicked by the server: When the issue occurs, the Client instance receives the `ConnectionStateChange` callback, which indicates the connection state is `ABORTED` and the reason for the connection state change `INTERRUPTED`. The log file shows the error code from the server is 10001. + + +## v1.1.0 + +v1.1.0 was released on September 18, 2019. It adds the following features: + +- [Gets the member count of specified channel(s).](#getcount) +- [Automatically returns the latest numer of members in the current channel](#oncount) +- [Channel attribute operations](#channelattributes) + + + +**Compatibility Changes** + +1. The getServerReceivedTs method of the RtmMessage object supports both peer-to-peer and channel messages. +2. Timeout for sending a peer-to-peer message is 10 seconds from this release, compared to 5 seconds in previous versions. See PEER_MESSAGE_ERR_TIMEOUT. + +**New Features** + + +#### 1. Gets the member count of specified channel(s). + +You can now get the member count of specified channel(s) without the need to join, by calling the `getChannelMemberCount` method. You can get the member counts of a maximum of 32 channels in one method call. + + +#### 2. Automatically returns the latest numer of members in the current channel + +If you are already in a channel, you do not have to call the `getChannelMemberCount` method to get the member count of the current channel. We also do not recommend using `onMemberJoined` and `onMemberLeft` to keep track of the member counts. As of this release, the SDK returns to the channel members `MemberCountUpdated` the latest channel member count when the number of channel members changes. Note that: + +- When the number of channel members ≤ 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once per second. +- When the number of channel members exceeds 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once every three seconds. + + +#### 3. Channel attribute operations + +Supports setting or getting the attribute(s) of a specified channel. You can use this feature to create group anouncement. + +Each channel attribute comes as a key-value pair. Where: + +- The key of each channel attribute must be visible characters and not exceed 8 KB. +- Each channel attribute must not exceed 8 KB in length. +- The overall size of the attributes of a channel must not exceed 32 KB. +- The number of attributes of a channel must not exceed 32. + +Specific features: + +- Sets the attributes of a specified channel with new ones. +- Adds or updates the attribute(s) of a specified channel. +- Deletes the attributes of a specified channel by attribute keys. +- Clears all attributes of a specified channel. +- Gets all attributes of a specified channel. +- Gets the attributes of a specified channel by attribute keys. + +When updating attributes of a channel, you can use the `enableNotificationToChannelMembers` flag to decide whether or not to notify all members of the channel about this attribute change. + +**Improvements** + +#### Resends peer-to-peer messages + +This release improves the resending mechanism of peer-to-peer messages, and extends the timeout for sending a peer-to-peer message from five to 10 seconds, greatly improving the success rate of peer-to-peer message sending under weak network conditions. + +#### Caches channel messages + +The Agora system will resend a maximum of 32 channel messages of up to 30 seconds to channel members, when they manage to reconnect to the system from poor network conditions. This greatly improves the overall arrival rate of channel messages under weak network conditions. + + +**API Changes** + +#### Added Methods + +- setChannelAttributes: Sets the attributes of a specified channel with new ones. +- addOrUpdateChannelAttributes: Adds or updates the attribute(s) of a specified channel. +- deleteChannelAttributesByKeys: Deletes the attributes of a specified channel by attribute keys. +- clearChannelAttributes: Clears all attributes of a specified channel. +- getChannelAttributes: Gets all attributes of a specified channel. +- getChannelAttributesByKeys: Gets the attributes of a specified channel by attribute keys. +- getChannelMemberCount: Gets the member count of specified channel(s). + +#### Added Callbacks + +- AttributesUpdated: Returns all attributes of the channel when the channel attributes are updated. +- MemberCountUpdated: Occurs when the number of the channel members changes, and returns the new number. + +#### Added Error Codes + +- GetChannelMemberCountErrCode: Error codes related to retrieving the channel member count of specified channel(s). +- JOIN_CHANNEL_ERR_JOIN_SAME_CHANNEL_TOO_OFTEN: The frequency of joining the same channel exceeds two times every five seconds. +- JOIN_CHANNEL_ERR_ALREADY_JOINED_CHANNEL_OF_SAME_ID: You have already joined another channel instance of the same channel ID. + + + + + + + +## v1.0.1 + +v1.0.1 was released on September 5, 2019. + +**Issues Fixed** + +- Peer-to-peer messages have a chance to become offline messages even if enableOfflineMessaging is not set. +- The local user has a chance of not being able to retrieve the latest user attributes of a remote user, if the remote user updates his/her attributes immediately after logging in the Agora system. + +**Improvements** + +- Caches up to six seconds of peer-to-peer messages sent when the network is interrupted, and resends the cached messages immediately after the SDK reconnects to the Agora system. +- Timeout for sending a peer-to-peer message is reset to 10 seconds. + +## v1.0.0 + +v1.0.0 was released on August 5th, 2019. + +**New Features** + +#### Interconnects with the legacy Agora Signaling SDK + +v1.0.0 implements the `LocalInvitation.channelId` and `LocalInvitation.channelId` property. + +> - To intercommunicate with the legacy Agora Signaling SDK, you MUST set the channel ID. However, even if the callee successfully accepts the call invitation, the Agora does not join the channel of the specified channel ID. +> - If your App does not involve the legacy Agora Signaling SDK, we recommend using the `LocalInvitation.content` or the `RemoteInvitation.response` property to set customized contents. + + +#### Sets the output log level of the SDK + +Supports setting the output log level of the SDK using the `logFilter` parameter. The log level follows the sequence of OFF, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels ERROR and WARNING. + + +#### API Changes + +#### Adds + +- logFilter +- setParameters - -Please note that as Signaling v2.1.3 is currently in public beta, certain specific functionalities may be subject to future changes aimed at improving the overall user experience. - -#### New features -v2.1.3 provides the following core functional modules: +## v0.9.3 -**Initial configuration** +v0.9.3 was released on July 24th, 2019. - 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: +**New Features** -- `new RTM`: 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. - - `rtmConfig`: - - `token`: Set the token for user authentication. - - `encryptionMode`: Specify the end-to-end encryption mode. - - `cipherKey`: Set the encryption key for end-to-end encryption. - - `salt`: Set the salt for end-to-end encryption. - - `heartbeatInterval`: Define the interval for end-to-end heartbeat keep-alive. - - `logUpload`: Configure whether to enable log upload. - - `logFilter`: Set the level for log filtering. - - `cloudProxy`: Configure whether to enable cloud proxy. - - `useStringUserId`: Specify whether to use a string type user ID. -- Event handling: Implement event notification for the events such as `OnMessageEvent`, `OnPresenceEvent`, `OnStorageEvent`, `OnTopicEvent`, `OnLockEvent`, `OnConnectionStateChange`, `OnTokenPrivilegeWillExpire`. -- `LoginAsync`: Log into the RTM service. -- `LogoutAsync`: Log out of the RTM service. +#### Sends an (offline) peer-to-peer message to a specified user (receiver) -**Channel** +This version allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one. -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 ms. 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 channel, message channel and stream channel, each offering distinct core capabilities as follows: +#### User attribute-related operations -- Message channel: - - `SubscribeAsync`: Subscribe to the specified message channel and receive messages and event notifications in the channel. - - `UnsubscribeAsync`: Unsubscribe from the specified message channel and stop receiving messages and event notifications in the channel. +This version allows you to set or update a user's attributes. You can: -- Stream channel: - - `CreateStreamChannel`: Create a stream channel instance and then call relevant APIs. - - `JoinAsync`: Join the stream channel and receive messages and event notifications in the channel. - - `LeaveAsync`: Leave the stream channel and stop receiving messages and event notifications in the channel. +- Substitutes the local user's attributes with new ones. +- Adds or updates the local user's attribute(s). +- Deletes the local user's attributes using attribute keys. +- Clears all attributes of the local user. +- Gets all attributes of a specified user. +- Gets the attributes of a specified user using attribute keys. -- The `SubscribeAsync`, `UnsubscribeAsync`, `JoinAsync`, and `LeaveAsync` methods trigger the `OnPresenceEvent` event notification. Other users in the channel receive corresponding `Join` and `Leave` event notifications. -- When calling `SubscribeAsync` and `JoinAsync` 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 attributes you set will be cleard when you log out of . -**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. +#### Queries the Online Status of the Specified Users -Call `PublishAsync` to send a message to the specified message channel. Calling `PublishAsync` triggers the `OnMessageEvent` event notification. If you want to receive messages in the channel, set `withMessage` to `true` when calling `SubscribeAsync` and register the event handler for the `OnMessageEvent` event. +This release introduces a new concept: online and offline. -**Topic** +- Online: The user has logged in the Agora system. +- Offline: The user has logged out of the Agora system. -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: +This release adds the function of querying the online status of the specified users. After logging in the Agora system, you can get the online status of a maximum of 256 specified users. -- `JoinTopicAsync`: Register as the publisher of this topic to gain the ability to send messages. -- `PublishTopicMessageAsync`: Send a message to the topic in the stream channel. -- `LeaveTopicAsync`: Unregister as the message publisher of this topic. -- `SubscribeTopicAsync`: Subscribe to one or more message publishers of the topic in this channel. -- `UnsubscribeTopicAsync`: Unsubscribe from this topic or unsubscribe from one or more message publishers in this topic. -Register (`JoinTopicAsync`) and unregister (`LeaveTopicAsync`) as a message publisher trigger the `OnTopicEvent` event notification that is sent to other users in the channel. +#### Renews the Token -Topics exist only in stream channels, not in message channels. +This release allows you to renew a token. -**Presence** +**API Changes** -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: +#### Adds -- Get the list of online users in a channel. -- Get the list of channels that an online user joins. -- Dynamically monitor user joining or leaving a channel. -- Dynamically monitor changes of the temporary status of online users. +- sendMessageToPeer +- setLocalUserAttributes +- addOrUpdateLocalUserAttributes +- deleteLocalUserAttributesByKeys +- clearLocalUserAttributes +- getUserAttributes +- getUserAttributesByKeys +- queryPeersOnlineStatus +- renewToken -The following features can be used in both message channels and stream channels: +## v0.9.1 -- `WhoNowAsync`: Get real-time information about the number of online users, the list of online users, and their temporary status in a specified channel. -- `WhereNowAsync`: Get real-time information about the list of channels in which a specific user joins. -- `SetStateAsync`: Set the temporary status of a user in a specified channel. -- `GetStateAsync`: Get the temporary status of a user in a specified channel. -- `RemoveStateAsync`: Remove the temporary status of a user in a specific channel. +v0.9.1 was released on May 20th, 2019. -In addition, presence also provides event notification capabilities through `OnPresenceEvent`. Events such as users joining, leaving, 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. +**New Features** -**Storage** +This release adds the call invitation feature, allowing you to create, send, cancel, accept, and decline a call invitation in a one-to-one or one-to-many voice/video call. -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 - - `SetChannelMetadataAsync`: Set the channel metadata or channel metadata item for a specified channel. - - `GetChannelMetadataAsync`: Retrieve the channel metadata and channel metadata item for a specified channel. - - `RemoveChannelMetadataAsync`: Delete the channel metadata or channel metadata item for a specified channel. - - `UpdateChannelMetadataAsync`: Update the existing channel metadata or channel metadata item for a specified channel. +**API Changes** - 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. +#### Adds - 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. +- createLocalInvitation: Creates a call invitation. +- LocalInvitation.send: Allows the caller to send a call invitation to a specified user (callee). +- LocalInvitation.cancel Allows the caller to cancel a sent call invitation. +- LocalInvitationState: **RETURNED TO THE CALLER** Call invitation status codes. +- LocalInvitationFailureReason: **RETURNED TO THE CALLER** Reason for failure of the outgoing call invitation. +- RemoteInvitationReceived: Occurs when the callee receives a call invitation. +- RemoteInvitation.accept: Allows the callee to accept an incoming call invitation. +- RemoteInvitation.refuse: Allows the callee to declien an incoming call invitation. +- RemoteInvitationState: **RETURNED TO THE CALLEE**: Call invitation status codes. +- RemoteInvitationFailureReason: **RETURNED TO THE CALLEE**: Reason for the failure of the incoming call invitation. -- User metadata +#### Renames - - `SetUserMetadataAsync`: Set the user metadata or a user metadata item for a specified user. - - `GetUserMetadataAsync`: Retrieve the user metadata or a user metadata item for a specified user. - - `RemoveUserMetadataAsync`: Delete the user metadata or a user metadata item for a specified user. - - `UpdateUserMetadataAsync`: Update the existing user metadata or a user metadata item for a specified user. - - `SubscribeUserMetadataAsync`: Subscribe to event notifications for changes in user metadata or a user metadata item for a specified user. - - `UnsubscribeUserMetadataAsync`: Unsubscribe from event notifications for changes in user metadata or a user metadata item for a specified user. +- `RtmClient.ConnectionStateChange` to ConnectionStateChanged . - 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. +#### Deletes -- Compare And Set (CAS) control +- The `RtmChannel.getId()` method. Uses the channelId property instead. - 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: +## v0.9.0 - - By using the `majorRevision` property in the `RtmMetadata` class, you can enable version number verification for the metadata array. - - By using the `revision` property in the `MetadataItem` class within `RtmMetadata`, you can enable version number verification for each metadata item array. +v0.9.0 was released on February 14th, 2019. - 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: +Initial version. - - 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. +**Key features** -- Lock +- Sends or receives peer-to-peer messages. +- Joins or leaves a channel. +- Sends or receives channel messages. - 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: - - `SetLockAsync`: Set a lock for a specified channel. - - `AcquireLockAsync`: Acquire a specified lock in a specified channel. - - `ReleaseLockAsync`: Release a specified lock in a specified channel. - - `RevokeLockAsync`: Revoke the ownership of a specific user for a lock in a specified channel to release the lock. - - `GetLocksAsync`: Retrieve the details of all locks in a specified channel. - - `RemoveLockAsync`: Delete a specified lock in a specified channel. - \ No newline at end of file + diff --git a/shared/signaling/release-notes/windows.mdx b/shared/signaling/release-notes/windows.mdx new file mode 100644 index 000000000..303390e91 --- /dev/null +++ b/shared/signaling/release-notes/windows.mdx @@ -0,0 +1,387 @@ + + + + +## v1.5.1 + +v1.5.1 was released on September 1, 2022 and improved the stability of the SDK. + +### v1.5.0 +v1.5.0 was released on July 27, 2022. + +#### Sunset features +Image or file messages, historical messages, and offline messages are deprecated as of this release. If you have integrated these features in a previous release, you can continue to use them. + +#### API changes + +The following methods are deprecated: + +- createFileMessageByMediaId +- createFileMessageByUploading +- createImageMessageByMediaId +- createImageMessageByUploading +- cancelMediaUpload +- cancelMediaDownload +- downloadMediaToMemory +- downloadMediaToFile +- enableOfflineMessaging +- enableHistoricalMessaging +- onFileMessageReceived +- onFileMessageReceivedFromPeer +- onImageMessageReceived +- onImageMessageReceivedFromPeer +- onMediaUploadingProgress +- onMediaDownloadingProgress + +### v1.4.10 +v1.4.10 was released on March 01, 2022. + + +#### Issues fixed + +Fixed some rich media related crashes. +### v1.4.9 +v1.4.9 was released on November 26, 2021. + +#### Improvements + +Improved the login success rate and connection stability under the IPv4/IPv6 dual-stack network. + +## v1.4.7 +v1.4.7 was released on July 19, 2021. + +Improved the success rate of logins and message delivery for the in poor network conditions. + +## v1.4.6 + +v1.4.6 was released on June 21, 2021. + +Fixed some issues that may cause crashes to improve stability. + +## v1.4.5 + +v1.4.5 was released on April 30, 2021. + +#### Improvements + +Fixed some issues that may cause crashes to improve stability. + +## v1.4.4 + +v1.4.4 was released on April 20, 2021. + +#### Improvements + +Improved the success rate of logins and message delivery for the in poor network conditions. + +#### Issues fixed + +Fixed some issues that might cause the system to crash. + +## v1.4.3 + +v1.4.3 was released on February 10, 2021. + +#### Issues fixed + +This release fixed the following issues: + +- Crash issues caused by occasional multi-thread access conflict. +- High timeout rate for login operations. + +## v1.4.2 + +v1.4.2 was released on November 23, 2020. + +**Improvements** + +- Improved performance of login and messaging operations. +- Added the `AGORA_SDK_BOTH_RTM_AND_RTC` macro for the `RTM_AREA_CODE` enum type. You can use the macro to resolve naming conflicts when using and together. + +## v1.4.1 + +v1.4.1 was released on September 30, 2020. + +**Improvements** + +Improved the log file. + + +## v1.4.0 + +v1.4.0 was released on September 1, 2020. + +**Compatibility changes** + +- You need to add new ports to the firewall whitelist. See [Firewall Requirements](../reference/firewall). + - New TCP ports: 8443, 9136, 9137, 9141. New UDP port: 8443. Reason: Support real-time transport encryption. + - New UDP ports: 8130, 9120, 9121. Reason: Support UDP path to improve the SDK's performance in sub-optimal network conditions. + - New UDP port: 9700. Reason: Support data reporting. +- In `setLogFileSize`, the default log file size increases from 512 KB to 10 MB. The maximum log file size increases from 10 MB to 1 GB. + +**New features** + +- Geofencing. You can call `setRtmServiceContext` to set the region of the Agora . The can only connect to Agora servers within the specified region. +- Transport Layer Security (TLS) encryption. + +**Improvements** + +- Improved the success rate of login and message delivery of the in poor network conditions. +- Optimized the reconnection mechanism. + +**API changes** + +#### New methods + +setRtmServiceContext + +## v1.3.0 + +v1.3.0 was released on May 8, 2020. + +**Compatibility changes** + +- You need to add a new TCP port, 9140, to the firewall whitelist. The port is for sending and receiving image or file messages. See [Firewall Requirements](../reference/firewall). +- The Agora server blocks any file message or image message that you send to 1.2.2 or earlier, or to the Signaling SDK. + +**New features** + +#### 1. Send and receive file messages + +v1.3.0 supports downloading non-empty files that are smaller than 30 MB. You can cancel an ongoing upload or download process at any time. Each file you upload to the Agora server corresponds to a media ID. The file stays on the Agora server for seven days. You can use the media ID to download the file as long as the it is still on the Agora server. + +You can only download files using the methods provided by the SDK. + +v1.3.0 adds the `IFileMessage` message class for saving and transferring a media ID. The `IFileMessage` class inherits from the `IMessage` class, so you can use the existing peer-to-peer or channel messaging methods to transfer the `IFileMessage` instance. You can use the `IFileMessage` object to complete the following tasks: + +- Set the filename and thumbnail of the uploaded file. +- Get the size of the uploaded file. + +
The total size of the message content, the filename, and the thumbnail must not exceed 32 KB.
+ +#### 2. Send and receive image messages + +v1.3.0 supports downloading non-empty image files that are smaller than 30 MB. You can cancel an ongoing upload or download process at any time. Each image you upload to the Agora server corresponds to a media ID. The image file stays on the Agora server for seven days. You can use the media ID to download the image file as long as it is still on the Agora server. + +
You can only download image files using the download methods provided by the SDK.
+ +v1.3.0 adds the `IImageMessage` message class for saving and transferring a media ID. The `IImageMessage` class inherits from the `IMessage` class, so you can use the existing peer-to-peer or channel messaging methods to transfer the `IImageMessage` instance. You can use the `IImageMessage` object to complete the following tasks: + +- Set the filename and thumbnail of the uploaded image file. +- Get the size of the uploaded image file. +- Get the SDK-calculated width and height of image files in JPEG, JPG, BMP, or PNG format. +- Set the width or height of image files. The width or height you set overwrites the width or height that the SDK calculates. + +
The total size of the message content, the filename, and the thumbnail must not exceed 32 KB.
+ +#### 3. Report the progress of upload or download + +The SDK returns the progress of an upload or download by callback every second during a task in progress. If the upload or download task pauses, the SDK ceases to return any further callback until the task continues. + +**Bug fixes** + +- Login failure caused by the SDK's incorrect identification of user's network type. +- Other problems that may cause the system to crash. + +**API changes** + +#### New methods + +- createFileMessageByUploading +- createImageMessageByUploading +- cancelMediaUpload +- cancelMediaDownload +- createFileMessageByMediaId +- createImageMessageByMediaId +- downloadMediaToMemory +- downloadMediaToFile + +#### New callbacks + +- onMediaUploadingProgress +- onMediaDownloadingProgress +- onMediaCancelResult +- onFileMediaUploadResult +- onImageMediaUploadResult +- onFileMessageReceivedFromPeer +- onImageMessageReceivedFromPeer +- onFileMessageReceived +- onImageMessageReceived +- onMediaDownloadToMemoryResult +- onMediaDownloadToFileResult + +#### Deprecated methods + +sendMessage is deprecated. Use sendMessage (const IMessage *message, const SendMessageOptions &options) instead. + +## v1.2.2 + +v1.2.2 was released on December 13, 2019. + + +**Compatibility Changes** + +This release deprecates the createAgoraService method, which creates an IAgoraService instance, and the initialize method, which initializes the created IAgoraService instance. As of this relase, you only need to call the createRtmService method and the initialize method to initialize it before being able to call its functions. + + +**Issues Fixed** + +Occasionally fails to receive any callback after a channel attribute operation. + +## v1.2.1 + +v1.2.1 was released on November 29, 2019. + +**New Feature** + +*Compatible with the endCall method of the Agora Signaling SDK* + +If you use the `sendMessageToPeer` method to send a text message in the format of AgoraRTMLegacyEndcallCompatibleMessagePrefix_\_\, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \ with the channel ID from which you want to leave (end call), and replace \ with any additional information. Note that you must not put any "_" (underscore) in your additional information but you can set \ as empty "". + +**Issues Fixed** + + +- The SDK fails to reconnect to the Agora system if the user disables VPN. +- If a channel member reconnects to the Agora server after being interrupted, chances are the rest members of the channel can receive `onMemberJoined` twice. + +## v1.2.0 + +v1.2.0 was released on November 6, 2019. + +**Compatibility Changes** + +Deprecated the `isOnline` property of the `PeerOnlineStatus`. Use `onlineState` instead. + + +**New Features** + +#### Subscribe to the online status of the specified user(s) + +When the method call succeeds, the SDK returns the onPeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe. +When the online status of the peers, to whom you subscribe, changes, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed. +If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server. + +#### Unsubscribe from the online status of the specified user(s) + +Allows you to unsubscribe from the online status of the specified user(s). + +#### Get a list of the peers, to whose specific status you have subscribed + +Allows you to get a list of the peers, to whose specific status you have subscribed. + +#### Create a raw message + +Creates and initializes a raw message to be sent. + + If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB. + + + + + + +## v1.1.0 + +v1.1.0 was released on September 30, 2019. It added the following features: + +**Send an (offline) peer-to-peer message to a specified user** + +This version allows you to send a message to a specified user when that user is offline. If you set a message as an offline message and the specified user is offline when you send it, the server caches it. Please note that we only cache 200 offline messages for up to seven days for each receiver. If the number of the cached messages reaches this limit, the newest message overrides the oldest one. + + + + + +**Get the member count of specified channel(s)** + +Use the getChannelMemberCount method get the member count of specified channel(s) without the need to join them. One method call can get the member counts of a maximum of 32 channels. + +**Query the online status of the specified users** + +**User attribute operations** + +This version enables you to set or update a user's attributes. Please note: + +- Only after you successfully logging in the Agora system can you execute user attribute-related operations. Otherwise, the SDK triggers the `ATTRIBUTE_OPERATION_ERR_NOT_LOGGED_IN` error code. +- The attributes you set will be cleared when you log out of . +- You can only set a maximum of 16 KB attributes in a single method call. Otherwise, the SDK triggers the `ATTRIBUTE_OPERATION_ERR_SIZE_OVERFLOW` error code. + +You can do the following: + +- Substitute the local user's attributes with new ones. +- Add or update the local user's attribute(s). +- Use attribute keys to delete the local user's attributes. +- Clear all attributes of the local user. +- Get all attributes of a specified user. +- Use attribute keys to get the attributes of a specified user. + +**Channel attribute operations** + +This version enables you to set or get the attribute(s) of a specified channel. You can use this feature to create group announcements. + +Each channel attribute exists as a key-value pair. See IRtmChannelAttribute for more information. Please note: + +- The key for each channel attribute must be printable characters and not exceed 8 KB. +- Each channel attribute must not exceed 8 KB in length. +- The overall size of the attributes of a channel must not exceed 32 KB. +- The number of attributes of a channel must not exceed 32. + +You can do the following: + +- Substitute the attributes of a specified channel with new ones. +- Adds or update the attribute of a specified channel. +- Use attribute keys to deletes the attributes of a specified channel. +- Clear all attributes of a specified channel. +- Get all attributes of a specified channel. +- Use attribute keys to get the attributes of a specified channel. + +> The enableNotificationToChannelMembers flag decides whether to notify all members of a channel about this attribute change. + +**Call invitation** + +This version enables you to create, send, cancel, accept, and decline a call invitation in a one-to-one or one-to-many voice/video call. + +**Join or leave a channel** + +**Send or receive channel messages** + + + +**Automatically return the latest number of members in the current channel** + +Once you are in a channel, you no longer must call the `getChannelMemberCount` method to get the member count of the current channel. We also do not recommend using `onMemberJoined` and `onMemberLeft` to keep track of the member counts. As of this release, the SDK returns to the channel members onMemberCountUpdated the latest channel member count when the number of channel members changes. Note that: + +- When the number of channel members ≤ 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once per second. +- When the number of channel members exceeds 512, the SDK returns this callback when the number changes and at a MAXIMUM speed of once every three seconds. + + + +> Please treat this callback and the onGetMembers callback separately: +> +> - The former is an automatic callback. It returns the current numer of channel members; +> - The latter is triggered by the getMembers method. It returns a member list of the current channel. If the number of channel members exceeds 512, the SDK only returns a list of 512 randomly selected channel members. + +**Renew the Token** + +**Specify the default path to the SDK log file** + +Use the `setLogFile` method to change the default path to the SDK log file. To ensure that errors are completely written to the log file, we recommend calling this method immediately after you have created and initialized an `IRtmService` instance. + + + +**Set the output log level of the SDK** + +Use the `setLogFilter` method to set the output log level of the SDK. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING (the OFF level does not return any log results). See also LOG_FILTER_TYPE. + +> You can call this method once you have created and initialized an `IRtmService` instance. You do not have to call this method until after calling the `login` method. + +**Set the log file size in KB** + +Use the `setLogFileSize` method to set the log file size. The log file has a default size of 512 KB. File size settings of less than 512 KB or greater than 10 MB will not take effect. + +> You can call this method once you have created and initialized an `IRtmService` instance. You do not have to call this method until after calling the `login` method. + + + + + \ No newline at end of file diff --git a/shared/signaling/storage/_storage.mdx b/shared/signaling/storage/_storage.mdx index 15c602ae2..66588f456 100644 --- a/shared/signaling/storage/_storage.mdx +++ b/shared/signaling/storage/_storage.mdx @@ -3,11 +3,15 @@ import ProjectImplement from '@docs/shared/signaling/storage/project-implementat import ProjectTest from '@docs/shared/signaling/storage/project-test/index.mdx'; import Reference from '@docs/shared/signaling/storage/reference/index.mdx'; - storage is a powerful feature that enables you to store and manage channel and user attributes in a serverless storage system. It acts as an extension of your database, offering synchronization across all participants. By using signaling storage, you can develop innovative, reliable, and scalable applications without the hassle of setting up your own database. This seamless integration ensures that data is readily available and up-to-date for all users, making it easier to build real-time and collaborative applications. + storage enables you to save channel and user attributes in an easy-to-use, serverless storage system. This feature helps you build innovative, reliable, and scalable applications without the need to set up your own database. -Your receives metadata modification events in real-time enabling you to update the front-end accordingly. You can leverage user and channel metadata in apps to: +Your app receives metadata modification events in real-time enabling you to update the front-end accordingly. You can leverage user and channel metadata in apps to: -* **Maintain search history**: Enable users to quickly search for specific messages, users, or topics within the app. +* **Personalize user profiles**: Create user profiles that include additional information such as the user's full name, a profile picture URL, geographic location, and availability status. + +* **Maintain chat history**: Store and display chat history, including timestamps and message status such as whether a message has been read or not. + +* **Maintain search history**: Enable users to quickly search for specific messages, users, or topics within the app. * **Customize notifications**: Enable users to customize their notification settings, such as choosing notifications to receive and setting custom alert tones. @@ -43,7 +47,9 @@ To follow this page, you must have: ## Implement storage -In the storage reference app, after the local user logs in to , you set their metadata in the form of key-value pairs. When the user modifies a value stored as metadata, you call the update method to save the new value. You show a list of all users currently in the channel. When the local user selects another user from the list, you retrieve and display their metadata. You subscribe to the metadata of remote users to be notified of changes. +In the `storage` reference app, after the local user logs in to , you set their metadata in the form of key-value pairs. When the user modifies a value stored as metadata, you call the update method to save the new value. You show a list of all users currently in the channel. When the local user selects another user from the list, you retrieve and display their metadata. You subscribe to the metadata of remote users to be notified of changes. + +To demonstrate the use of channel storage, the sets the `lastUser` key in the channel metadata to the current time, whenever a user subscribes to the channel. Since the channel metadata is shared by all users in the channel, the value of the `lastUser` key holds the time of the last subscription to the channel. You access the identity of the `lastUser` by referring to the `AuthorUid` of the metadata key. diff --git a/shared/signaling/storage/project-implementation/web.mdx b/shared/signaling/storage/project-implementation/web.mdx index 62936305e..b14308295 100644 --- a/shared/signaling/storage/project-implementation/web.mdx +++ b/shared/signaling/storage/project-implementation/web.mdx @@ -111,21 +111,21 @@ The following code examples show how to implement storage features in your 0, The target revision number must match this value for the operation to succeed. }, ]; const options = { - majorRevision: -1, // Use this field to enable version number verification of the entire set of channel attributes. - lockName: lockName, // When you specify a lock, only the user who calls the acquireLock method to acquire the lock can perform the operation. + majorRevision: -1, + lockName: "", // After setting a lock, only the user who calls the acquireLock method to acquire the lock can perform the operation. addTimeStamp: true, addUserId: true, }; @@ -134,11 +134,11 @@ The following code examples show how to implement storage features in your \ No newline at end of file diff --git a/shared/signaling/storage/project-test/index.mdx b/shared/signaling/storage/project-test/index.mdx index 1a9c70aad..7b1ffffef 100644 --- a/shared/signaling/storage/project-test/index.mdx +++ b/shared/signaling/storage/project-test/index.mdx @@ -8,11 +8,6 @@ import MacOS from './macos.mdx' import Unity from './unity.mdx' import Windows from './windows.mdx'; -import Test from '@docs/shared/common/project-test/index.mdx'; - -To test this functionality: - - diff --git a/shared/signaling/storage/project-test/web.mdx b/shared/signaling/storage/project-test/web.mdx index b3f1de736..dbad140eb 100644 --- a/shared/signaling/storage/project-test/web.mdx +++ b/shared/signaling/storage/project-test/web.mdx @@ -1,52 +1,62 @@ -4. **Login to as a first user** +1. In `/signaling-sdk-samples-web/src/signaling_manager/config.json`, update the following parameter values: - 1. Enter a numeric **User ID** and press **Login** to log in to . + * `appId`: Your enabled app ID from . - 1. Enter a **Channel name** and press **Subscribe** to subscribe to a channel. You see the following: + * `serverUrl`: The URL of your token server. See [Create and run a token server](../get-started/authentication-workflow#create-and-run-a-token-server) to set one up. - 1. Your User ID appears in the **Users in the channel** list. - 1. Under **Channel Metadata**, you see all the key-value pairs previously saved to the channel's storage. - 1. In the log events section at the bottom, you see notifications confirming update of user metadata. -4. **Login to as another user** +1. To access the token server from the web app, you use a proxy server. To start the proxy service, run the following command in Terminal from the `/signaling-sdk-samples-web/src` folder: - 1. In another browser tab, log in using a different **User ID**. Enter the same channel name as before, and press **Subscribe**. + ```bash + node proxy + ``` - You see that both User IDs appear in the user lists in both tabs. +1. To build and run the project, open a Terminal in the `/signaling-sdk-samples-web` folder, and run the following commands: -1. **Test metadata** + ``` bash + npm run build + npm run start:dev + ``` - In either tab, type in a **Key** and the **Value** you wish to store in the channel metadata, then press - **Update**. You see that the key-value pair is added or updated under **Channel Metadata** in both tabs. +1. In your browser, open `http://localhost:9000/` and select the **Store channel and user data** project from the navigation bar. -1. **Test version control** +1. Enter a numeric **User ID** and press **Login** to log in to . - 1. Under **Set channel metadata**, type a new **Value** for an existing channel metadata **Key**. Enter a random positive integer for **Revision** and press **Update**. The log events section shows that the storage operation fails due to `outdated revision`. - - 1. Update the **Revision** value to show the same number as displayed against the metadata key under **Channel Metadata**, then press **Update** again. This time, the operation succeeds. +1. Enter a **Channel name** and press **Subscribe** to subscribe to a channel. You see the following: + + 1. Your User ID appears in the **Users in the channel** list. + 1. Under **Channel Metadata**, you see the `lastUser` key that is saved to the channel. + 1. In the log events section at the bottom, you see notifications confirming update of channel and user metadata. + +1. In another browser tab, load `http://localhost:9000/storage` and log in using a different **User ID**. Enter the same channel name as before, and press **Subscribe**. You see the following: + + 1. Both User IDs appear in the user lists in both tabs. + 1. The value of the `lastUser` key, under **Channel Metadata**, is updated in *both* tabs with the time of the latest login. The updated `AuthorUid` shows the User ID of the new user. + +1. To test the version control feature: + +1. In the other browser tab, select the user for which you modified the User bio under **Users in the channel**. You see their updated metadata displayed in the log events section. -1. **Test locks** +1. To test the lock feature: - 1. Under **Manage Locks**, type a **Lock Name** and press **Set**. You see a `SET` event notification confirming creation of the lock. + 1. Type a **Lock Name** under **Manage Locks** and press **Set**. You see a `SET` event notification confirming creation of the lock. - 1. In **Lock to apply**, enter the same lock name and press **Update**. You see an error reporting that the lock has not been acquired. + 1. Enter the same lock name in **Lock to apply** and press **Update**. You see an error reporting that the lock has not been acquired. 1. Press **Acquire**. You see an `ACQUIRED` event notification confirming acquisition of the lock. - 1. Press **Update**, this time the channel key value is updated under **Channel Metadata**. + 1. Press **Update** again, this time the channel key value is updated under **Channel Metadata**. 1. Press **Get**. You see details of all current locks in the logs section. 1. Press **Release** to release the lock, and **Remove** to delete it. -1. **Test metadata** +1. To test the user metadata feature: - 1. In **Save bio to user metadata**, type in some text and press **Update Bio**. You see user metadata `UPDATE` - notifications in both tabs. + 1. In either browser tab, type in some text in the **Save bio to user metadata** box and press **Update Bio**. You see user metadata `UPDATE` notifications in both tabs. - 1. In the other browser tab, under **Users in the channel** select the user for which you modified the User bio. - You see their updated metadata displayed in the log events section. + 1. In the other browser tab, select the user for which you modified the User bio under **Users in the channel**. You see their updated metadata displayed in the log events section. - + \ No newline at end of file diff --git a/shared/signaling/storage/reference/web.mdx b/shared/signaling/storage/reference/web.mdx index fe2f4885d..4e3a3b2e4 100644 --- a/shared/signaling/storage/reference/web.mdx +++ b/shared/signaling/storage/reference/web.mdx @@ -12,6 +12,5 @@ * [updateUserMetadata](../reference/api#updateusermetadata) * [subscribeUserMetadata](../reference/api#subscribeusermetadata) * [unsubscribeUserMetadata](../reference/api#unsubscribeusermetadata) -* [Lock](../reference/api#lock) \ No newline at end of file diff --git a/shared/signaling/stream-channel/_stream-channel.mdx b/shared/signaling/stream-channel/_stream-channel.mdx index e5c61797f..018331fa5 100644 --- a/shared/signaling/stream-channel/_stream-channel.mdx +++ b/shared/signaling/stream-channel/_stream-channel.mdx @@ -1,4 +1,5 @@ import * as data from '@site/data/variables'; +import Setup from '@docs/shared/common/project-setup/index.mdx'; import ProjectImplement from '@docs/shared/signaling/stream-channel/project-implementation/index.mdx'; import ProjectTest from '@docs/shared/signaling/stream-channel/project-test/index.mdx'; import Reference from '@docs/shared/signaling/stream-channel/reference/index.mdx'; @@ -23,13 +24,18 @@ To follow this page, you must have: - Setup the [ reference app](/en/signaling/get-started/get-started-sdk#project-setup). -## Implement communication in a stream channel +## Implement communication in a stream chennel This section shows how to use the to implement stream channels and presence in your . -## Test stream channels +## Test your implementation + +For each user you use in your tests: + +1. [Generate a temporary token](../reference/manage-agora-account#generate-a--token). + diff --git a/shared/signaling/stream-channel/project-implementation/web.mdx b/shared/signaling/stream-channel/project-implementation/web.mdx index 866dcc003..c7229842d 100644 --- a/shared/signaling/stream-channel/project-implementation/web.mdx +++ b/shared/signaling/stream-channel/project-implementation/web.mdx @@ -8,26 +8,26 @@ 1. **Join and leave a channel** To create a new stream channel, call `createStreamChannel`. When you join the channel, you configure the features - you will use. For example, [Presence](/en/signaling/reference/api#presence), [Storage](/en/signaling/reference/api#storage), and [Lock](/en/signaling/reference/api#lock). You use the [RTC authentication - token](/en/signaling/get-started/authentication-workflow#authenticate-your--session) for the current UID to join the channel. To join a channel: + you will use. For example, [Presence](/en/signaling/reference/api#presence), [Storage](/en/signaling/reference/api#storage), and [Lock](/en/signaling/reference/api#lock). You use the authentication + token for the current UID to join the channel. To join a channel: ```javascript const streamChannelJoinAndLeave = async function ( isStreamChannelJoined, - uid, streamChannelName ) { - const token = await fetchRTCToken(uid, streamChannelName); - if (getSignalingStreamChannel() === null) { - streamChannel = await signalingManager - .getSignalingEngine() - .createStreamChannel(streamChannelName); // creates stream channel + if (config.rtcToken === null) { + console.log( + "please create a rtc token from the console and add the token to the RtcToken variable in 'src/signaling_manager/config.json'" + ); + return; } + streamChannel = await signalingManager.getSignalingEngine().createStreamChannel(streamChannelName); // creates stream channel if (isStreamChannelJoined === false) { await streamChannel .join({ - token: token, + token: config.rtcToken, withPresence: true, }) .then((response) => { @@ -36,7 +36,7 @@ } else { streamChannel.leave().then((response) => { console.log(response); - messageCallback("Left the channel: " + streamChannelName); + messageCallback("left channel: " + streamChannelName); streamChannel = null; }); } @@ -47,31 +47,39 @@ A topic is a data stream management mechanism in stream channels. Users join, leave, subscribe, and unsubscribe to topics. You join a topic to publish and recieve messages sent to all users in the topic. - You subscribe to listen to messages sent by publishers only. When a user joins or leaves a topic, - triggers an topic event notification. Users in the channel receive the notifications in real time. You use topic events - to track changes in topic status. To join a topic: + You subscribe to listen to messages sent by publishers only. When a user joins or leaves a topic, + triggers an topic event notification. Users in the channel receive the notifications in real time. You use topic events + to track changes in topic status. To join a topic: + + ```javascript + const topicJoinAndLeave = async function (isTopicJoined, topicName) { + if (config.rtcToken === null) { + console.log( + "please create a rtc token from the console and add the token to the RtcToken variable in '/src/signaling_manager/config.json'" + ); + return; + } - ```javascript - const topicJoinAndLeave = async function (isTopicJoined, topicName) { if (isTopicJoined === false) { - await signalingManager.getSignalingStreamChannel().joinTopic(topicName).then((response) => { + await streamChannel.joinTopic(topicName).then((response) => { messageCallback("Joined the topic: " + response.topicName); }); } else { - signalingManager.getSignalingStreamChannel().leaveTopic(topicName).then((response) => { + streamChannel.leaveTopic(topicName).then((response) => { console.log(response); - messageCallback("Left the topic: " + response.topicName); + messageCallback("left topic: " + response.topicName); }); } }; - ``` - There is no limit to the number of subscribers and publishers in each topic. However, there are limitations to - the [number of topics and messages a user can subscribe to](/en/signaling/reference/limitations). + ``` + + There is no limit to the number of subscribers and publishers in each topic. However, there are limitations to + the [number of topics and messages a user can subscribe to](/en/signaling/reference/limitations). 1. **Send messages to a topic** Messages are transmitted through the topic. After your user has joined a topic in a channel, you - publish messages to the topic. Publishers and subscribers receive the messages. To send a message: + publish messages to the topic. Publishers and subscribers receive the messages. To send a message: ```javascript const sendTopicMessage = function (message, topicName) { @@ -81,7 +89,7 @@ ); return; } - signalingManager.getSignalingStreamChannel().publishTopicMessage(topicName, message).then((response) => { + streamChannel.publishTopicMessage(topicName, message).then((response) => { console.log(response); messageCallback("Topic: " + topicName + ", Message:" + message); }); diff --git a/shared/signaling/stream-channel/project-test/index.mdx b/shared/signaling/stream-channel/project-test/index.mdx index f030391fe..7b1ffffef 100644 --- a/shared/signaling/stream-channel/project-test/index.mdx +++ b/shared/signaling/stream-channel/project-test/index.mdx @@ -7,11 +7,7 @@ import Flutter from './flutter.mdx'; import MacOS from './macos.mdx' import Unity from './unity.mdx' import Windows from './windows.mdx'; -import Test from '@docs/shared/common/project-test/index.mdx'; -To test this functionality: - - diff --git a/shared/signaling/stream-channel/project-test/web.mdx b/shared/signaling/stream-channel/project-test/web.mdx index 56b548f25..7aed76c1e 100644 --- a/shared/signaling/stream-channel/project-test/web.mdx +++ b/shared/signaling/stream-channel/project-test/web.mdx @@ -1,9 +1,21 @@ +2. In `/src/signaling_manager/config.json`: -4. **Test stream channels**: + 1. Replace the value of `token` with the temporary token. - 1. For each user, open the reference app in a new tab in your browser. + 1. Replace the values for `uid`, `appId`, and `channelName` with the app ID, + and channel name for the values from . - 1. Log in to , then send and receive messages using topics in channels. +1. Open a command prompt in the project folder, and run the following command: + + ``` bash + npm run build + npm run start:dev + ``` +1. For each user, in a new tab in your browser: + + 1. Open the project at http://localhost:9000/stream_channel/. + + 1. Login to , then send and receive messages using topics in channels. - + \ No newline at end of file diff --git a/shared/variables/global.js b/shared/variables/global.js index bd55b5b4a..0d3e5d4c2 100644 --- a/shared/variables/global.js +++ b/shared/variables/global.js @@ -72,7 +72,6 @@ export const CONSOLE = `${COMPANY} Console`; export const TOKEN = 'token'; export const ENGINE = `${COMPANY} Engine`; - export const RTE = 'Real-Time Engagement'; export const RTEC = `${RTE} Core`; export const RTES = `${RTE} SDK`; @@ -109,12 +108,11 @@ export const AV = 'Audio/Video'; export const MESS = 'Signaling'; export const MESS_SDK = `${MESS} SDK`; -export const MESS_ENGINE = `${MESS} Engine`; export const EASEMOB_SDK = `Easemob IM SDK`; export const NCS = `NCS`; export const NCS_LONG = `Notifications`; export const SIG = `${MESS}`; -export const SIG_RELEASE_API = `2.x`; +export const SIG_RELEASE_API = `1.x`; export const SIG_SDK_API_REF_ROOT = `${API_ROOT}/signaling-sdk`; export const SIG_SDK_API_ANDROID = `${SIG_SDK_API_REF_ROOT}/android/${SIG_RELEASE_API}`; export const SIG_SDK_API_WIN_CPP = `${SIG_SDK_API_REF_ROOT}/windows-cpp/${SIG_RELEASE_API}`; diff --git a/signaling/develop/_category_.json b/signaling/develop/_category_.json index 8d04cb259..bee160082 100644 --- a/signaling/develop/_category_.json +++ b/signaling/develop/_category_.json @@ -1,6 +1,6 @@ { "position": 3, - "label": "Core functionality", + "label": "Develop", "collapsible": true, "link": null } diff --git a/signaling/get-started/authentication-workflow.mdx b/signaling/develop/authentication-workflow.mdx similarity index 94% rename from signaling/get-started/authentication-workflow.mdx rename to signaling/develop/authentication-workflow.mdx index 25a675267..81ede3c42 100644 --- a/signaling/get-started/authentication-workflow.mdx +++ b/signaling/develop/authentication-workflow.mdx @@ -1,6 +1,6 @@ --- title: 'Secure authentication with tokens' -sidebar_position: 3 +sidebar_position: 1 type: docs description: > Retrieve tokens generated by an authentication token server to securely connect to Signaling. diff --git a/signaling/develop/integrate-token-generation.mdx b/signaling/develop/integrate-token-generation.mdx deleted file mode 100644 index f3cd123dc..000000000 --- a/signaling/develop/integrate-token-generation.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: 'Token generators' -sidebar_position: 15 -type: docs -description: > - Integrate token generation libraries into your authentication server. ---- - -import IntegrateToken from '@docs/shared/video-sdk/develop/_integrate-token-generation.mdx'; - -export const toc = [{}]; - - diff --git a/signaling/get-started/get-started-sdk.mdx b/signaling/get-started/get-started-sdk.mdx index 67c555496..7979eb208 100644 --- a/signaling/get-started/get-started-sdk.mdx +++ b/signaling/get-started/get-started-sdk.mdx @@ -20,16 +20,16 @@ channels](/en/signaling/develop/stream-channel). ## Understand the tech -Pub-sub is the simplest form of messaging. Your creates a channel when a user subscribes to it. Your listens for the channel events which contain the messages -users publish to it. +Pub-sub is the simplest form of messaging. A channel is created when a user +sends a message to a peer. Your listens for peer events which contain the messages users send to +each other. You use an authentication token to authenticate a user with and join a channel. Each token is bound to a single user UID. This means that one concurrent user only may login from your . -To create a pub-sub session for , implement the following steps in your -: +- *Retrieve a token*: -![](/images/signaling/get-started-workflow.svg) + A token is a computer-generated string that authenticates a user when your joins a channel. In this guide you retrieve your token from . To see how to create an authentication server for development purposes, see [Implement the authentication workflow](../get-started/authentication-workflow). To develop your own token generator and integrate it into your production IAM system, read [Token generators](/video-calling/develop/integrate-token-generation). In this guide you retrieve a temporary token from Token Generator. To understand how to create an authentication server for development purposes, see [Implement the authentication workflow](../get-started/authentication-workflow). @@ -37,22 +37,10 @@ To develop your own token generator and integrate it into your production IAM sy ## Prerequisites -In order to follow this procedure you must: +In order to follow this procedure you must have: -- [Raise a support ticket](https://agora-ticket.agora.io/) to activate . In your ticket, please provide the following details: - - Your Customer Id - - The project VID for which you want Signaling enabled - - The App Id for the project in which you want to integrate Signaling - - Do you require Stream Channel activation: Yes or No - - Do you need data storage (Storing user and channel attributes as metadata): Yes or No - - Your geographical region for product activation: US, EU, APAC (excluding China), or China - - The support team confirms activation through a ticket update. - -
  • Signaling 2.x is an enhanced version compared to 1.x with a wide range of new features. It follows a new pricing structure. Please visit the [Pricing](../reference/pricing) page for details.
  • The beta version of Signaling 2.x is offered free for testing its features and performance.
- diff --git a/signaling/get-started/run-the-sample-project.mdx b/signaling/get-started/run-the-sample-project.mdx new file mode 100644 index 000000000..c19db9769 --- /dev/null +++ b/signaling/get-started/run-the-sample-project.mdx @@ -0,0 +1,46 @@ +--- +title: 'Run the sample project' +sidebar_position: 2 +type: docs +description: > + Install and run the Signaling example project. +--- + +import Prerequites from '@docs/shared/common/prerequities.mdx'; +import RunSampleProject from '@docs/shared/signaling/run-the-sample-project/index.mdx'; + +export const toc = [{}]; + +This page shows you how to install and run the example project. + +## Prerequisites + +In order to follow this procedure you must have: + + + +## Implement Signaling + +### 1. Create an Agora project + +Create a project in [Agora Console](https://console.agora.io/), as follows: + +1. Log in to Console, and click **Project Management** in the left navigation menu to enter the [Project Management](https://dashboard.agora.io/projects) page. + +2. Click **Create**. + + ![create button](https://web-cdn.agora.io/docs-files/1594949127367) + +3. Enter your project name, and select **APP ID** for the authentication mechanism in the pop-up window. Agora recommends using an App ID for authentication only in a test environment, or if your project has low security requirements. + +4. Click **Submit**. You can see the created project on the **Project Management** page. + +### 2. Get an App ID + +Agora automatically assigns each project an App ID as a unique identifier. + +To copy this App ID, find your project on the [Project Management](https://dashboard.agora.io/projects) page in Agora Console, and click the eye icon to the right of the App ID. + +![get app id](https://web-cdn.agora.io/docs-files/1602646621028) + + diff --git a/signaling/overview/product-overview.mdx b/signaling/overview/product-overview.mdx index 1128a5ee0..c40bf3f9f 100644 --- a/signaling/overview/product-overview.mdx +++ b/signaling/overview/product-overview.mdx @@ -16,46 +16,34 @@ description: > authenticationLink="/signaling/get-started/authentication-workflow" productFeatures={[ { - title: "Message channels", - content: "Real-time messaging that enables asynchronous pub-sum message transmission without the need for " + - "immediate response. Publishers send messages to the channel, subscribers receive messages from the channels they " + - "sign up to. " + - "Depending on your business needs, send string or binary payloads", - link: "/en/signaling/get-started/get-started-sdk" + title: "Channel management", + content: "Organization and management capabilities around channel management like call invitation, user statuses in channel, and more.", + link: "" }, { - title: "Stream channels", - content: "A real-time data pipeline that enables the uninterrupted flow of data from one point to another " + - "without delay or latency. " + - "Depending on your business needs, send string or binary payloads", - link: "/en/signaling/develop/stream-channel" + title: "Online/offline presence", + content: "Real-time synchronization within 200ms of device online/offline status notification capabilities.", + link: "" }, { - title: "Topics", - content: "Facilitate effective data stream management and communication between users in real time in Stream " + - "channels. Enable users to subscribe to, distribute, and notify users subscribed to a topic. Publishers " + - "send messages to a topic, subscribers receive messages in the topics they sign up to.", - link: "/en/signaling/develop/stream-channel#implement-communication-in-a-stream-channel" + title: "Low latency", + content: "Provide real-time synchronization with global average latency under 200ms and average latency within region under 100ms.", + link: "" }, { - title: "Presence", - content: "In online collaboration apps, enable users to see the availability of their contacts. Presence " + - "information is typically displayed as a status message or with an icon next to a user's name. It helps " + - "users determine the availability of others for communication or collaboration.", - link: "/en/signaling/reference/api#presence" + title: "Storage, distribution, and notification", + content: "User device/channel attribute change capabilities for storage, distribution, and notification.", + link: "" }, { - title: "Storage", - content: "Persist and managing data that is exchanged between different clients or devices in real-time. " + - "Ensure that messages are not lost or dropped during transmission and enable quick and reliable message delivery to any number of clients. ", - link: "/en/signaling/develop/storage" + title: "Authentication", + content: "Control authentication workflow on user permission controls via token-based access to ban, mute, or manipulate the abilities of a user in a channel.", + link: "" }, { - title: "Lock", - content: "Critical resource management mechanism to prevent mutual interference. Ensure that messages are " + - "processed in a specific order and prevent concurrent access to the same data. When your app accesses a " + - "resource, it can lock on that resource to prevent other clients from accessing it.", - link: "/en/signaling/reference/api#lock" + title: "3rd party plugins", + content: "Add Signaling features with other supported 3rd party features like content moderation, SMS, persistent storage, and more via webhooks.", + link: "" }, ]} @@ -65,4 +53,4 @@ Agora Signaling provides low-latency, high-concurrency signaling and synchroniza - \ No newline at end of file + diff --git a/signaling/reference/api.mdx b/signaling/reference/api.mdx index e1b9a04ac..4ee4de618 100644 --- a/signaling/reference/api.mdx +++ b/signaling/reference/api.mdx @@ -1,20 +1,19 @@ --- title: 'Signaling SDK API reference' -sidebar_position: 3 +sidebar_position: 6 type: docs description: > Links to the API reference for your platform --- -import WebAPI from '@docs/shared/signaling/reference/index.mdx'; -export const toc = [{}]; - - You find the API reference documentation at: - - + +- Web API reference +- [User and channel events REST API](user-channel-events) +- [Messaging REST API](restful-messaging) + - Android API reference diff --git a/signaling/reference/downloads.mdx b/signaling/reference/downloads.mdx index c70d68f8d..13905da60 100644 --- a/signaling/reference/downloads.mdx +++ b/signaling/reference/downloads.mdx @@ -1,6 +1,6 @@ --- title: 'Manual install' -sidebar_position: 5 +sidebar_position: 3 type: docs description: > Links to the manual downloads for this product, and explanations on how to install them. diff --git a/signaling/reference/limitations.mdx b/signaling/reference/limitations.mdx index f3a531080..792c2766d 100644 --- a/signaling/reference/limitations.mdx +++ b/signaling/reference/limitations.mdx @@ -1,6 +1,6 @@ --- title: 'API usage restrictions' -sidebar_position: 4 +sidebar_position: 2 description: > A brief overview of the restrictions of the Signaling SDK, including API call limit, string size, encoding, and more. --- diff --git a/signaling/reference/manage-agora-account.mdx b/signaling/reference/manage-agora-account.mdx index 198bfe51e..f02ac9b16 100644 --- a/signaling/reference/manage-agora-account.mdx +++ b/signaling/reference/manage-agora-account.mdx @@ -1,6 +1,6 @@ --- title: 'Agora account management' -sidebar_position: 7 +sidebar_position: 4 type: docs description: > Create, manage and update your Agora account. diff --git a/signaling/reference/pricing.mdx b/signaling/reference/pricing.mdx index 5b614a404..fde91229f 100644 --- a/signaling/reference/pricing.mdx +++ b/signaling/reference/pricing.mdx @@ -7,180 +7,54 @@ description: > export const toc = [{}] -This page explains how calculates your monthly bill for . - -If you have already signed a contract with , the billing terms and conditions within that contract take precedence. - -## 1.x pricing plans, features, and limitations - - provides the following pricing plans: - -- [Free](#free-pricing) -- [Self-service](#self-service-pricing) -- [Enterprise](#enterprise-pricing) - -The available features and monthly fees depend on the plan you select. You can check and export the usage status as well as upgrade or downgrade your pricing plan at any time in . Plan upgrade takes effect immediately, while plan downgrade takes effect the following month. - -### Free pricing - -The Free pricing plan allows you to experience the core features with the following limitations: - -|Plan|Limitations|Monthly fee| -|:---|:----------|:----------| -|Free|
  • 3,000,000 messages/month
  • 100 PCU (peak concurrent users)/month
  • 1 GB storage capacity/month
|Free| - -If your usage exceeds the above limitations, you receive an error code and an email reminder. You cannot continue using until the end of the corresponding month. - -### Self-service pricing - -The Self-service pricing plan includes two tiers with the following limitations: - -|Plan|Limitations|Monthly fee| -|:---|:----------|:----------| -|Self-service startup|
  • 30,000,000 messages/month
  • 500 PCU/month
  • 2 GB free storage capacity/month
|399 RMB| -|Self-service business|
  • 600,000,000 messages/month
  • 10,000 PCU/month
  • 10 GB storage capacity/month
|5499 RMB| - -If your usage exceeds the above limitations, you receive an error code and an email reminder. You can continue using , and your usage -above the limitations is billed according to the Enterprise pricing. - -### Enterprise pricing - -The Enterprise pricing plan does not set any additional limitations, besides [the API usage restrictions](limitations), and includes per-usage billing. +This page explains how calculates your monthly bill for . -The monthly fee is calculated using the following basic formula: +If you have already signed a contract with , the billing terms and conditions within that contract take precedence. -**Monthly fee** = **PCU fee** + **message number fee** + **storage capacity fee** +## pricing The unit prices are as follows: -|Item|Pricing| -|:---|:------| -|PCU|100 RMB/1,000 peak connections| -|Price per message|10 RMB/1,000,000 messages| -|Storage unit price|50 RMB/1 GB| - -See [How Agora measures your usage](#how-agora-measures-your-usage) to understand how PCU, number of messages, and storage consumption are calculated. - -### Pricing plan feature comparison - -The following features and support are available based on the pricing plan you select: - -|Feature |Free |Self-service |Enterprise | -|:------------------|:------|:--------------|:----------| -|Publish/subscribe to messages |✔ |✔| ✔| -|Stream channel |✔ |✔ |✔| -|Presence |✔ |✔ |✔| -|Storage |✔ |✔ |✔| -|Historical messages |✔ |✔ |✔| -|Lock |✔ |✔ |✔| -|Authentication |✔ |✔ |✔| -|Console |✔ |✔ |✔| -|Webhook |✔ |✔| ✔| -|Analytics |✔ |✔| ✔| -|Uptime SLA |✘ |✔ |✔| -|Geofencing |✘ |✘ |✔| -|GDPR & HIPAA compliance guarantee |✘ |✘ |✔| -|Customized requirements |✘ |✘ |✔| -|Private deployment |✘ |✘ |✔| -|Service hours |12 x 7 |24 x 7 |24 x 7| -|Support reply speed |As soon as possible |24 hours| 1 hour| -|Email support |✔ |✔ |✔| -|Enterprise WeChat support |✔ |✔ |✔| -|Phone support |✔ |✔ |✔| -|Slack support |✘ |✔ |✔| -|Technical expert support |✘ |✘| ✔| -|Dedicated SA support |✘ |✘ |✔| -|Usage discount |✘ |✘ |✔| - - -## How Agora measures your usage - -Agora measures your PCU, number of messages, and storage consumption in the following way: +| Highest number of DAUs for the month | Pricing, US$/1,000 DAUs | +|--------------------------------------|------------------------| +| ≤ 1,000 | 0 | +| > 1,000 | 14.50 | -#### PCU +## Cost calculation -Your PCU is the maximum number of real-time users simultaneously connected to the server at any point in a calendar month. For example, if you have 10,000 users and a maximum of 500 users simultaneously connect in a given month, your PCU value for that month is 500, which means you only pay for 500 peak connections. The total number of users or devices that connected the server in that month does not affect the fee. +Billing for begins once you implement the signaling +functionality using and occurs monthly. -#### Total number of messages + calculates your monthly pricing by adding up the highest number of +**daily active users (DAUs)** for the month of each project in your +[ developer account](https://console.agora.io/), subtracting the 1,000 free DAUs, +and multiplying by unit pricing. -The size of a single message in is calculated as 1 KB. If you send a 10 KB message to a channel or topic subscribed to by 100 people, it counts as 10 inbound messages and 1,000 outbound messages, totalling in 1,010 messages. The following additional rules apply for calculating the number of messages: +The basic formula is shown here: -##### Sending and receiving messages +**Monthly cost** = (**total DAUs in all projects** - **1000 free DAUs**) / 1,000 × **unit pricing** - Every published or received message in a message channel counts as 1 message. For example, if a user sends 1 message to a message channel, and the channel is subscribed to by 10 other users, it counts as 1 sent message and 10 received messages, totaling in 11 messages. +## Examples - Every published or received message in a topic in a stream channel counts as 1 message. For example, if a users sends 1 message to a topic in a stream channel, and the topic is subscribed to by 10 other users, it counts as 1 sent message and 10 received messages, totaling in 11 messages. +This section illustrates how calculates the cost for . - Note that even if the user enables message filtering, it does not change how the number of messages is calculated. The client-side message filtering is only for the convenience of developers, since a filtered message is still delivered. The asynchronous callback generated by publishing a message in a message channel or a stream channel does not count as a message. +### One project - Messages sent using the RESTful API also count as messages. If a user does not subscribe to the channel or topic, they do not receive any messages. +Suppose you are using and the highest number of DAUs for the month is 9,000. +Because the first 1,000 in the highest number of DAUs for the month are free of charge, +the number of DAUs used to calculate the monthly billing is 8,000. +Therefore, the monthly billing for is 8,000 (DAUs) / 1,000 × $14.50 = $116. -##### Presence +### Two projects - Every published or received event notification about a user's presence, for example, about a user entering or leaving a channel, counts as one message. For example, if a user enters a channel subscribed to by 10 other users that have enabled the `withPresence` parameter to receive presence notifications, then 1 presence notification is sent and 10 notifications are received, totalling in 11 messages. - - User message filtering has no effect on the presence event notification count. - - If the user does not want to send or receive presence notification events when joining or subscribing to a channel, they can set the `beQuite` parameter to `true` and `withPresence` to `false`. In this case, they won't receive any presence notifications. This affects the total count of presence event notifications. - -##### Storage - - Setting, querying, updating, and deleting any item of the channel metadata in a message channel or stream channel counts as one message. Receiving an event notification about a change in a message or stream channel metadata counts as 1 message. For example, if a user sets a metadata item in a channel subscribed to by 10 other users who have enabled the `withMetadata` parameter to receive metadata change notifications, then 1 notification is sent and 10 notifications are received, totalling in 11 messages. - - Setting, querying, updating, and deleting any item of the user metadata counts as one message. Receiving an event notification about a change in a user metadata counts as 1 message. For example, if a user sets an item in a user metadata subscribed to by 10 other users, then 1 notification is sent and 10 notifications are received, totalling in 11 messages. - - User message filtering has no effect on metadata change notification counts. - - If a user does not want to receive metadata change notifications when joining or subscribing to a channel, they can set `withMetaData` to `false`. If a user does not join a stream channel or subscribe to a message channel, they don't receive channel metadata change notifications. If a user does not subscribe to other users' metadata, they do not receive other user's metadata change notifications. - -##### Lock - - Setting, querying, releasing, depriving, and deleting a lock counts as one message. Receiving an event notification about a lock change in a message or stream channel counts as 1 message. For example, if a user sets a lock on a channel subscribed to by 10 other users who have enabled the `withLock` parameter to receive lock change notifications, then 1 notification is sent and 10 notifications are received, totalling in 11 messages. - -#### Storage capacity - -Storage in generates cloud storage occupancy. Agora samples and accumulates your actual cloud storage occupancy at 1-hour intervals to calculate the monthly fee. - - - - - -## 2.x pricing plans - - 2.x is an enhanced version with wide range of new features compared to 1.x and follows a new pricing structure. You can choose from the following packages: - -| Signaling 2.x Package | Description | Package Price Per Month in USD | -|:-------------|:------------------------------------------|:----------| -| Free Package | Up to 100 Peak Concurrent Users, 100K Daily Message Volume, 3M Monthly Message volume, 1 GB Storage | Free | -| Starter Package | Up to 500 Peak Concurrent Users, 1M Daily Message Volume, 30M Monthly Message volume, 2 GB Storage | $59.00 | -| Pro Package | Up to 5K Peak Concurrent Users, 10M Daily Message Volume, 300M Monthly Message volume, 5 GB Storage | $399.00 | -| Business Package | Up to 10K Peak Concurrent Users, 20M Daily Message Volume, 600M Monthly Message volume, 10 GB Storage | $820.00 | -| Enterprise Package | For Every 1000 Peak Concurrent Users - $15
For Every 1 Million Message Count - $1.5
For Every GB of Storage -$7.5 | Pay –as-you-go (with defined unit prices in the description ) | - -### Costing examples - -**Example 1 - Fixed package**: Suppose you are using Signaling 2.x and the number of peak concurrent users (PCU) is less than 5,000, the total message count per month is less than 10 million and storage usage is less than 5 GB. The monthly billing will be $399 considering the Pro Package. - -**Example 2 - Pay-as-you-go**: Suppose you are using Signaling 2.x and the number of peak concurrent users is 20,000, the total message count per month is 7051 Million and the storage is 10 GB. The monthly billing will be as follows: - -* PCU: 20,000 - * PCU Cost = 20000/1000 x $15 = $300 ($15 for Every 1000 Peak Concurrent Users) -* Message count: 7051 Million - * Messages Cost = 7051 x $1.50 = $10,576 ($1.50 for every 1 million message count) -* Storage: 10GB - * Storage cost = 10 x $7.50= $75 ($7.50 for Every GB of Storage -$7.5) -* **Total cost**: $300 + $10,576 + $75 = $10,951 USD (PCU + Messages + Storage) - -The beta version of Signaling 2.x is offered free of charge for testing its features and performance for the duration of its public beta. - - +Suppose you are using in project A and project B. The highest number of DAUs for the +month in project A is 9,000, and the highest number of DAUs for the month in project B is 5,000. +Because the first 1,000 in the highest number of DAUs for the month are free of charge, +the number of DAUs used to calculate the monthly billing is 9,000 + 5,000 - 1,000 = 13,000. +Therefore, the monthly billing for is 13,000 (DAUs) / 1,000 × $14.50 = $188.5. ## See also [Billing policies and free-of-charge policy](../reference/billing-policies) - - - - diff --git a/signaling/reference/release-notes.mdx b/signaling/reference/release-notes.mdx index 740d98ce0..a24348594 100644 --- a/signaling/reference/release-notes.mdx +++ b/signaling/reference/release-notes.mdx @@ -11,9 +11,15 @@ import ReleaseNotes from '@docs/shared/signaling/release-notes/index.mdx'; export const toc = [{}]; -The Agora provides a streamlined and stable messaging mechanism for you to quickly implement real-time messaging for various scenarios. See [product overview](../overview/product-overview) for more information. +The following features are deprecated starting from v1.5.0: + +- Send and receive image or file messages +- Historical messages +- Offline messages +If you have integrated those features in an earlier release and want to continue using them, you can do so in v1.4.x. +The Agora provides a streamlined and stable messaging mechanism for you to quickly implement real-time messaging for various scenarios. See [product overview](../overview/product-overview) for more information. diff --git a/signaling/reference/user-channel-events.mdx b/signaling/reference/user-channel-events.mdx index 59897ade2..e140cc84d 100644 --- a/signaling/reference/user-channel-events.mdx +++ b/signaling/reference/user-channel-events.mdx @@ -1,6 +1,6 @@ --- title: 'User and channel events REST API' -sidebar_position: 6 +sidebar_position: 1 type: docs description: > Enable UIKit to connect to a token server and securely connect to Agora channels.