Upscope Flutter Plugin #

A Flutter federated 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.

Plugin Architecture #

The plugin is structured as a federated plugin with the following packages:

upscope_platform_interface: Defines the platform interface using MethodChannel
upscope_android: Implements the platform interface using the native Android SDK
upscope_ios: Implements the platform interface using the native iOS SDK
upscope_flutter: The main plugin package that provides a unified Dart API

Features #

✅ Initialize Upscope with configuration
✅ Connect/disconnect from Upscope servers
✅ Session management (start, stop, decline)
✅ Real-time event streaming
✅ Custom messaging
✅ Screen sharing with app-only or full-screen capture
✅ Automatic platform registration
✅ PlatformView support for native overlays
✅ Comprehensive example app

Installation #

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

dependencies:
  upscope_flutter:
    path: packages/upscope_flutter

Usage #

Basic Setup #

import 'package:upscope_flutter/upscope_flutter.dart';

// Initialize Upscope
final config = UpscopeConfiguration(
  apiKey: 'your-api-key',
  region: 'eu-west-1',
  enableLogging: true,
  redactionEnabled: true,
);

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');
});

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:

Parameter	Type	Default	Description
`apiKey`	`String`	required	Your Upscope API key
`region`	`String`	`'eu-west-1'`	Server region
`enableLogging`	`bool`	`false`	Enable SDK logging
`showDebugLogs`	`bool`	`false`	Show detailed debug logs (Android only)
`redactionEnabled`	`bool`	`true`	Enable UI element redaction
`requireSessionAuthorization`	`bool`	`false`	Require user approval for sessions
`captureEntireScreen`	`bool`	`false`	Capture full screen vs app-only
`enableTelemetry`	`bool`	`true`	Enable telemetry (iOS only)
`metadata`	`Map<String, dynamic>`	`{}`	Additional metadata

Platform-Specific Setup #

Android #

The Upscope Android SDK will be automatically included from the GitHub repository.
The plugin automatically includes this repository and dependency:

repositories {
    maven { url 'https://github.com/upscopeio/cobrowsing-android/raw/master/' }
}

dependencies {
    // Automatically included via upscope_android plugin
    implementation 'io.upscope:upscope-android-sdk:2025.6.24'
}

No additional authentication required!
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" />

Initialize Upscope in your Application class:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // Upscope will be initialized from Flutter
    }
}

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', :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.

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

Example App #

A comprehensive example app is included in the example directory, matching the structure of the iOS sample app. It demonstrates:

Main Tab: #

SDK initialization with configuration (uses same API keys as iOS sample)
Connection management with color-coded buttons
Real-time session status monitoring
Event subscription and state updates
Custom messaging functionality
Watch link generation

Redaction Demo Tab: #

Regular vs redacted text input examples
Interactive list with redacted items simulation
Visual indicators for redacted content
Add/remove list functionality

API Keys Used (matching iOS sample):

Debug/Simulator: lazycat
Release/Device: cEoQfasmRo

To run the example:

cd example
flutter run

Development #

Building the Plugin #

To work on the plugin locally:

Clone this repository
Navigate to the project directory
Run flutter pub get in each package directory
Make your changes
Test using the example app

Package Structure #

upscope-flutter/
├── packages/
│   ├── upscope_platform_interface/   # Platform interface
│   ├── upscope_android/              # Android implementation
│   ├── upscope_ios/                  # iOS implementation
│   └── upscope_flutter/              # Main package
├── example/                          # Example app
└── README.md

Native SDK Integration Status #

The plugin is configured to use the official Upscope packages:

Android: GitHub Repository - io.upscope:upscope-android-sdk:2025.6.24
iOS: GitHub Repository - UpscopeIO v2025.6.4

Current integration status:

✅ Dependencies: Configured to use actual published packages
✅ Imports: Native SDK imports are enabled
🚧 Implementation: TODO sections need to be updated with actual SDK method calls
🚧 Event Handling: Subscribe to native SDK events and forward to Flutter
🚧 Overlay Views: Implement native drawing overlays using SDK APIs

To complete the integration, update the TODO sections in the native plugins to call the actual UpscopeManager methods.

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 #

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
Native SDK not linked: Make sure the native SDKs are properly integrated in your platform-specific code

Debug Mode #

Enable logging in your configuration to see detailed debug information:

final config = UpscopeConfiguration(
  apiKey: 'your-api-key',
  enableLogging: true,
  showDebugLogs: true, // Android only
);

Contributing #

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License #

This plugin is provided as an example implementation. 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.

upscope_flutter 1.0.1 upscope_flutter: ^1.0.1 copied to clipboard

Metadata