Screen sharing enables the host of an interactive live streaming broadcast or video call to display what is on their screen to other users in the channel. This technology has many obvious advantages for communicating information, particularly in the following scenarios:
As of v3.7.0, Agora provides the React Native API for screen sharing. This page describes how to implement screen sharing on Android and iOS platforms using the React Native SDK v3.7.0 and later.
Before you begin, ensure that you understand how to start a video call or start interactive video streaming. For details, see Start a Video Call or Start Interactive Video Streaming.
To implement screen sharing on the Android platform, you only need to call startScreenCapture
to enable screen sharing. You can refer to example/src/examples/advanced/ScreenSharing/ScreenSharing.tsx
in react-native-agora to implement screen sharing.
Screen sharing on iOS is implemented by using the native iOS ReplayKit framework in an Extension to record the screen and by treating the screen sharing stream as a user joining the channel. As Apple does not support screen capture in the main app process, you need to create a separate Extension for the screen sharing stream.
Go to your project directory, and open ios/.xcodeproj
with Xcode.
Ensure that AgoraReplayKitExtension.xcframework
is integrated into the project. This dynamic library wraps the following functionality:
Create a Broadcast Upload Extension to enable the screen sharing process:
a. In Xcode, click File > New > Target..., select Broadcast Upload Extension in the pop-up window, and click Next.
b. In the pop-up window, fill in Product Name and other fields, uncheck Include UI Extension, and click Finish. Xcode automatically creates the Extension folder, which contains the SampleHandler.h
file.
c. Under Target, select the Extension you have created, click General, and set the iOS version to 12.0 or later under Deployment Info.
d. Modify the SampleHandler.h
file to modify the code logic that implements screen sharing:
If you only need to use the functionality in AgoraReplayKitExtension.xcframework
provided by Agora, modify it by checking Target
for the Extension you created, and setting the Value of the NSExtension > NSExtensionPrincipalClass key in the Info settings from SampleHandler to AgoraReplayKitHandler.
If you need to add some business logic in addition to using the functionality in AgoraReplayKitExtension.xcframework
provided by Agora, modify it by replacing the code in the SampleHandler.h
file with the following code:
// Objective-C
#import "SampleHandler.h"
#import "AgoraReplayKitExt.h"
#import <sys/time.h>
@interface SampleHandler ()<AgoraReplayKitExtDelegate>
@end
@implementation SampleHandler
- (void)broadcastStartedWithSetupInfo:(NSDictionary<NSString *,NSObject *> *)setupInfo {
// User has requested to start the broadcast. Setup info from the UI extension can be supplied but optional.
[[AgoraReplayKitExt shareInstance] start:self];
}
- (void)broadcastPaused {
// User has requested to pause the broadcast. Samples will stop being delivered.
NSLog(@"broadcastPaused");
[[AgoraReplayKitExt shareInstance] pause];
}
- (void)broadcastResumed {
// User has requested to resume the broadcast. Samples delivery will resume.
NSLog(@"broadcastResumed");
[[AgoraReplayKitExt shareInstance] resume];
}
- (void)broadcastFinished {
// User has requested to finish the broadcast.
NSLog(@"broadcastFinished");
[[AgoraReplayKitExt shareInstance] stop];
}
- (void)processSampleBuffer:(CMSampleBufferRef)sampleBuffer withType:(RPSampleBufferType)sampleBufferType {
[[AgoraReplayKitExt shareInstance] pushSampleBuffer:sampleBuffer withType:sampleBufferType];
}
#pragma mark - AgoraReplayKitExtDelegate
- (void)broadcastFinished:(AgoraReplayKitExt *_Nonnull)broadcast reason:(AgoraReplayKitExtReason)reason {
switch (reason) {
case AgoraReplayKitExtReasonInitiativeStop:
{
// NSDictionary *userInfo = @{NSLocalizedDescriptionKey : @"Host app stop srceen capture"};
// NSError *error = [NSError errorWithDomain:NSCocoaErrorDomain code:0 userInfo:userInfo];
// [self finishBroadcastWithError:error];
NSLog(@"AgoraReplayKitExtReasonInitiativeStop");
}
break;
case AgoraReplayKitExtReasonConnectFail:
{
// NSDictionary *userInfo = @{NSLocalizedDescriptionKey : @"Connect host app fail need startScreenCapture in host app"};
// NSError *error = [NSError errorWithDomain:NSCocoaErrorDomain code:0 userInfo:userInfo];
// [self finishBroadcastWithError:error];
NSLog(@"AgoraReplayKitExReasonConnectFail");
}
break;
case AgoraReplayKitExtReasonDisconnect:
{
// NSDictionary *userInfo = @{NSLocalizedDescriptionKey : @"disconnect with host app"};
// NSError *error = [NSError errorWithDomain:NSCocoaErrorDomain code:0 userInfo:userInfo];
// [self finishBroadcastWithError:error];
NSLog(@"AgoraReplayKitExReasonDisconnect");
}
break;
default:
break;
}
}
@end
Call startScreenCapture
, and prompt the user's manual action to make the app start screen sharing. You can choose either of the following two methods:
RPSystemBroadcastPickerView
is limited in use and might fail in later versions of iOS systems. Therefore, if Method 1 fails, use Method 2 instead.Agora provides an example of screen sharing in react-native-agora, where you can refer to the following files to implement screen sharing:
example/ios/ScreenSharing/SampleHandler.m
example/src/examples/advanced/ScreenSharing/ScreenSharing.tsx
If you use Cocoapods, add the following lines to the Podfile
file to add dependencies for your screen sharing Extension. Remember to replace ScreenSharing
with the target name of your screen sharing Extension.
target 'ScreenSharing' do
pod 'AgoraRtcEngine_iOS', '3.7.0.3'
end
node_modules/react-native-agora/react-native-agora.podspec
file.The memory limit of a Broadcast Upload Extension is 50 MB. Ensure that your memory usage does not exceed this limit.
In the screen sharing process, you need to call muteAllRemoteVideoStreams
and muteAllRemoteAudioStreams
to cancel receiving streams from remote users and avoid double subscriptions.
Some restrictions and cautions exist for using the screen sharing feature, and charges can apply. Agora recommends that you read the following API references before calling the API: