Upscope Flutter Plugin

A Flutter plugin that wraps the native Upscope cobrowsing SDKs for Android and iOS.

Overview

This plugin provides a unified Flutter API for integrating Upscope's cobrowsing functionality into your Flutter applications. It supports both Android and iOS platforms through a federated plugin architecture.

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  upscope_flutter: ^2025.7.6

Usage

Basic Setup

import 'package:upscope_flutter/upscope_flutter.dart';

// Basic initialization
final upscopeManager = await Upscope.initialize('your-api-key');

// Advanced initialization with configuration and connection parameters
final config = UpscopeConfiguration(
  requireAuthorizationForSession: true,
  enableLookupCodeOnShake: true,
);

final upscopeManager = await Upscope.initialize(
  'your-api-key',
  config: config,
  agentPrompt: 'How can I help you today?',
  identities: ['user123', 'premium_user'],
  integrationIds: ['zendesk', 'salesforce'],
  tags: ['mobile', 'flutter'],
  uniqueId: 'unique-user-identifier',
  metadata: {'app_version': '1.0.0', 'user_type': 'premium'},
);

Connecting and Managing Sessions

// Connect to Upscope
await upscopeManager.connect();

// Get lookup code for session
final lookupCode = await upscopeManager.getLookupCode();
print('Lookup code: $lookupCode');

// Send custom message
await upscopeManager.customMessage('Hello from Flutter!');

// Stop session
await upscopeManager.stopSession();

// Disconnect
await upscopeManager.disconnect();

Event Handling

// Subscribe to connection status changes
upscopeManager.subscribeToIsConnected((isConnected) {
  print('Connection status changed: $isConnected');
});

// Subscribe to recording status changes
upscopeManager.subscribeToIsRecording((isRecording) {
  print('Recording status changed: $isRecording');
});

// Subscribe to short ID changes
upscopeManager.subscribeToShortId((shortId) {
  print('Short ID: $shortId');
});

Content Redaction

The plugin supports redacting sensitive content during screen sharing:

import 'package:upscope_flutter/upscope_flutter.dart';

// Method 1: Using UpscopeRedacted widget
UpscopeRedacted(
  child: Text('Sensitive information'),
)

// Method 2: Using extension method
Text('Credit card number').markAsRedacted()

// Method 3: Conditional redaction
UpscopeRedacted(
  enabled: shouldRedact,
  child: Text('Conditionally sensitive data'),
)

Redacted content will be hidden during screen capture while remaining visible to the app user.

Basic Redaction Usage

import 'package:upscope_flutter/upscope_flutter.dart';

// Method 1: Using the UpscopeRedacted widget
UpscopeRedacted(
  child: Text('Sensitive information'),
  enabled: true, // Optional, defaults to true
)

// Method 2: Using the extension method (recommended)
Text('Credit Card: 4532-1234-5678-9012').markAsRedacted()

// Method 3: Conditionally redact content
TextField(
  decoration: InputDecoration(labelText: 'Password'),
  obscureText: true,
).markAsRedacted(enabled: shouldRedact)

Advanced Redaction Examples

// Redacting form fields
class SensitiveForm extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // Normal field - visible in cobrowsing
        TextField(
          decoration: InputDecoration(labelText: 'Email'),
        ),

        // Redacted field - appears as black rectangle
        TextField(
          decoration: InputDecoration(labelText: 'Password'),
          obscureText: true,
        ).markAsRedacted(),

        // Conditionally redacted content
        Container(
          padding: EdgeInsets.all(16),
          child: Text('SSN: 123-45-6789'),
        ).markAsRedacted(enabled: isDataSensitive),
      ],
    );
  }
}

Redaction in Lists and Scrollable Content

// Redacting specific list items
ListView.builder(
  itemCount: items.length,
  itemBuilder: (context, index) {
    final item = items[index];
    final isRedacted = item.isSensitive;

    Widget listTile = ListTile(
      title: Text(item.title),
      subtitle: Text(item.content),
    );

    // Apply redaction to sensitive items
    return isRedacted ? listTile.markAsRedacted() : listTile;
  },
)

Global Redaction Configuration

// Configuration is now optional since all fields are optional
final config = UpscopeConfiguration(
  requireAuthorizationForSession: true,
  enableLookupCodeOnShake: true,
);

final upscopeManager = await Upscope.initialize('your-api-key', config);

// Or initialize with minimal configuration
final upscopeManager = await Upscope.initialize('your-api-key');

Initialization Parameters

The Upscope.initialize method supports the following parameters:

Required Parameters

Parameter	Type	Description
`apiKey`	`String`	Your Upscope API key

Optional Connection Parameters

