diff --git a/integration-issues/adjust_music_volume.mdx b/integration-issues/adjust_music_volume.mdx new file mode 100644 index 0000000..462ee66 --- /dev/null +++ b/integration-issues/adjust_music_volume.mdx @@ -0,0 +1,33 @@ +--- +title: 'Why can't I adjust the volume of the background music through the system volume?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +## Problem + +When users play background music in mobile devices and join an RTC channel, they cannot adjust the volume of the background music by adjusting the system volume. + +## Reason + +Mobile devices have two volume types: in-call volume and media volume. Generally speaking, users use the in-call volume control to adjust audio or video calls, and the media volume control to adjust background music. See [What is the difference between the in-call volume and the media volume](./faq/system_volume) for details. + +After users join an RTC channel, the Agora RTC SDK determines which volume type the system volume controls. When the SDK controls the in-call volume and the background music uses the media volume, users cannot adjust the volume of the background music through the system volume. + +## Solution + +#### Solution one + +Call `startAudioMixingPlay` to play the background music, and the SDK can control both the background music and the user's voice. Regardless of whether the SDK uses in-call volume or media volume, users can adjust the volume of both the background music and the user's voice through the system volume. + +#### Solution two + +Set the `scenario` parameter of `setAudioProfile` as `GAME_STREAMING`/`AgoraAudioScenarioGameStreaming` to make the SDK use the media volume. Users can then adjust the volume of both the background music and the user's voice through the system volume. + +#### Solution three + +If the above solutions cannot meet your requirements, you can use platform-specific APIs to intercept volume key events and adjust the volume as follows: + +- Android: Use [AudioManager](https://developer.android.com/reference/android/media/AudioManager.html). +- iOS: Use [MPVolumeView](https://developer.apple.com/documentation/mediaplayer/mpvolumeview). \ No newline at end of file diff --git a/integration-issues/agora_class_ios_error.mdx b/integration-issues/agora_class_ios_error.mdx new file mode 100644 index 0000000..560dbb9 --- /dev/null +++ b/integration-issues/agora_class_ios_error.mdx @@ -0,0 +1,87 @@ +Most of the Agora Classroom SDK for iOS is written in Swift and supports Swift 5.0 and later. Swift supports ABI stability since version 5.0 and Module Stability since version 5.1. Because the Agora Classroom SDK for iOS enables Module Stability, errors can occur when you modify its source code. + +This page lists some common errors and corresponding solutions. + +## Module compiled with Swift 5.3.2 cannot be imported by the Swift 5.4 compiler + +### Error + + The following error might occur when you run Flexible Classroom for iOS v1.1.0: + +![](https://web-cdn.agora.io/docs-files/1620822526000) + +### Reason + +The Agora Classroom SDK v1.1.0 supports Swift 5.3.2. Therefore, this error occurs if you use Swift 5.4. + +### Solution + +If you directly integrate the complete Agora Classroom SDK into your project, Agora recommends upgrading the Agora Classroom SDK to v1.1.2 or later. As of v1.1.2, Agora Classroom SDK supports Swift 5.0 and later. + +## '@objc' instance method in extension of subclass of 'XXX' requires iOS 13.0.0 + +### Error + +When you modify the source code of the Agora Classroom SDK, if you enable BUILD_LIBRARY_FOR_DISTRIBUTION for A.framework, and B.framework inherits the class of A, the following error might occur when you use `@objc` in the `extension` of B: + +![](https://web-cdn.agora.io/docs-files/1624525158077) + +### Solution + +Add `@objc` to the main class. + +## Explicit '@objc' on subclass of 'XXX' requires iOS 13.0.0 + +### Error + +When you modify the source code of the Agora Classroom SDK, if you enable BUILD_LIBRARY_FOR_DISTRIBUTION for A.framework, and B.framework inherits the class of A, the following error might occur when you use `@objc` in the class of B: + +![](https://web-cdn.agora.io/docs-files/1624525178299) + +### Solution + +Delete `@objc`, or modify it with `@objcMembers`. + +## Non-'@objc' method 'tableView(_:numberOfRowsInSection:)' does not satisfy requirement of '@objc' protocol 'UITableViewDataSource' + +### Error + +When you modify the source code of the Agora Classroom SDK, if you enable BUILD_LIBRARY_FOR_DISTRIBUTION for A.framework, and B.framework inherits the class of A, the following error might occur when you implement `UITableViewDataSource` or `UITableViewDelegate` in the `extension` of B: + +![](https://web-cdn.agora.io/docs-files/1624525202089) + +The same error might occur when you implement `AgoraApaasReportorEventTube`, which is the custom `@objc` protocol: + +![](https://web-cdn.agora.io/docs-files/1624525211463,) + +### Solution + +Add the Delegate code to the main class. + +## Undefined symbol: _OBJC_CLASS_$__TtC5OC_XXXXXXX + +### Error + +In an OC file of B.framework, if you call the Swift class `AgoraHandsUpVM`, which contains member variables of the `AgoraAcceptedInfo` structure in the A.framework, the following error might occur: + +![](https://web-cdn.agora.io/docs-files/1624525235312) + +### Reason + +Because B.framework is a static library, it is unlikely to export non-OC libraries from a Swift file. + +### Solution + +Inherit `AgoraAcceptedInfo` from NSObject, and modify it with `@objc` or `@objcMembers`. + +## Unknown type name 'XXX'; did you mean 'ZZZ'? + +### Error + +In an OC file of B.framework, if you refer to the Swift class `AgoraApaasReportor`, which inherits from the Swift `AgoraReportor` class in the A.framework, the following error might occur: + +![](https://web-cdn.agora.io/docs-files/1624525251577) + +### Solution + +Create a Wrapper class to encapsulate `AgoraApaasReportor`, and refer to it in the OC file. \ No newline at end of file diff --git a/integration-issues/app_id_to_token.mdx b/integration-issues/app_id_to_token.mdx new file mode 100644 index 0000000..914ce70 --- /dev/null +++ b/integration-issues/app_id_to_token.mdx @@ -0,0 +1,31 @@ +To meet the requirements for higher security, Agora is phasing out authenticating with an App ID. For projects that currently use App ID to authenticate users, Agora recommends the following steps to upgrade all your projects to token-based authentication + +## 1. Enable the App Certificate + +If you choose the **APP ID** authentication mechanism when creating a project, you need to enable the primary certificate manually. + +On the **Edit Project** page, find **Primary certificate** and click **Enable**. Once the primary certificate is enabled, you can click ![](https://web-cdn.agora.io/docs-files/1592469070485) to view and copy the primary certificate, and use either an App ID or the token generated by the primary certificate for authentication. + +![](https://web-cdn.agora.io/docs-files/1594949302908) + +Once the App Certificate is enabled, the project supports authenticating users with either an App ID or a token. This enables the app to ungrade to token-based authentication without any impact on current users. + + ## 2. Generate tokens on your app server + +Refer to [Generate a Token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Android) to deploy a token generator on your app server. + + ## 3. Modify the app client logic + +Now modify the authentication logic on your app client. Ensure that you fill the `token` parameter in `joinChannel` or `login` with the token generated from your app server. + + ## 4. Grey release + + Your app client is now ready for a grey release. In this state, app users can join a channel either with or without a token. + + ## 5. Delete No Certificate + + When all app clients have upgraded to token-based authentication, delete **No Certificate** in Agora Console. This prevents users from joining a channel with only an App ID. + +
Once No Certificate is deleted, app clients that does not use token-based authentication can no longer join a channel.
+ +![](https://web-cdn.agora.io/docs-files/1614588546605) \ No newline at end of file diff --git a/integration-issues/bucket_region.mdx b/integration-issues/bucket_region.mdx new file mode 100644 index 0000000..5010f05 --- /dev/null +++ b/integration-issues/bucket_region.mdx @@ -0,0 +1,12 @@ +Agora Cloud Recording supports the following cloud storage vendors: + +- Qiniu Cloud +- Amazon S3 +- Alibaba Cloud +- Tencent Cloud + +Before you start, ensure that you have enabled cloud storage service with at least one of the above-mentioned vendors and have created a bucket. When calling `start`, you need to enter your cloud storage information: When setting `storageConfig`, choose a region close to the server from which you send your recording request. See [Agora Cloud Recording RESTful API](/en/cloud-recording/cloud_recording_api_rest#storageConfig) for more information. + +## Issues with cross-region upload + +The files to upload to the cloud storage are stored on the servers close to where you make the recording request. Therefore, a cross-region upload, e.g., making the request in the U.S. while setting the region to Beijing, can be slow or even fail. \ No newline at end of file diff --git a/integration-issues/camera_exposure_focus.mdx b/integration-issues/camera_exposure_focus.mdx new file mode 100644 index 0000000..9924382 --- /dev/null +++ b/integration-issues/camera_exposure_focus.mdx @@ -0,0 +1,167 @@ +--- +title: 'How can I enable camera exposure and focus?' +sidebar_position: 658 +platforms: [] +products: [] +--- + + +Camera exposure and focus are commonly used in video calls to enable high-quality video capture. The Agora RTC SDK provides a set of camera management methods on the Android and iOS platforms, with which you can switch between the front and rear camera, set the camera zoom factor, set the exposure region and set the focus position. + +- Camera exposure: Auto exposure is supported where users can manually set the exposure region. +- Camera focus: Auto face-focus and manual focus are supported. + +## Implementation + +> Before proceeding, ensure that you have implemented basic real-time functions in your project. + +Refer to the following steps to set the camera exposure and focus: + +- **Exposure** +Call the `isCameraExposurePositionSupported` method to check whether exposure function is supported. If it is supported, call the `setCameraExposurePosition` method to set the camera exposure. +You can monitor the exposure position with the `onCameraExposureAreaChanged` callback. +- **Auto face-focus** +Call the `isCameraAutoFocusFaceModeSupported` method to check whether auto face-focus function is supported. If it is supported, call the `setCameraAutoFocusModeEnabled` method to set the focus. +- **Manual focus** +Call the `isCameraFocusSupported` method to check whether manual focus function is supported. If it is supported, call the `setCameraFocusPositionInPreview` method to set the focus. +You can monitor the focus position with the `onCameraFocusAreaChanged` callback. + +### Sample code + +```java +// Java +// Check whether exposure function is supported and enable exposure. +boolean shouldSetExposure = rtcEngine.isCameraExposurePositionSupported(); +if (shouldSetExposure) { + // Set the camera exposure at (50, 100). + float positionX = 50.0f; + float positionY = 100.0f; + rtcEngine.setCameraExposurePosition(positionX, positionY); +} + +// Check whether auto face-focus function is supported and enable auto-face focus. +boolean shouldSetFaceMode = rtcEngine.isCameraAutoFocusFaceModeSupported(); +rtcEngine.setCameraAutoFocusFaceModeEnabled(shouldSetFaceMode); + +// Check whether manual focus function is supported and set the focus. +boolean shouldManualFocus = rtcEngine.isCameraFocusSupported(); +if (shouldManualFocus) { + // Set the camera focus at (50, 100). + float positionX = 50.0f; + float positionY = 100.0f; + rtcEngine.setCameraFocusPositionInPreview(positionX, positionY); +} + +// The camera focus area is updated. You can monitor the update event and implement corresponding logic. +public void onCameraExposureAreaChanged(rect) { +} + +// The camera exposure area is updated. You can monitor the update event the implement corresponding logic. +public void onCameraFocusAreaChanged(rect) { +} +``` + +```swift +// Swift +// Check whether exposure function is supported and enable exposure. + let isSupported = agoraKit.isCameraExposurePositionSupported() + +if isSupported { + // Set the camera exposure at (50, 100). + let point = CGPoint(x: 50, y: 100) + agoraKit.setCameraExposurePosition(point) +} + +// Check whether auto face-focus function is supported and enable auto-face focus. +let isSupported = agoraKit.isCameraAutoFocusFaceModeSupported() +agoraKit.setCameraAutoFocusFaceModeEnabled(isSupported) + +// Check whether manual focus function is supported and set the focus. +let isSupported = agoraKit.isCameraFocusPositionInPreviewSupported() + +if isSupported { + // Set the camera focus at (50, 100). + let point = CGPoint(x: 50, y: 100) + agoraKit.setCameraFocusPositionInPreview(point) +} + + +// The camera focus area is updated. You can monitor the update event and implement corresponding logic. +func rtcEngine(_ engine: AgoraRtcEngineKit, cameraExposureDidChangedToRect: CGRect) { +} + +// The camera exposure area is updated. You can monitor the update event the implement corresponding logic. +func rtcEngine(_ engine: AgoraRtcEngineKit, cameraFocusDidChangedToRect: CGRect) { +} +``` + +```objective-c +// Objective-C +// Check whether exposure function is supported and enable exposure. +let isSuppported = [agoraKit isCameraExposurePositionSupported]; + +if (isSupported) { + // Set the camera exposure at (50, 100). + CGPoint *point = CGPointMake(50, 100); + [agoraKit setCameraExposurePosition: point]; +} + +// Check whether auto face-focus function is supported and enable auto-face focus. +Bool isSupported = [agoraKit isCameraAutoFocusFaceModeSupported]; +[agoraKit setCameraAutoFocusFaceModeEnabled: isSupported]; + +// Check whether manual focus function is supported and set the focus. +let isSupported = [agoraKit isCameraFocusPositionInPreviewSupported]; + +if (isSupported) { + // Set the camera focus at (50, 100). + CGPoint *point = CGPointMake(50, 100); + [agoraKit setCameraFocusPositionInPreview: point]; +} + + +// The camera focus area is updated. You can monitor the update event and implement corresponding logic. +- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine cameraExposureDidChangedToRect:(CGRect)rect { +} + +// The camera exposure area is updated. You can monitor the update event the implement corresponding logic. +- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine cameraFocusDidChangedToRect:(CGRect)rect { +} +``` + +### API comparison table + +The following table shows the API comparison table of Java and Objective-C languages. + +| Java | Objective-C| +|------|-----------| +|`isCameraExposurePositionSupported`|`isCameraExposurePositionSupported`| +|`setCameraExposurePosition`|`setCameraExposurePosition`| +|`isCameraAutoFocusFaceModeSupported`|`isCameraAutoFocusFaceModeSupported`| +|`setCameraAutoFocusModeEnabled`|`setCameraAutoFocusModeEnabled`| +|`isCameraFocusSupported`|`isCameraFocusPositionInPreviewSupported`| +|`setCameraFocusPositionInPreview`|`setCameraFocusPositionInPreview`| +|`onCameraExposureAreaChanged`|`cameraExposureDidChangedToRect`| +|`onCameraFocusAreaChanged`|`cameraFocusDidChangedToRect`| + + +### API reference +- Java + - [`isCameraExposurePositionSupported`](./API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#a6818c2a98bebeb72e4802b1c585da99b) + - [`setCameraExposurePosition`](./API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#a0ac20919f60df42635850c53c9cbdefd) + - [`isCameraAutoFocusFaceModeSupported`](./API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#a09f61f738cf7d8a1902761e03a7fa600) + - [`setCameraAutoFocusModeEnabled`](./API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#a7e67afe7ad0045448fe0bd97203afcee) + - [`isCameraFocusSupported`](./API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#a0e20f04ccecfc41aa23bf63116c9a8cd) + - [`setCameraFocusPositionInPreview`](./API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#aba273e4337a760d883b6c7c1344183c0) + - [`onCameraExposureAreaChanged`](./API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler.html#ab6bc82a55191e596d5bf5a7c56bdf95e) + - [`onCameraFocusAreaChanged`](./API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler.html#a7af6c96c4c35587a13d1e367255e3ec0) + +- Objective-C + - [`isCameraExposurePositionSupported`](./API%20Reference/oc/Classes/AgoraRtcEngineKit.html#//api/name/isCameraExposurePositionSupported) + - [`setCameraExposurePosition`](./API%20Reference/oc/Classes/AgoraRtcEngineKit.html#//api/name/setCameraExposurePosition:) + - [`isCameraAutoFocusFaceModeSupported`](./API%20Reference/oc/Classes/AgoraRtcEngineKit.html#//api/name/isCameraAutoFocusFaceModeSupported) + - [`setCameraAutoFocusModeEnabled`](./API%20Reference/oc/Classes/AgoraRtcEngineKit.html#//api/name/setCameraAutoFocusFaceModeEnabled:) + - [`isCameraFocusPositionInPreviewSupported`](./API%20Reference/oc/Classes/AgoraRtcEngineKit.html#//api/name/isCameraFocusPositionInPreviewSupported) + - [`setCameraFocusPositionInPreview`](./API%20Reference/oc/Classes/AgoraRtcEngineKit.html#//api/name/setCameraFocusPositionInPreview:) + - [`cameraExposureDidChangedToRect`](./API%20Reference/oc/Protocols/AgoraRtcEngineDelegate.html#//api/name/rtcEngine:cameraExposureDidChangedToRect:) + - [`cameraFocusDidChangedToRect`](./API%20Reference/oc/Protocols/AgoraRtcEngineDelegate.html#//api/name/rtcEngine:cameraFocusDidChangedToRect:) \ No newline at end of file diff --git a/integration-issues/cocoapods_problem.mdx b/integration-issues/cocoapods_problem.mdx new file mode 100644 index 0000000..9945da3 --- /dev/null +++ b/integration-issues/cocoapods_problem.mdx @@ -0,0 +1,53 @@ +--- +title: 'How can I solve common CocoaPods problems?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +## pod: command not found + +**Issue description** + +In Terminal, after running `pod init` under the root directory of your project, the Terminal prompts `pod: command not found`. + +**Reason** + +CocoaPods is not installed. + +**Solution** + +See the following steps to solve the issue: + +1. Run `sudo gem install cocoapods` and input the admin password to install CocoaPods. +2. After CocoaPods is successfully installed, go to the root directory of your project and run `pod init` again to generate a `Podfile` under your project folder. + +
If you run sudo gem install cocoapods and encounter authority issues such as You don't have write permissions for the /Library/Ruby/Gems/2.3.0 directory , Agora recommends that you run sudo gem install -n /usr/bin cocoapods to install CocoaPods.
+ +## Cannot install the latest Agora SDK + +**Issue description** + +When you install the Agora SDK, you might encounter the following issues: + +- After entering `pod 'library_name'` in a Podfile and running `pod install` in Terminal, the Agora SDK that is installed is not the latest version. + +- After entering `pod 'library_name', 'latest_version'` in a Podfile and running `pod install` in Terminal, the Terminal prompts error messages such as the following: + + ```shell + [!] CocoaPods could not find compatible versions for pod "AgoraRtcEngine_iOS": + In Podfile: + AgoraRtcEngine_iOS (= 3.5.0) +None of your spec sources contain a spec satisfying the dependency: `AgoraRtcEngine_iOS (= 3.5.0)`. +``` + +**Reason** + +The local CocoaPods repository is not updated. + +**Solution** + +See the following steps to solve the issue: + +1. Run `pod repo update` in Terminal to update the local CocoaPods repository. +2. Run `pod install` again to install the latest version of the Agora SDK. \ No newline at end of file diff --git a/integration-issues/high-availability.mdx b/integration-issues/high-availability.mdx new file mode 100644 index 0000000..6f32867 --- /dev/null +++ b/integration-issues/high-availability.mdx @@ -0,0 +1,29 @@ +--- +title: 'What does Cloud Recording do when a recording server drops offline or a process gets killed?' +sidebar_position: 658 +platforms: [] +products: [] +--- + + +When this happens, the cloud recording service enables the high availability mechanism, where the fault processing center automatically switches to a new server within 90 seconds to resume the service. + +### Why has the file name of a recording file changed? + +Each time the service enables the high availability mechanism, it creates a new M3U8 file, which contains the index information of the recorded slice files from when the service resumes. The file name is prepended with `bak`, where `n` stands for the number of times the mechanism is enabled in a recording, and starts off with `0`. + +For example, in composite recording mode, the file name of M3U8 is `_.m3u8`. After enabling the high availability mechanism for the first time, the service creates a new M3U8 file with the name of `bak0__.m3u8`. + +After the cloud recording service enables the high availability mechanism, the names of the recorded TS/WebM files are also prepended with `bak`. + +> The service enables the high availability mechanism for a maximum of three times in a recording. It gives up the attempt the fourth time the recording server is disconnected or the process killed. + +### Why do I get a 404 error when I call `query`? + +After the cloud recording enables the high availability mechanism, the fault processing center needs a certain period of time to find the cause of the failure and act accordingly. + +When the service detects that the server process is killed, the fault processing center switches the service to another server within 30 seconds; when the service detects that the server is disconnected, the fault processing center tries to reconnect to that server or switch to a different server if it fails to reconnect within one minute. Before the service resumes, you get a 404 for the method call of `query`, `updateLayout`, or `stop`. + +### Why isn't the UID in the callback notification the same as the recording UID I set? + +After the high availability mechanism is enabled and the service is switched to a new server, the service rejoins the channel with a randomly-generated recording UID, abandoning the old one. \ No newline at end of file diff --git a/integration-issues/integration_with_app_logic.mdx b/integration-issues/integration_with_app_logic.mdx new file mode 100644 index 0000000..bf13751 --- /dev/null +++ b/integration-issues/integration_with_app_logic.mdx @@ -0,0 +1,22 @@ +--- +title: 'How to connect Flexible Classroom with your own user management system and class scheduling system?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +Flexible Classroom enables real-time engagement in classrooms but does not provide user management system and class scheduling system. If you already have a user management system and class scheduling system, refer to the following picture to connect Flexible Classroom with your own systems. + +![](https://web-cdn.agora.io/docs-files/1625827386244) + +You need to implement the following business logic: + +- Deploy an RTM Token generator on your server, and generate an RTM Token with parameters including the Agora App ID, App Certificate, and user ID. For details, see [Generate an RTM Token](https://docs.agora.io/en/Real-time-Messaging/token_server_rtm?platform=All%20Platforms). +- Design a RESTful API for the following three purposes: + - Check whether the user logging into the app exists in your user management system. + - Get the user's personal information and class schedule. + - Get the RTM token generated by the RTM Token Generator. + +After the client gets the user ID, class ID, and RTM token, refer to the [quickstart guide](/en/agora-class/agora_class_quickstart_web) to call the `launch` method in the Agora Classroom SDK and pass in the user ID, class ID, and RTM token to the SDK to join a flexible classroom. + +
  • Please ensure that the user ID and class ID are globally unique.
  • When the first user joins the classroom, Agora automatically creates a classroom. The classroom is destroyed one hour after the last user leaves the classroom. Agora does not store any of your business data.
    • \ No newline at end of file diff --git a/integration-issues/ios_simulator_problem.mdx b/integration-issues/ios_simulator_problem.mdx new file mode 100644 index 0000000..7c57dda --- /dev/null +++ b/integration-issues/ios_simulator_problem.mdx @@ -0,0 +1,94 @@ +--- +title: 'Why does my project build fail when I use the iOS simulator in Xcode 12.3 or later?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +## Problem + +When you integrate the Agora SDK and use an iOS simulator to build a project in Xcode 12.3 or later, you may receive the following error message: + +```swift +Building for iOS Simulator, but the linked and embedded framework 'xxx.framework' was built for iOS + iOS Simulator. +``` + +## Reason + +Starting in Xcode 11.0, Apple recommended against using a single `.framework` file to bundle a binary framework or library for multiple platforms, although they still allowed it. As of Xcode 12.3, however, Apple no longer allows this; instead, you must use an `.xcframework` file. To support running a project on an iOS simulator, versions of the Agora SDK earlier than v3.3.0 bundle a library for multiple platforms in a `.framework` file, so `.framework` files are identified by Xcode as a prohibited configuration when you use an iOS simulator to build a project. + +## Solution + +### Solution one: Upgrade the SDK + +As of v3.3.0, the Agora SDK uses `.xcframework` files in place of `.framework` files, which comply with Xcode's requirements and support running projects on iOS physical devices or iOS simulators. Agora recommends upgrading the SDK to v3.3.0 or later. See [Integrate the SDK](./start_call_ios?platform=iOS#integrate_sdk). + +### Solution two: Change build options + +In Xcode, navigate to **TARGETS > Project Name > Build Settings > Build Options** menu, and set **Validate Workspace** as **Yes**. + +### Solution three: Create .xcframework files + +For the SDK v3.0.0 to v3.2.1, Agora provides an `xcframework.sh` script to create `.xcframework` files based on `.framework` files. Refer to the following steps to use this script: + +1. Create an `xcframework.sh` file, and add the following code to the file: + + ```bash +#!/bin/bash +echo "Start building xcframework..." +AgoraIosFrameworkDir=$1 +cd $AgoraIosFrameworkDir +# Detect the SDK path +if [ ! -d "libs" ]; then + echo "SDK path error, please check!" + exit 1 +fi +cd libs/ +cur_path=`pwd` +framework_suffix=".framework" +frameworks="" +# Find all .framework files under the libs folder +for file in `ls $cur_path`; do + echo $file + if [[ $file == *$framework_suffix* ]]; then + frameworks="$frameworks $file" + fi +done +echo "Frameworks found:$frameworks" +for framework in $frameworks; do + binary_name=${framework%.*} + echo "framework_name is $binary_name" + supported_platforms="\"iPhoneSimulator\"" + # In the Info.plist file under the ALL_ARCHITECTURE/xxx.framework path, change the CFBundleSupportedPlatforms attribute to x86-64 or i386 only + plutil -replace CFBundleSupportedPlatforms -json "[$supported_platforms]" ALL_ARCHITECTURE/$framework/Info.plist || exit 1 + # Remove the armv7 and arm64 architectures in the .framework file under the ALL_ARCHITECTURE folder, and keep the x86-64 or i386 architecture only + lipo -remove armv7 ALL_ARCHITECTURE/$framework/$binary_name -output ALL_ARCHITECTURE/$framework/$binary_name + lipo -remove arm64 ALL_ARCHITECTURE/$framework/$binary_name -output ALL_ARCHITECTURE/$framework/$binary_name + # Use the xcodebuild command to create an .xcframework file based on the devices architecture under the libs folder and the .framework file under the ALL_ARCHITECTURE folder + xcodebuild -create-xcframework -framework $framework -framework ALL_ARCHITECTURE/$framework -output $binary_name.xcframework +done +echo "Build xcframework successfully." +``` + +2. In Terminal, run the following command to create `.xcframework` files: + + ```shell +// Replace the xcframework_path with the path of the xcframework.sh script +cd xcframework_path +// Run the xcframework.sh script +// Replace the sdk_path with the path of the SDK. For example, /Users/agora/Downloads/Agora_Native_SDK_for_iOS_FULL +sh xcframework.sh sdk_path +``` + +3. Navigate to your project folder, delete the `.framework` files, and copy the `.xcframework` files into the folder. + +4. In Xcode (the interface description in this article is based on Xcode 12.3), navigate to **TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content** menu: + + 1. Click **-** to remove `.framework` files. + 2. Click **+ > Add Other… > Add Files** to add the corresponding `.xcframework` files. Ensure the status of these dynamic libraries is **Embed & Sign**. + + For example, with the Video SDK v3.2.0, after you successfully configure the project, you see the following interface: + + ![](https://web-cdn.agora.io/docs-files/1611565418238) + +For more information about creating an `.xcframework` file, see [Create an XCFramework](https://help.apple.com/xcode/mac/11.4/#/dev544efab96). \ No newline at end of file diff --git a/integration-issues/kick_user.mdx b/integration-issues/kick_user.mdx new file mode 100644 index 0000000..7ffcf48 --- /dev/null +++ b/integration-issues/kick_user.mdx @@ -0,0 +1,29 @@ +--- +title: 'How can I remove a specified user from a channel?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +In real-time engagement scenarios, you may need to remove a specified user from a channel. Refer to the following solutions according to your scenario: + +**Scenario one** + +After a call ends, some user (most often a Web user) forgets to leave the channel. Even though no call takes place, Agora adds up service minutes. + +To prevent this from happening, you can detect whether a user is active by using the `onAudioVolumeIndication` callback, or by monitoring whether the user publishes an audio stream within a certain amount of time. If the user is inactive, call `leaveChannel` in the app logic to remove the user from the channel. + +**Scenario two** + +For scheduling apps, calls usually start and end at pre-set time points. For example, if a meeting starts at 10 and lasts for one hour, then the scheduling app should end the meeting at 11. + +Choose either of the following methods to remove the user: + +- Set the token expiration timestamp (the `privilegeExpiredTs` parameter) as the timestamp when the meeting ends. Once the token expires, the user is kicked out of the channel. For details, see [generate a token](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=All%20Platforms). +- Use the server RESTful API to kick a specified user out of the channel. Call the kicking-rule method, and fill the channel name and user ID in the method. Set the `time` parameter as 0, so that the user can join other channels after being kicked. For details, see [create a kicking rule](./rtc_channel_management_restfulapi?platform=RESTful#creates-a-rule). + +**Scenario three** + +In a live streaming channel, the host can kick off a co-host or audience member who violates chatroom rules. + +You can use the peer-to-peer messaging function of the Agora RTM SDK. On the host's client, call `sendMessageToPeer` to notify the remote user to leave channel, and on the remote user's client, call `leaveChannel` after receiving the peer message in the `onMessageReceived` callback. \ No newline at end of file diff --git a/integration-issues/mirrormode.mdx b/integration-issues/mirrormode.mdx new file mode 100644 index 0000000..dba61c5 --- /dev/null +++ b/integration-issues/mirrormode.mdx @@ -0,0 +1,28 @@ +--- +title: 'How can I set a mirror mode?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +As of v3.0.0, Agora Native SDK provides [new methods](#api) for you to obtain the desired video display effect at different stages in a video call. + +## Stage 1. Set a mirror mode for the local view +On the local device, the video stream of the local user is bound to the local view, and the local user can see the display effect of the local view. You can use `mirrorMode` in the `setupLocalVideo` or` setLocalRenderMode` method to set a mirror effect for the local view. It affects only the local user's view on the local device, not any view on the remote device. +
    mirrorMode has a default value, that is, the SDK enables mirror mode at this stage when using the front camera, and disables it when using the rear camera.
    + +## Stage 2. Set a mirror effect for the remote view on the local device +The video stream of a remote user is bound to the corresponding remote view on the local device, and the local user can see the display effect of the remote view. You can use `mirrorMode` in the `setupRemoteVideo` or `setRemoteRenderMode` method to set a mirror effect for the remote view. It affects only the remote user's view on the local device, not any view on the remote device. + +## Stage 3. Set a mirror effect for the video stream to be sent +The local video stream is encoded and then sent to the remote user. You can use `config` in the `setVideoEncoderConfiguration` method to set a mirror effect for the video stream to be sent. It affects only the local user's view on the remote device, not any view on the local device. + + +## API reference +See the following API reference for details: +* [`setLocalVideoMirrorMode (deprecated)`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/cpp/classagora_1_1rtc_1_1_i_rtc_engine.html#a67f08a1ee32d9443a04bb9b293156bde) +* [`setupLocalVideo`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/cpp/classagora_1_1rtc_1_1_i_rtc_engine.html#a744003a9c0230684e985e42d14361f28) +* [`setLocalRenderMode`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/cpp/classagora_1_1rtc_1_1_i_rtc_engine.html#ac433e6e88da91f87c107012cbaf8bb5c) +* [`setupRemoteVideo`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/cpp/classagora_1_1rtc_1_1_i_rtc_engine.html#ac166814787b0a1d8da5f5c632dd7cdcf) +* [`setRemoteRenderMode`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/cpp/classagora_1_1rtc_1_1_i_rtc_engine.html#aaaf8535dcab7ab0d12bdc351b88d09c2) +* [`setVideoEncoderConfiguration`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/cpp/classagora_1_1rtc_1_1_i_rtc_engine.html#a9bcbdcee0b5c52f96b32baec1922cf2e) \ No newline at end of file diff --git a/integration-issues/no_music_unity.mdx b/integration-issues/no_music_unity.mdx new file mode 100644 index 0000000..441265e --- /dev/null +++ b/integration-issues/no_music_unity.mdx @@ -0,0 +1,21 @@ +--- +title: 'Why can't I hear the music when using Unity objects to play the music?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +## Issue description + +When using Unity objects like AudioSource and AudioClip to play the music on an iOS device, you may encounter the following issue: + +- Being able to hear the music at first, but no longer hearing it after joining a channel. +- Being able to hear the music in a channel, but no longer hearing it after leaving the channel. + +## Reason + +When you use Unity objects to play the music before joining a channel, the status of the system `AudioSession` is set to active. After you join or leave a channel, the Agora Unity SDK changes the status of the system `AudioSession` to inactive, which is why you cannot hear the music after joining or leaving a channel. + +## Solution + +Before joining a channel, call `mRtcEngine.SetParameters("{\"che.audio.keep.audiosession\":true}");` to keep the status of the system `AudioSession` as active. This ensures that you can hear the music, even after you join or leave a channel. \ No newline at end of file diff --git a/integration-issues/pod_init_lint_error.mdx b/integration-issues/pod_init_lint_error.mdx new file mode 100644 index 0000000..58b2f68 --- /dev/null +++ b/integration-issues/pod_init_lint_error.mdx @@ -0,0 +1,34 @@ +--- +title: 'Why do I receive error messages after integrating the iOS SDK through CocoaPods and run the pod lib init command?' +sidebar_position: 658 +platforms: [] +products: [] +--- + + +## Problem + +On Xcode 12 or later, if you integrate the iOS SDK 3.3.0 or later through CocoaPods and run the `pod lib lint` command, you may receive the following error message: + +```shell +[iOS] xcodebuild: warning: [CP] Unable to find matching .xcframework slice in ' true ios-armv7_arm64/AgoraRtcKit.framework ios-x86_64-simulator/AgoraRtcKit.framework' for the current build architectures (arm64 x86_64). +``` + +## Reason + +CocoaPods is not compatible with Xcode 12 or later versions, so the `.xcframework` frameworks cannot be linked in your project. + +## Solution + +To solve the problem, do the following: + +1. Install a version earlier than Xcode 12 (for example, Xcode 11). + +2. In Terminal, run the following command to switch the Xcode version. + + ```shell + // Replaces with the path of Xcode 11. + sudo xcode-select -s + ``` + +3. Run the `pod lib lint` command to check whether the `.xcframework` framework is successfully linked. \ No newline at end of file diff --git a/integration-issues/reduce_app_size_ng.mdx b/integration-issues/reduce_app_size_ng.mdx new file mode 100644 index 0000000..d17c100 --- /dev/null +++ b/integration-issues/reduce_app_size_ng.mdx @@ -0,0 +1,64 @@ +--- +title: 'How can I reduce the app size after integrating the v4.x SDK?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +This article describes how to reduce the app size after integrating the v4.0.0 Beta SDK. + +The SDK provides extensions that can be optionally integrated into the project. If you do not need the extension functions, you can directly remove the corresponding extension libraries to reduce the app size. + +The name of extension libraries is suffixed with `Extension`. See the following for details. + + + +### Virtual background library (beta) + +Before calling `enableVirtualBackground` to enable the virtual background, you need to integrate the virtual background library. See [v4.0.0 Beta Release Notes](https://docs.agora.io/en/video-call-4.x-beta/release_android_ng?platform=Android). + +The following table shows the extension library name for each platform and the increase in the app size after integration. + +| Platform | Architecture | Library name | App size increase after integration (KB) | +| :------- | :----------- | :-------------------------------------------- | :--------------------------------------- | +| Android | arm64-v8a | `libagora_segmentation_extension.so` | 2529 | +| Android | armeabi-v7a | `libagora_segmentation_extension.so` | 1643 | +| iOS | arm64 | `AgoraVideoSegmentationExtension.xcframework` | 2343 | +| iOS | armv7 | `AgoraVideoSegmentationExtension.xcframework` | 1646 | +| macOS | arm64 | `AgoraVideoSegmentationExtension.framework` | 2900 | +| macOS | x86_64 | `AgoraVideoSegmentationExtension.framework` | 3297 | +| Windows | x86 | `libagora_segmentation_extension.dll` | 2455 | +| Windows | x86_64 | `libagora_segmentation_extension.dll` | 2766 | + + + +### Video enhancement library + +Before calling `setExtensionProperty` to enable the video enhancement functions, or call `setBeautyEffectOptions` to enable image enhancement options, you need to integrate the video enhancement library. See [v4.0.0 Beta Release Notes](https://docs.agora.io/en/video-call-4.x-beta/release_android_ng?platform=Android). + +The following table shows the extension library name for each platform and the increase in the app size after integration. + +| Platform | Architecture | Library name | App size increase after integration (KB) | +| :------- | :----------- | :------------------------------------- | :--------------------------------------- | +| Android | arm64-v8a | `libagora_video_process_extension.so` | 1306 | +| Android | armeabi-v7a | `libagora_video_process_extension.so` | 944 | +| iOS | arm64 | `AgoraVideoProcessExtension.xcframework` | 7996 | +| iOS | armv7 | `AgoraVideoProcessExtension.xcframework` | 7996 | +| macOS | arm64 | `AgoraVideoProcessExtension.framework` | 2307 | +| macOS | x86_64 | `AgoraVideoProcessExtension.framework` | 2307 | +| Windows | x86 | `libagora_video_process_extension.dll` | 1403 | +| Windows | x86_64 | `libagora_video_process_extension.dll` | 1575 | + +### Super resolution library (beta) + +After integrating the super resolution library, you can call `enableRemoteSuperResolution` to enable super resolution. + +The following table shows the extension library name for each platform and the increase in the app size after integration. + +| Platform | Architecture | Library name | App size increase after integration (KB) | +| ------- | ----------- | ---------------------------------------- | ----------------- | +| Android | arm64-v8a | `libagora_super_resolution_extension.so` | 640 | +| Android | armeabi-v7a | `libagora_super_resolution_extension.so` | 401 | +| iOS | arm64 | `AgoraSuperResolutionExtension.xcframework` | 399 | +| iOS | armv7 | `AgoraSuperResolutionExtension.xcframework` | 397 | + diff --git a/integration-issues/return_404.mdx b/integration-issues/return_404.mdx new file mode 100644 index 0000000..606ed6e --- /dev/null +++ b/integration-issues/return_404.mdx @@ -0,0 +1,15 @@ +--- +title: 'Why do I get a 404 error when I call query after successfully starting a cloud recording?' +sidebar_position: 658 +platforms: [] +products: [] +--- + + +You may get a 404 error for the following reasons: + +- The recording service checks if the parameters are correctly set after a cloud recording starts. The recording may stop if there are issues. Please pay particular attention to your `transcoding` settings. See [How do I set the video profile of the recorded video?](https://docs.agora.io/en/faq/recording_video_profile) for detailed information about setting `transcoding`. +- The third-party storage information, such as `accessKey` or `secretKey,` is incorrect, resulting in a failure to upload the recorded files. If you have enabled [Agora Message Notification Service](https://docs-preview.agoralab.co/en/Agora%20Platform/ncs), you will receive the [`cloud_recording_error`](https://docs.agora.io/en/cloud-recording/cloud_recording_callback_rest?platform=All%20Platforms#a-name1a1-cloud_recording_error) callback when the service detects that your cloud storage settings are incorrect. +- The cloud recording service fails to join the channel because `token` in `clientRequest` is incorrect. Check if your application has App Certificate enabled. If so, ensure you enter the correct [dynamic key](https://docs.agora.io/en/Agora%20Platform/terms?platform=All%20Platforms#token); otherwise, you do not need to set this parameter. See [Set up Authentication](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms). +- The ongoing cloud recording service ends automatically, if no user is in the channel for more than the time period specified by `maxIdleTime`. +- The cloud recording server is disconnected or the process is killed. At this point, you get a 404 for the method call of `query`, `updateLayout`, or `stop`. It may take the fault processing center a maximum of 90 seconds to troubleshoot and act accordingly. You can call `query` again after a certain period of time to query whether the service is back up. See [Fault processing when a cloud recording server is disconnected or the process killed](/en/faq/high-availability) for details. \ No newline at end of file diff --git a/integration-issues/stream_bombing.mdx b/integration-issues/stream_bombing.mdx new file mode 100644 index 0000000..73d02c7 --- /dev/null +++ b/integration-issues/stream_bombing.mdx @@ -0,0 +1,91 @@ +--- +title: 'How to protect interactive live streaming from stream bombing?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +In interactive live streaming, stream bombing refers to confusion caused by incorrect host seat information due to vulnerabilities in your application, or the use of these vulnerabilities by unauthorized users to deliberately disrupt a streaming session. + +Stream bombing can occur in the following scenarios: + +- Online voice chatrooms +- Interactive live video streaming involving multiple hosts + +Typical stream bombing examples include: + +- Due to flaws in your application, the host seat information displayed on the clients does not match the actual number of hosts in the channel, and therefore the audience in the channel cannot identify who is talking. +- An attacker hijacks the signaling messages to prevent the application server from sending status messages to the clients, disrupting host seat updates or room management. +- During live streaming, a troublemaker makes noise or bombards other users with disturbing audio or video content. +- An intruder repeatedly joins a channel with a token that should have expired but has not, because the valid time of the token is set too long. + +## Solutions + +### Locate disruptive users + +The key to stopping stream bombing is to quickly locate any disruptive users. You can use the following methods: + +- **Method one (recommended)** + + Call [`enableAudioVolumeIndication`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#aaec0b8db9458b45d14cdcb3003f76fbe) on the client to enable the [`onAudioVolumeIndication`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler.html#a4d37f2b4d569fa787bb8c0e3ae8cd424) callback. The callback reports which users are speaking and the speakers' volume. Compare the UIDs reported in the callback with the user list maintained on your application server to discover disruptive users. + +- **Method two** + + Call the Agora RESTful API [`https://api.agora.io/dev/v1/channel/user/{appid}/{channelName}`](https://web-cdn.agora.io/docs-cms/swagger/en/rtc/restfulapi/index.html#/Online%20channel%20statistics%20query/userProperty) on your application server regularly to query the user list of a channel. Compare the user list returned by Agora with the user list maintained on your application server to discover disruptive users. + +- **Method three** + + Enable the [Agora message notification service](https://docs-preview.agoralab.co/en/Agora%20Platform/ncs) and subscribe to [real-time communication events](https://docs-preview.agoralab.co/en/Agora%20Platform/rtc_eventtype?platform=All%20Platforms). When receiving the following events, check the user list on your application server to determine whether the newly joined host is authorized. + + - A host joins the channel. + - An audience member switches their hole to host after joining the channel. + +
    Agora Message Notification Service is in the Beta stage. Agora recommends that core apps should not rely on the Message Notification Service.
    + +- **Method four** + If the channel has troublemakers who keep sending pornographic, violent, or politically sensitive voice content, you can use the individual recording mode of Agora Cloud Recording to record the audio and then upload the audio to a third-party content review service. Use the review results to discover the user sending the disruptive content. + +### Manage disruptive users + +After discovering unauthorized users, you need to stop their disruptive behaviors to restore orderly live streaming as soon as possible. You can manage disruptive users in any of the following ways: + +- **Prohibit disruptive users from sending streams.** + Method one: + + Your application server sends a role-switching message to the client of the disruptive user. When it receives the message, the client calls [`setClientRole`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#aa2affa28a23d44d18b6889fba03f47ec) to set the user role as audience, thus removing the user's privilege to send streams. + + Method Two: + + Call the Agora RESTful API [`https://api.agora.io/dev/v1/kicking-rule`](https://docs.agora.io/en/rtc/restfulapi/#/Banning%20rule%20management/createKickingRule) on your application server, and set the `privileges` parameter as `publish_audio` and `publish_video` in the request body to ban disruptive users from sending audio and video streams. + +- **Stop receiving audio streams from disruptive users.** + + If an unauthorized user hijacks the message that your application server sends to its client, your application server can send a mute message to the clients of all authorized users. When receiving the message, the clients call [`muteRemoteAudioStream`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#a3e17b5d2b71d628206d740d895044c5d) to stop receiving unauthorized user's audio stream. + +- **Kick disruptive users out of the channel or block their IP addresses.** + + Call [`https://api.agora.io/dev/v1/kicking-rule`](https://docs.agora.io/en/rtc/restfulapi/#/Banning%20rule%20management/createKickingRule) on your application server to kick unauthorized users out of the channel or block their IP addresses. + To implement the functions, you need to set the `privileges` parameter as `join_channel` in the request body and fill in the `cname`, `uid`, and `ip` fields in one of the following ways: + + - Set `ip`, but not `cname` or `uid` to ban a user with this IP address from joining any channel in the app. + - Set `uid`, but not `cname` or `ip` to ban a user with this ID from joining any channel in the app. + - Set `cname` and `uid`, but not `ip` to ban a user with this ID from joining the channel specified by the `cname` field. + +### Precautions against stream bombing + +You can take the following measures to avoid vulnerabilities and strengthen security, thus protecting your live streaming from disruptions: + +- Optimize your Token management. + + Set the token expiration timestamp (the [`privilegeExpiredTs`](https://docs.agora.io/en/Interactive%20Broadcast/token_server?platform=Android#api-reference) parameter) according to the average user online time in the channel. Once the token expires, all users are removed from the channel. Thus, an unauthorized user cannot repeatedly join a channel with the token. + Listen for the [`onTokenPrivilegeWillExpire`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler.html#a0ecee4bcca9b98dda251a57cfe92adb5) callback to monitor the event that the token is about to expire. Upon receiving this callback, you need to generate a new `token` on the server and call [`renewToken`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_rtc_engine.html#af1428905e5778a9ca209f64592b5bf80) to pass the new `token` to the SDK. + +- Prevent the disclosure of your [App ID and App certificate](https://docs.agora.io/en/Interactive%20Broadcast/token?platform=All%20Platforms). + Agora recommends that you store the App ID and App certificate on your server to keep them secret. If there is a suspected leak, you need to update the App certificate. + +
    Agora recommends updating the App certificate when the number of online users in the channel is at a low level to avoid causing a large number of login failures.
    + +- To avoid the signaling message sent by the server being hijacked, you can establish a timeout mechanism between your server and clients. Only after receiving a confirmation message from the client does the server proceed to the next operation. + For example, when the server sends a notification of switching user role to a client, the timeout timer starts. If the server receives a confirmation message from the client within a specified time, then the server determines the client has switched its user role to audience and then updates the host seat on the UI. + +- To avoid inconsistencies between the channel user list on your application server and the one on the Agora server, you need to monitor the [`onRejoinChannelSuccess` ](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/java/classio_1_1agora_1_1rtc_1_1_i_rtc_engine_event_handler.html#ad222912d35c5f9c22f95f3072feed77d) callback when the network reconnects after interruption and review each user ID that rejoins the channel. \ No newline at end of file diff --git a/integration-issues/switchdevice_web.mdx b/integration-issues/switchdevice_web.mdx new file mode 100644 index 0000000..d016470 --- /dev/null +++ b/integration-issues/switchdevice_web.mdx @@ -0,0 +1,38 @@ +--- +title: 'How can I switch the input device during a web call?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +The Agora Web SDK identifies media input devices by the device ID (`deviceId`). Each device has a unique device ID that you can get by [`getDevices`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/web/globals.html#getdevices). The device ID is randomly generated, and may change for the same device, so Agora recommends calling `getDevices` every time before switching the device. + +
    On Chrome 81 or later, Safari, and Firefox, device IDs are only available after the user has granted permissions to use the media device. See Why can't I get device ID on Chrome 81?
    + +## For the Agora Web SDK v2.5.0 or later + +1. Call `getDevices` to enumerate available devices and get the device IDs. +2. Call [`switchDevice`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/web/interfaces/agorartc.stream.html#switchdevice) after getting the device ID. + +
    switchDevice does not work on Firefox, and cannot switch audio input devices on Safari 11 or earlier. See the API Reference for other limitations.
    + +### Switch cameras on mobile devices + +To switch cameras on mobile devices, for example, switching between the rear camera and the front camera, you need to stop the current video track before calling `switchDevice`. + +``` javascript +switchBtn.onclick=()=>{ + localStream.getVideoTrack().stop(); + localStream.switchDevice("video",devices.value); +}; +``` + +## For versions earlier than v2.5.0 + +Set the `microphoneId` and `cameraId` parameters in the `createStream` method to switch the microphone and camera. + +1. Call [`close`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/web/interfaces/agorartc.stream.html#close) to close the local stream. +2. Call `getDevices` to enumerate available devices and get the device IDs. +3. Call [`createStream`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/web/globals.html#createstream) and fill the [`microphoneId`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/web/interfaces/agorartc.streamspec.html#microphoneid) or [`cameraId`](https://docs.agora.io/en/Interactive%20Broadcast/API%20Reference/web/interfaces/agorartc.streamspec.html#cameraid) parameter with the device ID. + +To use the first input device by default, set `cameraId` and `microphoneId` as `""` in `createStream`. \ No newline at end of file diff --git a/integration-issues/token_error.mdx b/integration-issues/token_error.mdx new file mode 100644 index 0000000..4854e8a --- /dev/null +++ b/integration-issues/token_error.mdx @@ -0,0 +1,94 @@ +--- +title: 'How to solve token-related errors?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +Once you enable the **Primary/Secondary certificate** and the **No certificate** does not exist in your project, you have decided that your app authenticates its users with the dynamic token. + +Tokens expire. During the runtime of your app, you may receive the following error codes or callback events that are related to the token. This article helps you to learn more about the issues, their causes, and how to troubleshoot. + +
    This article applies to the Agora RTC SDK only.
    + +## 101: Invalid app ID + +**Issue description:** + +- Native: The SDK returns `ERR_INVALID_APP_ID(101)` when initializing the Agora service, or reports the `ERR_INVALID_APP_ID(101)` error in the `onError` callback when you try to join a channel by calling `joinChannel`. +- Web: The Console prints `ERR_INVALID_VENDOR_KEY(101)` when the SDK initializes the Agora service, or when you try to join a channel by calling `Client.join`. + +**Reason:** The App ID is invalid, usually because the data format of the App ID is incorrect. + +**Solution:** Check the data format of your App ID. Ensure that you use the correct App ID to initialize the Agora service. + +## 109/118/2: Token expired + +**Issue description:** + +- Native: The SDK reports the `ERR_TOKEN_EXPIRED(109)` error in the `onError` callback when you try to join a channel by calling `joinChannel`. +- Web: The Console prints `ERR_DYNAMIC_KEY_TIMEOUT(109)` or `ERR_DYNAMIC_KEY_EXPIRED(118)` when you try to join a channel by calling `Client.join`. + +**Reason:** The token has expired. + +**Solution:** When a token expires, you need to generate a new token on your server, and try to join the channel by calling `renewToken`. + +## 110: Invalid token + +**Issue description:** + +- Native: The SDK reports `ERR_INVALID_TOKEN(110)` in the onError callback when you try to join a channel by calling `joinChannel`. +- Web: The Console prints `ERR_NO_AUTHORIZED(110)` when you try to to join a channel by calling `Client.join`. + +**Reason:** The token is invalid, usually for the following reasons: + +- Did not provide a token when joining a channel in a situation where you enable the **Primary/Secondary certificate** and the **No certificate** does not exist in your project. +- Tried to join a channel with a token in a situation where the project has not enabled the **Primary/Secondary certificate**. +- The App ID, user ID and channel name that you use to generate the token on the server do not match those that you use when joining a channel. + +**Solution:** + +- Before joining a channel, check whether you has enabled the **Primary/Secondary certificate** for your project. + - If you has not enabled the **Primary/Secondary certificate**, join a channel without a token. + - If you has enabled the **Primary/Secondary certificate** and the **No certificate** exists in your project, you can either complete authentication with the App ID only or use tokens generated by the **Primary/Secondary certificate** for authentication. + - If you has enabled the **Primary/Secondary certificate** and the **No certificate** does not exist in your project, you must provide a token when joining a channel. +- When using a token to join a channel, ensure that the App ID, user ID, and channel name that you use to generate the token is the same as the App ID that you use to initialize the Agora service, and the user ID and channel name that you use to join the channel. + +## 119: Static user using the dynamic key + +
    This error code applies to the Agora RTC Web SDK only.
    + +**Issue description:** The Console prints `ERR_STATIC_USE_DYNAMIC_KEY(119)` when the SDK tries to join a channel by calling Client.join. + +**Reason:** This is because you try to join a channel with a token in a situation where the Agora project has not enabled the **Primary/Secondary certificate**. You can use a token to join a channel only when the **Primary/Secondary certificate** is enabled. + +**Solution:** For projects that have not enabled the **Primary/Secondary certificate**, you can either join a channel without a token, or enable the **Primary/Secondary certificate**, generate a token on your server, and join a channel using that token. + +## 120: Dynamic user using the static key + +
    This error code applies to the RTC Web SDK only.
    + +**Issue description:** The Console prints `ERR_DYNAMIC_USE_STATIC_KEY(120)` when you try to join a channel by calling Client.join. + +**Reason:** This is because you fail to provide a token when joining a channel in the situation where you has enabled the **Primary/Secondary certificate** and the **No certificate** does not exist in your project. + +**Solution:** If you has enabled the **Primary/Secondary certificate** and the **No certificate** does not exist in your project, you must provide a token when joining a channel. You can also initialize the Agora service with an App ID that has not enabled the **Primary/Secondary certificate**. + +## Token callback events + +To ensure smooth communication, Agora provides the following two callback events to remind the user that the token is about to expire, or has expired. + +- `onTokenPrivilegeWillExpire`: Occurs 30 seconds before the token expires. Upon receiving this callback, generate a new token on the server, and call renewToken to pass the new token to the SDK. +- `onRequestToken` (or `onTokenPrivilegeDidExpire` on Web): Occurs when the token expires. Upon receiving this callback, generate a new token on the server, call `joinChannel`, and pass the new token to join the channel. + +## Token-related errors in different programming languages + +| Error code | Java/C++/C# | Objective-C | Javascript | +| ---------------- | ---------------- | ---------------- | ---------------- | +| 101 | `ERR_INVALID_APP_ID` | `AgoraErrorCodeInvalidAppId` | `ERR_INVALID_VENDOR_KEY` | +| 109 | `ERR_TOKEN_EXPIRED` | `AgoraErrorCodeTokenExpired` | `ERR_DYNAMIC_KEY_TIMEOUT` | +| 110 | `ERR_INVALID_TOKEN` | `AgoraErrorCodeInvalidToken` | `ERR_NO_AUTHORIZED` | +| 2 | / | / | `K_TIMESTAMP_EXPIRED` | +| 118 | / | / | `ERR_DYNAMIC_KEY_EXPIRED` | +| 119 | / | / | `ERR_STATIC_USE_DYNAMIC_KEY` | +| 120 | / | / | `ERR_DYNAMIC_USE_STATIC_KEY` | diff --git a/integration-issues/web_on_mobile.mdx b/integration-issues/web_on_mobile.mdx new file mode 100644 index 0000000..d4f251d --- /dev/null +++ b/integration-issues/web_on_mobile.mdx @@ -0,0 +1,62 @@ +--- +title: 'How can I use Agora Web SDK on mobile deivces?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +The Agora Web SDK is based on WebRTC and relies on the browser's support for WebRTC. However, some apps on some mobile devices may not support WebRTC depending on their WebView implementation. This page introduces the support for sending and receiving audio/video streams on mobile webpages. + +## Audio streams + +### iOS + +On iOS, all apps with built-in browsers use the system WebView which does not support sending streams. The following table lists the support for sending and receiving audio streams on three types of mobile webpages. + +| Mobile webpage | Version | +| :---------------------------------------------------------- | :------------------ | +| The built-in browser of WeChat (supports receiving streams) | iOS 12.1.4 or later | +| Apps with built-in WebView (supports receiving streams) | iOS 12.1.4 or later | +| Safari (supports sending and receiving streams) | iOS 11.0 or later | + + +### Android + +Android WebView supports customization, and the system WebView varies by device. The following table lists the support for sending and receiving audio streams on three types of mobile webpages. + +| Mobile webpage | Version | +| :----------------------------- | :----------------------------------------------------------- | +| The built-in browser of WeChat | Depends on the domain name. For example, the `.com` domains support sending and receiving audio streams, while the `.io` domains do not. | +| Apps with built-in WebView | No support on most mobile devices. | +| Chrome 58 or later | Supports sending and receiving streams. | + +
    The support for sending and receiving audio streams on apps with built-in WebView is dependent on the mobile device.
    + +## Video streams + +### iOS + +On iOS, all apps with built-in browsers use the system WebView which does not support sending streams. The following table lists the supported codecs of three types of mobile webpages. + +| | VP8 | H.264 | +| :---------------------------------------------------------- | :---------------- | :------------------ | +| The built-in browser of WeChat (supports receiving streams) | iOS 12.2 or later | iOS 12.1.4 or later | +| Apps with built-in WebView (supports receiving streams) | iOS 12.2 or later | iOS 12.1.4 or later | +| Safari (supports sending and receiving streams) | iOS 12.2 or later | iOS 11 or later | + + +### Android + +Android WebView supports customization, and the system WebView varies by device. The following table lists the supported codecs of three types of mobile webpages. + +| | VP8 | H.264 | +| :----------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- | +| The built-in browser of WeChat | The latest version supports sending and receiving streams. | No support | +| Apps with built-in WebView | Supports sending and receiving streams on some mobile devices. | Supports sending and receiving streams on some mobile devices. | +| Chrome 58 or later | Supports sending and receiving video streams. | Supports sending and receiving streams on some mobile devices | + +
    VP8 and H.264 support on apps with built-in WebView and H.264 support on Chrome are dependent on the mobile device.
    + +### Codec setting + +If all users in the channel use the Agora Web SDK, we recommend setting `codec` as `"vp8"` in the `createClient` method. Refer to the above tables for the supported system and app versions. \ No newline at end of file diff --git a/integration-issues/window_sharing_win7.mdx b/integration-issues/window_sharing_win7.mdx new file mode 100644 index 0000000..0a9788a --- /dev/null +++ b/integration-issues/window_sharing_win7.mdx @@ -0,0 +1,61 @@ +--- +title: 'How can I handle the window-sharing issue on Windows 7?' +sidebar_position: 658 +platforms: [] +products: [] +--- + +## Problem + +When sharing a File Explorer window on Windows 7, the color of the search box of the shared window may appear abnormal (black) to remote users. + + +When sharing a File Explorer window on Windows 7, if the local user stretches or shrinks the height of the window, the search box of the shared window may appear abnormal. + + +## Reason + +When you enable the Aero theme effect on Windows 7, the window has the [WS_EX_LAYERED](https://docs.microsoft.com/en-us/windows/win32/winmsg/extended-window-styles) attribute. As a result, the window image that the Agora SDK gets by GDI (Graphics Device Interface) DC (Device Context) is black. + +## Solution + +To solve this problem caused by the Aero theme effect of the Windows operating system, Agora recommends the following steps. + +1. Determine the version of the Windows operating system before you start window sharing. If it is Windows 7, load the DWM (Desktop Window Manager) API, as follows: + + ```cpp + typedef HRESULT(WINAPI* DwmEnableCompositionFunc)(UINT); + typedef HRESULT(WINAPI* DwmIsCompositionEnabledFunc)(BOOL* pfEnabled); + + DwmIsCompositionEnabledFunc is_composition_enabled_func_; + DwmEnableCompositionFunc composition_func_; + + HMODULE dwmapi_library_ = LoadLibrary(L"dwmapi.dll"); + if (dwmapi_library_) { + is_composition_enabled_func_ = reinterpret_cast( + GetProcAddress(dwmapi_library_, "DwmIsCompositionEnabled")); + composition_func_ = reinterpret_cast( + GetProcAddress(dwmapi_library_, "DwmEnableComposition")); + } + ``` + +2. Determine whether the Aero theme effect is enabled on Windows 7. If so, disable the Aero theme effect, as follows: + + ```cpp + BOOL result = FALSE; + if (is_composition_enabled_func_) + is_composition_enabled_func_(&result); + if(result) { + if (composition_func_） + (*composition_func_)(DWM_EC_DISABLECOMPOSITION); + } + ``` + +3. Start window sharing. + +4. Once you have stopped window sharing, you can restore the Aero theme effect, as follows: + + ```cpp + if (composition_func_） + (*composition_func_)(DWM_EC_ENABLECOMPOSITION); + ```