upscope_flutter 1.0.0

A Flutter plugin for Upscope cobrowsing that supports Android and iOS.

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

1. The Upscope Android SDK will be automatically included from the GitHub repository.

2. 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'
}

3. No additional authentication required!

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

3. Initialize Upscope in your Application class:

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

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.

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:

1. Clone this repository
2. Navigate to the project directory
3. Run flutter pub get in each package directory
4. Make your changes
5. 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:

1. ✅ Dependencies: Configured to use actual published packages
2. ✅ Imports: Native SDK imports are enabled
3. 🚧 Implementation: TODO sections need to be updated with actual SDK method calls
4. 🚧 Event Handling: Subscribe to native SDK events and forward to Flutter
5. 🚧 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

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

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