@upscopeio/react-native-sdk 2026.4.1 → 2026.6.0

package/README.md

@@ -17,16 +17,14 @@ npm install @upscopeio/react-native-sdk
 
 ### iOS
 
-1. **Add UpscopeSDK via SPM** — In Xcode, go to your project > Package Dependencies > `+` and add:
-   ```
-   https://github.com/upscopeio/cobrowsing-ios
-   ```
-   Set version to `~> 1.0`.
+Run `pod install` — the native UpscopeSDK is linked automatically via this SDK's podspec dependency, so its version always matches the published package. No extra steps.
 
-2. **Install pods** (for the RN bridge module):
-   ```bash
-   cd ios && pod install
-   ```
+```bash
+cd ios && pod install
+```
+
+By default the SDK shares only your app's UI. To let agents view the visitor's
+**entire device**, see [Full device sharing (iOS)](#full-device-sharing-ios).
 
 ### Android
 
@@ -118,6 +116,34 @@ function LookupCode() {
 }
 ```
 
+### `useRemoteControlState`
+
+Returns whether an agent currently has remote control of the device.
+
+```tsx
+import { useRemoteControlState } from '@upscopeio/react-native-sdk';
+
+function ControlBadge() {
+  const state = useRemoteControlState();
+  // state: 'inactive' | 'active'
+  return <Text>Remote control: {state}</Text>;
+}
+```
+
+### `useFullDeviceSharingState`
+
+Returns whether full-device (broadcast) sharing is currently running.
+
+```tsx
+import { useFullDeviceSharingState } from '@upscopeio/react-native-sdk';
+
+function SharingBadge() {
+  const state = useFullDeviceSharingState();
+  // state: 'inactive' | 'active'
+  return <Text>Full-device sharing: {state}</Text>;
+}
+```
+
 ### `useUpscope`
 
 Returns a stable object of imperative action methods — safe to destructure and pass as deps.
@@ -158,15 +184,19 @@ useEffect(() => {
 | Event name                | Payload type                  | Description                              |
 | ------------------------- | ----------------------------- | ---------------------------------------- |
 | `connectionStateChanged`  | `ConnectionStateChangedEvent` | Connection state transitioned            |
+| `sessionStateChanged`     | `SessionStateChangedEvent`    | Session state transitioned (current-value)|
 | `sessionStarted`          | `SessionStartedEvent`         | Agent joined and session is active       |
 | `sessionEnded`            | `SessionEndedEvent`           | Session ended (includes reason)          |
-| `customMessageReceived`   | `CustomMessageEvent`          | Arbitrary string from an observer        |
+| `customMessageReceived`   | `CustomMessageEvent`          | Arbitrary string from a viewer           |
 | `error`                   | `UpscopeError`                | Non-fatal SDK error                      |
-| `observerJoined`          | `Observer`                    | New observer connected                   |
-| `observerLeft`            | `ObserverLeftEvent`           | Observer disconnected                    |
-| `observerCountChanged`    | `ObserverCountChangedEvent`   | Total observer count changed             |
+| `viewerJoined`            | `Viewer`                      | New viewer connected                     |
+| `viewerLeft`              | `ViewerLeftEvent`             | Viewer disconnected                      |
+| `viewerCountChanged`      | `ViewerCountChangedEvent`     | Total viewer count changed               |
 | `shortIdChanged`          | `ShortIdChangedEvent`         | Short ID assigned or rotated             |
 | `lookupCodeChanged`       | `LookupCodeChangedEvent`      | Lookup code issued or changed            |
+| `remoteControlStateChanged` | `RemoteControlStateChangedEvent` | Agent gained or lost remote control |
+| `fullDeviceSharingStateChanged` | `FullDeviceSharingStateChangedEvent` | Full-device sharing started or stopped |
+| `fullDeviceRequest`       | `FullDeviceRequestEvent`      | Agent requested full-device sharing — answer with `respondToFullDeviceRequest` |
 
 ## View Masking
 
@@ -199,18 +229,112 @@ interface UpscopeConfig {
   requireAuthorizationForSession?: boolean; // Show a prompt before allowing a session. Default: true.
   autoConnect?: boolean;                 // Connect on initialize(). Default: false.
   region?: string;                       // Override the server region.
-  showBanner?: boolean;                  // Show the native in-session banner.
-  showTerminateButton?: boolean;         // Show an end-session button in the banner.
+  showTerminateButton?: boolean;         // Show an end-session button during a session.
   authorizationPromptTitle?: string;     // Custom title for the session request dialog.
   authorizationPromptMessage?: string;   // Custom message for the session request dialog.
   endOfSessionMessage?: string;          // Message shown when a session ends.
-  stopSessionText?: string;              // Label for the terminate-session button.
+  stopSessionText?: LocalizedString;     // Label for the terminate-session button.
   allowRemoteClick?: boolean;            // Allow agent to send tap events. Default: true.
   allowRemoteScroll?: boolean;           // Allow agent to send scroll events. Default: true.
   requireControlRequest?: boolean;       // Require visitor approval before remote control starts.
+  broadcastAppGroupId?: string;          // iOS only. App Group shared with the Broadcast Upload Extension (enables full-device sharing).
+  broadcastExtensionBundleId?: string;   // iOS only. Bundle id of the Broadcast Upload Extension.
 }
+
+// Translation fields accept either a plain string or a language-keyed map.
+// Keys are BCP-47 language tags; the native SDK picks the best match for the
+// device's preferred languages.
+type LocalizedString = string | { [language: string]: string };
 ```
 
+Example:
+
+```ts
+Upscope.initialize({
+  apiKey: "…",
+  stopSessionText: { en: "Stop", it: "Ferma", "pt-PT": "Parar" },
+});
+```
+
+## Full device sharing (iOS)
+
+Full device sharing lets the agent see the entire device screen (other apps,
+home screen) via ReplayKit. It requires a Broadcast Upload Extension target in
+your app — npm packages can't add app extension targets, so this is a one-time
+manual setup (~10 minutes). Without it, the agent's "Full app sharing" button
+is hidden.
+
+> Android needs no setup: it uses MediaProjection, and the required
+> foreground-service permissions are merged automatically from the SDK's manifest.
+
+### 1. Add the extension target
+
+In Xcode: **File → New → Target → Broadcast Upload Extension**. Name it (e.g.
+`YourAppBroadcast`), uncheck "Include UI Extension".
+
+### 2. Replace the generated SampleHandler
+
+```swift
+import UpscopeSDK
+
+class SampleHandler: UpscopeSampleHandler {}
+```
+
+### 3. Add an App Group to BOTH targets
+
+In **Signing & Capabilities** for your app target *and* the extension target,
+add the **App Groups** capability with the same group, e.g.
+`group.com.yourcompany.yourapp`.
+
+### 4. Declare the group in the extension's Info.plist
+
+```xml
+<key>UpscopeAppGroupId</key>
+<string>group.com.yourcompany.yourapp</string>
+```
+
+Also make sure `NSExtension > RPBroadcastProcessMode` is `2` (sample-buffer
+mode); some Xcode template versions omit it. See the example app's
+[`Info.plist`](example/ios/UpscopeExampleBroadcast/Info.plist).
+
+### 5. Add the extension pod
+
+```ruby
+# Podfile (top level, alongside your app target)
+target 'YourAppBroadcast' do
+  pod 'UpscopeSDK/BroadcastExtension'
+end
+```
+
+Run `pod install`.
+
+### 6. Pass the keys at initialization
+
+```ts
+Upscope.initialize({
+  apiKey: 'your-api-key',
+  broadcastAppGroupId: 'group.com.yourcompany.yourapp',
+  broadcastExtensionBundleId: 'com.yourcompany.yourapp.YourAppBroadcast',
+});
+```
+
+`broadcastAppGroupId` enables the feature (the agent's button appears);
+`broadcastExtensionBundleId` preselects your extension in the iOS picker.
+
+### Notes
+
+- The App Group ID must match in **three** places: both targets' entitlements,
+  the extension's `Info.plist` (`UpscopeAppGroupId`), and `broadcastAppGroupId`.
+- Test on a **physical device** — ReplayKit broadcasts are unreliable on the
+  simulator.
+- Full-device capture cannot mask views. Set
+  `disableFullScreenWhenMasked: true` to automatically end full-device sharing
+  whenever masked content is on screen.
+- Expo managed workflow is not supported (extension targets require a config
+  plugin; not currently provided).
+- A complete working setup is in
+  [`example/ios`](example/ios) (`UpscopeExampleBroadcast` target).
+
 ## API Reference
 
 ### Initialization
@@ -235,6 +359,9 @@ interface UpscopeConfig {
 | `stopSession()`                     | Terminate the active session.                       |
 | `requestAgent()`                    | Request that an agent join.                         |
 | `cancelAgentRequest()`              | Cancel a pending agent-join request.                |
+| `stopRemoteControl()`               | Revoke the agent's remote control, keep the session.|
+| `stopFullDeviceSharing()`           | Stop full-device sharing, revert to in-app, keep the session. |
+| `respondToFullDeviceRequest(id, accept)` | Answer a `fullDeviceRequest` event.            |
 
 ### Data
 
@@ -248,7 +375,7 @@ interface UpscopeConfig {
 
 | Method                              | Description                                         |
 | ----------------------------------- | --------------------------------------------------- |
-| `sendCustomMessage(message)`        | Send a string to all connected observers.           |
+| `sendCustomMessage(message)`        | Send a string to all connected viewers.             |
 
 ### Events
 

package/android/build.gradle.kts

@@ -32,5 +32,5 @@ android {
 
 dependencies {
     implementation("com.facebook.react:react-android")
-    implementation("io.github.upscopeio:upscope-android-sdk:2026.4.6")
+    implementation("io.github.upscopeio:upscope-android-sdk:2026.5.1")
 }

package/android/src/main/kotlin/io/upscope/reactnative/UpscopeModule.kt

@@ -1,19 +1,28 @@
 package io.upscope.reactnative
 
 import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.LifecycleEventListener
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.modules.core.DeviceEventManagerModule
+import io.upscope.sdk.Cancellable
 import io.upscope.sdk.ConnectionState
-import io.upscope.sdk.Observer
+import io.upscope.sdk.FullDeviceSharingState
+import io.upscope.sdk.Viewer
+import io.upscope.sdk.RemoteControlState
 import io.upscope.sdk.SessionEndReason
+import io.upscope.sdk.SessionRequestResponse
+import io.upscope.sdk.SessionState
 import io.upscope.sdk.Upscope
 import io.upscope.sdk.UpscopeConfiguration
 import io.upscope.sdk.UpscopeError
 import io.upscope.sdk.UpscopeListener
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
@@ -33,6 +42,28 @@ class UpscopeModule(
     private var listenerCount = 0
     private var shortIdJob: Job? = null
     private var lookupCodeJob: Job? = null
+    private var sessionStateJob: Job? = null
+    private var remoteControlStateJob: Job? = null
+    private var fullDeviceSharingStateJob: Job? = null
+
+    /** Pending full-device requests awaiting a JS response, keyed by request id. */
+    private val pendingFullDeviceRequests = ConcurrentHashMap<String, SessionRequestResponse>()
+
+    /**
+     * Refreshes the SDK's current activity whenever the host resumes. In-app
+     * capture needs a non-null current activity to produce frames; registering
+     * once at init can race RN startup or go stale after activity changes
+     * (Bug #5 — "Waiting for first frame").
+     */
+    private val lifecycleListener = object : LifecycleEventListener {
+        override fun onHostResume() {
+            reactContext.currentActivity?.let { Upscope.setCurrentActivity(it) }
+        }
+
+        override fun onHostPause() {}
+
+        override fun onHostDestroy() {}
+    }
 
     private val upscopeListener = object : UpscopeListener {
         override fun onConnectionStateChanged(state: ConnectionState) {
@@ -62,10 +93,10 @@ class UpscopeModule(
             sendEvent("sessionEnded", params)
         }
 
-        override fun onCustomMessageReceived(message: String, observerId: String) {
+        override fun onCustomMessageReceived(message: String, viewerId: String) {
             val params = Arguments.createMap().apply {
                 putString("message", message)
-                putString("observerId", observerId)
+                putString("viewerId", viewerId)
             }
             sendEvent("customMessageReceived", params)
         }
@@ -74,23 +105,31 @@ class UpscopeModule(
             sendEvent("error", serializeError(error))
         }
 
-        override fun onObserverJoined(observer: Observer) {
-            sendEvent("observerJoined", serializeObserver(observer))
+        override fun onViewerJoined(viewer: Viewer) {
+            sendEvent("viewerJoined", serializeViewer(viewer))
         }
 
-        override fun onObserverLeft(observerId: String) {
+        override fun onViewerLeft(viewerId: String) {
             val params = Arguments.createMap().apply {
-                putString("observerId", observerId)
+                putString("viewerId", viewerId)
             }
-            sendEvent("observerLeft", params)
+            sendEvent("viewerLeft", params)
         }
 
-        override fun onObserverCountChanged(count: Int) {
+        override fun onViewerCountChanged(count: Int) {
             val params = Arguments.createMap().apply {
                 putInt("count", count)
             }
-            sendEvent("observerCountChanged", params)
+            sendEvent("viewerCountChanged", params)
         }
+
+        // Remote-control and full-device-sharing state are emitted from their
+        // StateFlows in addListener() (current-value, so fresh subscriptions get
+        // the real state). The listener overrides would duplicate those events.
+    }
+
+    init {
+        reactContext.addLifecycleEventListener(lifecycleListener)
     }
 
     override fun initialize(config: ReadableMap) {
@@ -112,6 +151,12 @@ class UpscopeModule(
         if (config.hasKey("region")) {
             builder.region(checkNotNull(config.getString("region")))
         }
+        if (config.hasKey("baseDomain")) {
+            builder.baseDomain(checkNotNull(config.getString("baseDomain")))
+        }
+        if (config.hasKey("disableFullScreenWhenMasked")) {
+            builder.disableFullScreenWhenMasked(config.getBoolean("disableFullScreenWhenMasked"))
+        }
         if (config.hasKey("showTerminateButton")) {
             builder.showTerminateButton(config.getBoolean("showTerminateButton"))
         }
@@ -128,9 +173,12 @@ class UpscopeModule(
         if (config.hasKey("endOfSessionMessage")) {
             builder.endOfSessionMessage(checkNotNull(config.getString("endOfSessionMessage")))
         }
-        if (config.hasKey("stopSessionText")) {
-            builder.stopSessionText(checkNotNull(config.getString("stopSessionText")))
-        }
+        applyLocalized(
+            config,
+            "stopSessionText",
+            setString = { builder.stopSessionText(it) },
+            setMap = { builder.stopSessionText(it) },
+        )
         if (config.hasKey("allowRemoteClick")) {
             builder.allowRemoteClick(config.getBoolean("allowRemoteClick"))
         }
@@ -155,14 +203,35 @@ class UpscopeModule(
         if (config.hasKey("lookupCodeKeyMessage")) {
             builder.lookupCodeKeyMessage(checkNotNull(config.getString("lookupCodeKeyMessage")))
         }
-        if (config.hasKey("translationsYes")) {
-            builder.translationsYes(checkNotNull(config.getString("translationsYes")))
-        }
-        if (config.hasKey("translationsNo")) {
-            builder.translationsNo(checkNotNull(config.getString("translationsNo")))
-        }
-        if (config.hasKey("translationsOk")) {
-            builder.translationsOk(checkNotNull(config.getString("translationsOk")))
+        applyLocalized(
+            config,
+            "translationsYes",
+            setString = { builder.translationsYes(it) },
+            setMap = { builder.translationsYes(it) },
+        )
+        applyLocalized(
+            config,
+            "translationsNo",
+            setString = { builder.translationsNo(it) },
+            setMap = { builder.translationsNo(it) },
+        )
+        applyLocalized(
+            config,
+            "translationsOk",
+            setString = { builder.translationsOk(it) },
+            setMap = { builder.translationsOk(it) },
+        )
+
+        // Bridge the native full-device request hook to the JS event layer:
+        // store the response keyed by a generated id, emit `fullDeviceRequest`,
+        // and return a Cancellable that clears the entry if the SDK cancels the
+        // request externally. JS answers via respondToFullDeviceRequest(id, accept).
+        builder.onFullDeviceRequest { response ->
+            val requestId = UUID.randomUUID().toString()
+            pendingFullDeviceRequests[requestId] = response
+            val params = Arguments.createMap().apply { putString("requestId", requestId) }
+            sendEvent("fullDeviceRequest", params)
+            Cancellable { pendingFullDeviceRequests.remove(requestId) }
         }
 
         val configuration = builder.build()
@@ -203,6 +272,18 @@ class UpscopeModule(
 
     override fun cancelAgentRequest() { Upscope.cancelAgentRequest() }
 
+    override fun stopRemoteControl() { Upscope.stopRemoteControl() }
+
+    override fun stopFullDeviceSharing() { Upscope.stopFullDeviceSharing() }
+
+    override fun respondToFullDeviceRequest(requestId: String, accept: Boolean) {
+        val response = pendingFullDeviceRequests.remove(requestId)
+        if (response == null) {
+            return
+        }
+        if (accept) response.accept() else response.reject()
+    }
+
     override fun getLookupCode() { Upscope.getLookupCode() }
 
     override fun getShortId(promise: Promise) { promise.resolve(Upscope.getShortId()) }
@@ -213,8 +294,9 @@ class UpscopeModule(
 
     /**
      * Called by RN when the JS side adds an event listener. Starts collecting Flow emissions
-     * for shortId and lookupCode on the first listener so we only run these coroutines when
-     * something is actually subscribed.
+     * on the first listener so we only run these coroutines when something is actually
+     * subscribed. State flows are current-value (StateFlow), so a fresh subscription
+     * immediately receives the real current state — the fix for state stuck on remount.
      */
     override fun addListener(eventName: String) {
         listenerCount++
@@ -232,6 +314,30 @@ class UpscopeModule(
                     sendEvent("lookupCodeChanged", p)
                 }
             }
+            sessionStateJob = scope.launch {
+                Upscope.sessionStateFlow.collect { state ->
+                    val p = Arguments.createMap().apply {
+                        putString("state", serializeSessionState(state))
+                    }
+                    sendEvent("sessionStateChanged", p)
+                }
+            }
+            remoteControlStateJob = scope.launch {
+                Upscope.remoteControlStateFlow.collect { state ->
+                    val p = Arguments.createMap().apply {
+                        putString("state", serializeRemoteControlState(state))
+                    }
+                    sendEvent("remoteControlStateChanged", p)
+                }
+            }
+            fullDeviceSharingStateJob = scope.launch {
+                Upscope.fullDeviceSharingStateFlow.collect { state ->
+                    val p = Arguments.createMap().apply {
+                        putString("state", serializeFullDeviceSharingState(state))
+                    }
+                    sendEvent("fullDeviceSharingStateChanged", p)
+                }
+            }
         }
     }
 
@@ -245,8 +351,45 @@ class UpscopeModule(
             listenerCount = 0
             shortIdJob?.cancel()
             lookupCodeJob?.cancel()
+            sessionStateJob?.cancel()
+            remoteControlStateJob?.cancel()
+            fullDeviceSharingStateJob?.cancel()
             shortIdJob = null
             lookupCodeJob = null
+            sessionStateJob = null
+            remoteControlStateJob = null
+            fullDeviceSharingStateJob = null
+        }
+    }
+
+    /**
+     * Applies a translation field that may arrive from JS as either a plain string or a
+     * language-keyed map. The native SDK exposes a [String] and a [Map] builder overload
+     * for each such field; we dispatch to whichever matches the runtime value and silently
+     * skip any other type so the server-provided default remains in effect.
+     */
+    private fun applyLocalized(
+        config: ReadableMap,
+        key: String,
+        setString: (String) -> Unit,
+        setMap: (Map<String, String>) -> Unit,
+    ) {
+        if (!config.hasKey(key)) return
+        when (config.getType(key)) {
+            ReadableType.String -> config.getString(key)?.let(setString)
+            ReadableType.Map -> {
+                val map = config.getMap(key) ?: return
+                val entries = mutableMapOf<String, String>()
+                val iter = map.keySetIterator()
+                while (iter.hasNextKey()) {
+                    val entryKey = iter.nextKey()
+                    if (map.getType(entryKey) == ReadableType.String) {
+                        map.getString(entryKey)?.let { entries[entryKey] = it }
+                    }
+                }
+                setMap(entries)
+            }
+            else -> Unit
         }
     }
 
@@ -265,6 +408,24 @@ class UpscopeModule(
         is ConnectionState.Error -> "error"
     }
 
+    private fun serializeSessionState(state: SessionState): String = when (state) {
+        SessionState.INACTIVE -> "inactive"
+        SessionState.PENDING_REQUEST -> "pendingRequest"
+        SessionState.ACTIVE -> "active"
+        SessionState.PAUSED -> "paused"
+        SessionState.ENDED -> "ended"
+    }
+
+    private fun serializeRemoteControlState(state: RemoteControlState): String = when (state) {
+        RemoteControlState.INACTIVE -> "inactive"
+        RemoteControlState.ACTIVE -> "active"
+    }
+
+    private fun serializeFullDeviceSharingState(state: FullDeviceSharingState): String = when (state) {
+        FullDeviceSharingState.INACTIVE -> "inactive"
+        FullDeviceSharingState.ACTIVE -> "active"
+    }
+
     private fun serializeEndReason(reason: SessionEndReason): String = when (reason) {
         is SessionEndReason.UserStopped -> "userStopped"
         is SessionEndReason.AgentStopped -> "agentStopped"
@@ -277,13 +438,14 @@ class UpscopeModule(
         putString("message", error.message)
     }
 
-    private fun serializeObserver(observer: Observer): WritableMap = Arguments.createMap().apply {
-        putString("id", observer.id)
-        putString("name", observer.name)
-        putDouble("screenWidth", observer.screenWidth)
-        putDouble("screenHeight", observer.screenHeight)
-        putDouble("windowWidth", observer.windowWidth)
-        putDouble("windowHeight", observer.windowHeight)
-        putBoolean("hasFocus", observer.hasFocus)
+    private fun serializeViewer(viewer: Viewer): WritableMap = Arguments.createMap().apply {
+        putString("id", viewer.id)
+        putString("name", viewer.name)
+        putDouble("screenWidth", viewer.screenWidth)
+        putDouble("screenHeight", viewer.screenHeight)
+        putDouble("screenScale", viewer.screenScale)
+        putDouble("windowWidth", viewer.windowWidth)
+        putDouble("windowHeight", viewer.windowHeight)
+        putBoolean("hasFocus", viewer.hasFocus)
     }
 }

package/ios/UpscopeModule.mm

@@ -13,6 +13,9 @@ RCT_EXTERN_METHOD(updateConnection:(NSDictionary *)params)
 RCT_EXTERN_METHOD(stopSession)
 RCT_EXTERN_METHOD(requestAgent)
 RCT_EXTERN_METHOD(cancelAgentRequest)
+RCT_EXTERN_METHOD(stopRemoteControl)
+RCT_EXTERN_METHOD(stopFullDeviceSharing)
+RCT_EXTERN_METHOD(respondToFullDeviceRequest:(NSString *)requestId accept:(BOOL)accept)
 RCT_EXTERN_METHOD(getLookupCode)
 RCT_EXTERN_METHOD(getShortId:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)
 RCT_EXTERN_METHOD(getWatchLink:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject)