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

Usage #

Basic Setup #

import 'package:upscope_flutter/upscope_flutter.dart';

// Initialize Upscope
final config = UpscopeConfiguration(
  apiKey: 'your-api-key',
);

final upscopeManager = await Upscope.initialize(config);

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

// Enable/disable redaction globally
final config = UpscopeConfiguration(
  apiKey: 'your-api-key',
  redactionEnabled: true, // Default: true
);

final upscopeManager = await Upscope.initialize(config);

How Redaction Works

• Coordinate-based: Redaction tracks widget positions and sends coordinates to native platforms
• No visual overlays: Redacted content appears normal to the user but is blocked in cobrowsing
• Dynamic tracking: Widget positions are tracked in real-time as they move or scroll
• Clipping-aware: Properly handles scrollable areas, clipped content, and complex layouts
• Device pixel ratio: Automatically handles different screen densities

Redaction Best Practices

1. Mark sensitive data: Always redact passwords, credit cards, SSNs, and other PII
2. Use extension method: widget.markAsRedacted() is the most convenient approach
3. Consider user experience: Redaction is invisible to users but blocks cobrowsing agents
4. Test thoroughly: Verify redaction works correctly in your specific UI layouts
5. Global configuration: Use redactionEnabled: false in development if needed

Using Native Overlays #

For apps that need to display native overlays (like drawing tools), you can use the UpscopeOverlayView:

import 'package:upscope_flutter/upscope_flutter.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        // Your app content
        MyAppContent(),

        // Native overlay view
        Positioned.fill(
          child: UpscopeOverlayView(
            onViewCreated: () {
              print('Overlay view created');
            },
          ),
        ),
      ],
    );
  }
}

Configuration Options #

The UpscopeConfiguration class supports the following options:

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" />

<!-- For full-screen capture (optional) -->
<uses-permission android:name="android.permission.MEDIA_PROJECTION" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

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', :git => 'https://github.com/upscopeio/cobrowsing-ios.git', :tag => 'v2025.6.4'

  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(UpscopeConfiguration config) - 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)
• subscribeToIsConnecting(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

Debug Mode #

Enable logging in your configuration to see detailed debug information:

final config = UpscopeConfiguration(
  apiKey: 'your-api-key',
);

Contributing #

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

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.