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 #

Optional Connection Parameters #

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):

Platform-Specific Setup #

Android #

1. The plugin automatically includes the Upscope Android SDK.

2. 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 #

1. 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.

2. Run pod install in the ios directory to install dependencies.

3. 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 #

1. Plugin not found: Ensure you've added the plugin to your pubspec.yaml and run flutter pub get
2. 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.