Documentation

    Configuration Options

    You can customize the behavior of the Co-Browsing API Android SDK through configuration options.

    Setting Configuration

    Use the UpscopeConfiguration.Builder when initializing the SDK:

    val config = UpscopeConfiguration.Builder("YOUR_API_KEY")
    .requireAuthorizationForSession(true)
    .authorizationPromptTitle("Screen Sharing Request")
    .authorizationPromptMessage("Allow {%agentName%|Support} to view your screen?")
    .endOfSessionMessage("Thanks for using screen sharing!")
    .translationsYes("Allow")
    .translationsNo("Decline")
    .build()

Upscope.initialize(applicationContext, config)

    Configuration Options

    Session Authorization

    OptionTypeDefaultDescription
    requireAuthorizationForSessionBoolean(Set through the admin interface)Require user permission before screen sharing starts.
    authorizationPromptTitleString(Set through the admin interface)Custom title for the authorization dialog.
    authorizationPromptMessageString(Set through the admin interface)Custom message for the authorization dialog. Supports placeholders.

    Message Placeholders

    The authorizationPromptMessage supports these placeholders:

    • {%agentName%|fallback} - Agent's name with a fallback if unavailable
    • {%currentDomain%} - App name on Android

    Example:

    .authorizationPromptMessage("{%agentName%|Our support team} would like to view your screen")

    UI Display

    OptionTypeDefaultDescription
    showTerminateButtonBoolean(Set through the admin interface)Show a button to end the screen sharing session.
    endOfSessionMessageString(Set through the admin interface)Message displayed when the session ends.
    stopSessionTextString(Set through the admin interface)Custom text for the stop session button.

    Remote Control

    OptionTypeDefaultDescription
    allowRemoteClickBoolean(Set through the admin interface)Allow agents to remotely tap on the screen.
    allowRemoteScrollBoolean(Set through the admin interface)Allow agents to remotely scroll the screen.
    requireControlRequestBoolean(Set through the admin interface)Require user approval before agents can use remote input.
    controlRequestTitleString(Set through the admin interface)Custom title for the control request prompt.
    controlRequestMessageString(Set through the admin interface)Custom message for the control request prompt.

    Lookup Code

    OptionTypeDefaultDescription
    enableLookupCodeOnShakeBoolean(Set through the admin interface)Show lookup code dialog when device is shaken.
    lookupCodeKeyTitleString(Set through the admin interface)Custom title for the shake detection dialog.
    lookupCodeKeyMessageString(Set through the admin interface)Custom message for shake dialog. Supports {%lookupCode%} placeholder.

    Localization Strings

    OptionTypeDescription
    translationsYesStringCustom text for "Allow" button in authorization prompt.
    translationsNoStringCustom text for "Deny" button in authorization prompt.
    translationsOkStringCustom text for "OK" button.

    Multi-Language Translations

    Every text option (titles, messages, and the strings above) also accepts a map keyed by language code instead of a single string. The translation matching the device language is shown, falling back to en if the device language isn't included:

    .translationsYes(mapOf("en" to "Yes", "it" to "Si"))
.translationsNo(mapOf("en" to "No", "it" to "No"))

    All of these can also be configured per language through the dashboard.

    System Options

    OptionTypeDescription
    autoConnectBooleanAutomatically connect on initialization. Default: true (set through the admin interface).
    regionStringServer region for connections.
    disableFullScreenWhenMaskedBooleanWhen true, full device screen sharing is automatically declined if any masked views are present. (Set through the admin interface)

    Custom Authorization UI

    You can replace the default authorization dialog with your own UI by providing an onSessionRequest listener:

    val config = UpscopeConfiguration.Builder("YOUR_API_KEY")
    .requireAuthorizationForSession(true)
    .onSessionRequest(OnSessionRequestListener { response, agentName ->
        // Show your custom UI here
        // Call response.accept() or response.reject()
        myCustomDialog.show(agentName) { accepted ->
            if (accepted) response.accept() else response.reject()
        }
        // Return a Cancellable for cleanup if the request is dismissed externally
        Cancellable { myCustomDialog.dismiss() }
    })
    .build()

    Similarly, use onControlRequest to customize the remote control authorization prompt:

    val config = UpscopeConfiguration.Builder("YOUR_API_KEY")
    .requireControlRequest(true)
    .onControlRequest(OnControlRequestListener { response ->
        response.accept() // or response.reject()
        null // or return a Cancellable
    })
    .build()

    Use onFullDeviceRequest to intercept an agent's request for full-device screen sharing before the system MediaProjection permission dialog appears. Show your own UI, then call response.accept() to proceed to the system prompt or response.reject() to decline and stay in in-app mode. When this listener is not set, the SDK shows the system permission dialog directly.

    val config = UpscopeConfiguration.Builder("YOUR_API_KEY")
    .onFullDeviceRequest(OnFullDeviceRequestListener { response ->
        // Show your custom UI here
        myDialog.show(
            onAccept = { response.accept() },
            onDecline = { response.reject() }
        )
        // Return a Cancellable invoked if the request is withdrawn before the user responds
        Cancellable { myDialog.dismiss() }
    })
    .build()

    The listener interface is:

    fun interface OnFullDeviceRequestListener {
    fun onFullDeviceRequest(response: SessionRequestResponse): Cancellable?
}

    SessionRequestResponse exposes accept() and reject(). The returned Cancellable (or null) is called for cleanup if the request is withdrawn by the agent before the user responds.

    Full Example

    val config = UpscopeConfiguration.Builder("YOUR_API_KEY")
    .requireAuthorizationForSession(true)
    .authorizationPromptTitle("Screen Share")
    .authorizationPromptMessage("{%agentName%|Support} wants to help you")
    .showTerminateButton(true)
    .endOfSessionMessage("Session ended. Thank you!")
    .stopSessionText("End Session")
    .allowRemoteClick(true)
    .allowRemoteScroll(true)
    .enableLookupCodeOnShake(true)
    .lookupCodeKeyTitle("Your Code")
    .lookupCodeKeyMessage("Share this code: {%lookupCode%}")
    .translationsYes("Yes, share")
    .translationsNo("No thanks")
    .translationsOk("Got it")
    .region("us-east")
    .build()

Upscope.initialize(applicationContext, config)