react-native-agora Documentation

When using the PiP feature, follow these best practices for memory management and UI customization:

Memory Management

Always dispose of the AgoraPipController when it is no longer needed to prevent memory leaks.

iOS Control Styles

You can customize the appearance of the PiP window on iOS using the following control style indices:

• 0: All system controls (default)
• 1: Hide forward/backward buttons
• 2: Hide play/pause and progress bar (recommended for video conferencing)
• 3: Hide all controls

iOS requires specific capabilities and user-initiated actions for PiP to function correctly.

1. Configure Background Modes

In Xcode:

1. Select your app's target and go to the Signing & Capabilities tab.
2. Click the + Capability button.
3. Add Background Modes.
4. Select Audio, AirPlay, and Picture in Picture.

2. Camera Access in Multitasking (Optional)

If you need to show the local video stream in the PiP window while multitasking:

• iOS < 16: You must request the com.apple.developer.avfoundation.multitasking-camera-access entitlement from Apple.
• iOS ≥ 16: Set multitaskingCameraAccessEnabled to true in the capture session (feature coming soon).

3. Important iOS Requirement

PiP must be initiated by a user action on iOS. Programmatic or automatic activation may lead to App Store rejection.

To enable Picture-in-Picture on Android, you must declare support in your AndroidManifest.xml and ensure your MainActivity inherits from AgoraPIPActivity to handle automatic PiP mode entry (especially for Android 12+).

1. Update AndroidManifest.xml

Add android:supportsPictureInPicture="true" and include the necessary android:configChanges to your activity:

<activity android:name=".MainActivity"
    android:supportsPictureInPicture="true"
    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation"
    ...

2. Configure MainActivity

Inherit from AgoraPIPActivity to leverage built-in automatic PiP activation when the app goes to the background. If you need to customize this behavior, you can implement the AgoraPIPActivityProxy interface.

To install the SDK in a React Native project (version >= 0.60.0), use npm or yarn, then install the iOS dependencies using CocoaPods.

Note: This SDK is designed for Agora Video 4.x APIs. For older 3.x versions, refer to the 3.x branch.

# Using yarn
yarn add react-native-agora

# Or using npm
npm i --save react-native-agora

# For iOS
cd ios && pod install

Agora SDK requires specific minimum SDK versions. Use expo-build-properties to configure these in your app.json.

Requirements:

• Android: minSdkVersion = 24
• iOS: deploymentTarget = 12.4+

Setup:

1. Install the plugin:

   npx expo install expo-build-properties --save-dev

2. Configure app.json:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "minSdkVersion": 24
          },
          "ios": {
            "deploymentTarget": "12.4"
          }
        }
      ]
    ]
  }
}

To use Agora in an Expo-managed application, you must use expo-dev-client to enable native module support. Follow these steps to initialize your project:

1. Create the Expo app:

   npx create-expo-app my-agora-app && cd my-agora-app

2. Install expo-dev-client:

   npx expo install expo-dev-client

3. Install the Agora SDK:

   npx expo install react-native-agora

4. Test the build (this compiles the project using local Android SDK or Xcode):
   • Android: npx expo run:android
   • iOS: npx expo run:ios

Agora allows you to create and send custom data streams (up to 5 per user) for non-media data.

1. Create a stream: Use createDataStreamEx(config, connection) to get a streamId.
2. Send data: Use sendStreamMessageEx(streamId, data, length, connection) to broadcast data to all users in the channel.

Restrictions:

• Max 5 data channels per client.
• Total sending bitrate limit: 30 KB/s.
• Max 60 packets per second per channel.
• Max 1 KB per packet.

// 1. Create the stream
const streamId = engineEx.createDataStreamEx(dataStreamConfig, connection);

// 2. Send data
const data = new Uint8Array([0x01, 0x02, 0x03]);
engineEx.sendStreamMessageEx(streamId, data, data.length, connection);

If your application does not use the screen sharing feature, you can exclude the screen sharing extension in your project-level build.gradle to avoid requiring the FOREGROUND_SERVICE_MEDIA_PROJECTION permission.

// build.gradle (project-level)

configurations.configureEach {
    exclude group: "io.agora.rtc", module: "full-screen-sharing"
}

If you encounter a pod install error stating that targets have libraries with conflicting names (e.g., libcrypto.a), you must disable Flipper in your iOS configuration. This is common if you have use_frameworks! enabled.

1. In your Podfile, comment out the Flipper configuration:

# add_flipper_pods!
# post_install do |installer|
#   flipper_post_install(installer)
# end

2. Comment out the Flipper initialization code in your AppDelegate.

# Disable these lines in Podfile if pod install fails due to conflicting names
add_flipper_pods!
post_install do |installer|
  flipper_post_install(installer)
end

To start using the SDK, import createAgoraRtcEngine and initialize it with your Agora App ID. This creates the engine instance required for all RTC operations.

import { createAgoraRtcEngine } from 'react-native-agora';

const engine = createAgoraRtcEngine();
engine.initialize({ appId: 'YOUR APP ID' });