Parameter	Type	Description
`agentPrompt`	`String?`	Custom prompt text shown to agents
`identities`	`List<String>?`	Array of identity strings for the user
`integrationIds`	`List<String>?`	Array of integration identifiers (e.g., 'zendesk')
`tags`	`List<String>?`	Array of tags for categorization (e.g., 'mobile')
`uniqueId`	`String?`	Unique identifier for the user/session
`secretKey`	`String?`	Secret key for additional authentication
`metadata`	`Map<String, String>?`	Additional metadata as key-value pairs

Usage Examples

// Minimal initialization
final manager = await Upscope.initialize('your-api-key');

// With user identification
final manager = await Upscope.initialize(
  'your-api-key',
  identities: ['user123', 'premium_tier'],
  uniqueId: 'user-unique-id',
  tags: ['mobile', 'ios'],
);

// With integrations and metadata
final manager = await Upscope.initialize(
  'your-api-key',
  integrationIds: ['zendesk', 'salesforce'],
  metadata: {
    'app_version': '1.0.0',
    'user_tier': 'premium',
    'platform': 'flutter',
  },
);

Configuration Options

The UpscopeConfiguration class supports the following options (all fields are optional):

Parameter	Type	Default	Description
`beta`	`bool?`	`null`	Enable beta features
`teamDomain`	`String?`	`null`	Team domain for authentication
`showUpscopeLink`	`bool?`	`null`	Show Upscope branding link
`showTerminateButton`	`bool?`	`null`	Show session terminate button
`enableLookupCodeOnShake`	`bool?`	`null`	Enable lookup code display on device shake
`lookupCodeKeyTitle`	`String?`	`null`	Custom title for lookup code dialog
`lookupCodeKeyMessage`	`String?`	`null`	Custom message for lookup code dialog
`requireAuthorizationForSession`	`bool?`	`null`	Require user authorization before starting session
`authorizationPromptTitle`	`String?`	`null`	Custom authorization prompt title
`authorizationPromptMessage`	`String?`	`null`	Custom authorization prompt message
`endOfScreenshareMessage`	`String?`	`null`	Custom message when screenshare ends
`translationsYes`	`String?`	`null`	Custom "Yes" translation
`translationsNo`	`String?`	`null`	Custom "No" translation
`translationsOk`	`String?`	`null`	Custom "OK" translation
`translationsStopSession`	`String?`	`null`	Custom "Stop Session" translation
`autoconnect`	`bool?`	`null`	Automatically connect on initialization
`region`	`String?`	`null`	Override default region

Platform-Specific Setup

Android

The plugin automatically includes the Upscope Android SDK.
Add required permissions to android/app/src/main/AndroidManifest.xml:

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

iOS

Add the Upscope iOS SDK to your app's ios/Podfile:

platform :ios, '16.0'  # Required for UpscopeIO SDK

target 'Runner' do
  use_frameworks!

  # Add Upscope iOS SDK
  pod 'UpscopeIO', '~> 2025.7.1'

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

Note: UpscopeIO requires iOS 16.0 or later as the minimum deployment target.

Run pod install in the ios directory to install dependencies.
For full-screen capture, add screen recording capability to your app's entitlements.

API Reference

UpscopeManager

The main class for interacting with the Upscope SDK.

Methods

initialize(String apiKey, {UpscopeConfiguration? config, String? agentPrompt, List<String>? identities, List<String>? integrationIds, List<String>? tags, String? uniqueId, String? secretKey, Map<String, String>? metadata}) - Initialize the SDK
connect() - Connect to Upscope servers
disconnect() - Disconnect from servers
reset() - Reset SDK state
getShortId() - Get session short ID
getLookupCode() - Get/generate lookup code
updateConnection({Map<String, dynamic>? metadata}) - Update connection metadata
getWatchLink() - Get session watch URL
stopSession() - End current session
customMessage(String message) - Send custom message
declineSession() - Decline incoming session
getIsConnected() - Get connection status
getIsConnecting() - Get connecting status
getIsRecording() - Get recording status
getUniqueConnectionId() - Get unique connection identifier

Event Subscriptions

subscribeToIsConnected(Function(bool) callback)
subscribeToIsRecording(Function(bool) callback)
subscribeToShortId(Function(String) callback)
subscribeToLookupCode(Function(String) callback)
subscribeToUniqueConnectionId(Function(String) callback)

UpscopeOverlayView

A widget for displaying native overlay content.

Properties

onViewCreated - Callback when the native view is created
layoutDirection - Layout direction for the view
gestureRecognizers - Gesture recognizers to attach to the view

Troubleshooting

Common Issues

Plugin not found: Ensure you've added the plugin to your pubspec.yaml and run flutter pub get
Platform not supported: This plugin only supports Android and iOS

License

This plugin is provided under the same license as the Upscope SDKs. Please refer to Upscope's official documentation and licensing terms for production use.

Support

For support with the Upscope service itself, please contact Upscope support. For issues with this Flutter plugin, please file an issue in this repository.