Full Device Screen Sharing

By default, the Co-Browsing API React Native SDK shares only your app's screen. With full device screen sharing, agents can see the entire device screen, including other apps, the home screen, and system UI.

On iOS this uses Apple's Broadcast Upload Extension (ReplayKit); on Android it uses the MediaProjection API. Both need a little native setup, described below.

Physical devices only

Full device screen sharing only works on physical devices. It is not supported on the iOS Simulator or Android emulators.

Full device screen sharing must also be enabled in the Co-Browsing API dashboard (admin interface) in addition to the steps below.

iOS setup

Full device capture on iOS runs in a Broadcast Upload Extension — a separate native target in your app's Xcode project (under ios/). It sends frames to your app through an App Group, and the SDK relays them to the agent.

1. Add the extension dependency

In your app's ios/Podfile, add the broadcast subspec to the extension target. Do not pin a version — it follows the UpscopeSDK version that @upscopeio/react-native-sdk already requires:

target 'YourAppBroadcast' do
  pod 'UpscopeSDK/BroadcastExtension'
end

Then run pod install from the ios/ directory.

2. Create the Broadcast Upload Extension target

Open ios/YourApp.xcworkspace in Xcode
Go to File > New > Target
Select Broadcast Upload Extension
Uncheck "Include UI Extension"
Name it (e.g., YourAppBroadcast — match the target name used in the Podfile above)
The bundle identifier must be prefixed with your main app's bundle identifier (e.g., com.yourcompany.yourapp.broadcast)

3. Configure App Groups

Both your main app and the extension need to share data through an App Group:

Select your main app target > Signing & Capabilities > + Capability > App Groups
Add a group identifier (e.g., group.com.yourcompany.yourapp)
Select your extension target > Signing & Capabilities > + Capability > App Groups
Add the same group identifier

4. Configure the extension's Info.plist

Add the App Group identifier to the extension's Info.plist:

<key>UpscopeAppGroupId</key>
<string>group.com.yourcompany.yourapp</string>

5. Implement the extension

Replace the contents of the extension's SampleHandler.swift with:

import UpscopeBroadcastExtension

class SampleHandler: UpscopeSampleHandler {}

All frame capture and forwarding is handled by UpscopeSampleHandler.

6. Configure the SDK

Pass the App Group and extension bundle identifiers when initializing the SDK:

import Upscope from '@upscopeio/react-native-sdk';

Upscope.initialize({
  apiKey: 'YOUR_API_KEY',
  broadcastAppGroupId: 'group.com.yourcompany.yourapp',
  broadcastExtensionBundleId: 'com.yourcompany.yourapp.broadcast',
});

If you do not set broadcastAppGroupId, the SDK will not advertise full device support on iOS, and agent requests for it are declined automatically.

Android setup

Add the screen-capture permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />

The SDK already declares the capture service and activity. It detects these permissions at runtime — if they are missing, full device screen sharing is disabled regardless of the dashboard setting. No further configuration is required; Android shows the system screen-capture permission dialog when sharing starts.

Responding to full device requests

Unlike the native iOS SDK (which can present the system picker automatically), the React Native SDK always routes full device requests to your JavaScript code. You must listen for fullDeviceRequest and respond, or requests will never proceed:

import { useEffect } from 'react';
import Upscope from '@upscopeio/react-native-sdk';

useEffect(() => {
  const subs = [
    Upscope.addListener('fullDeviceRequest', ({ requestId }) => {
      // Optionally show your own confirmation UI here, then respond:
      Upscope.respondToFullDeviceRequest(requestId, true); // false to decline
    }),

    Upscope.addListener('fullDeviceSharingStateChanged', ({ state }) => {
      console.log('Full device sharing:', state); // 'active' | 'inactive'
    }),
  ];

  return () => subs.forEach((s) => s.remove());
}, []);

After you accept, iOS shows the system broadcast picker (the user taps Start Broadcast) and Android shows the screen-capture dialog (the user taps Start now). End sharing programmatically at any time:

Upscope.stopFullDeviceSharing();

The user can also stop sharing from iOS Control Center or the Android capture notification; the SDK reports this via fullDeviceSharingStateChanged.

Limitations

Works on physical devices only (not the iOS Simulator or Android emulators)
Element masking is not available in full device mode (the SDK cannot inspect views outside your app)
Remote control only works within your app, not on the home screen or other apps
Drawing annotations are not displayed in full device mode
The user must explicitly start the broadcast/capture via the system prompt — it cannot be started programmatically

Documentation