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.

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: ^1.0.13

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

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
metadata	Map<String, dynamic>	{}	Additional metadata

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.