Obsly Flutter SDK - Framework-Agnostic #

🚀 Now supports MaterialApp, CupertinoApp, and custom Flutter architectures!

Overview #

Obsly offers an advanced observability platform for iOS, Android and Web applications. This Flutter SDK is framework-agnostic and works with any Flutter application architecture while providing Crashlytics-style initialization patterns.

🔥 New Framework-Agnostic Features #

• ✅ MaterialApp Support - Full backward compatibility, zero breaking changes
• ✅ CupertinoApp Support - Native iOS styling preserved, no forced MaterialApp wrapper
• ✅ Custom Architecture Support - Works with any Flutter widget hierarchy
• ✅ Advanced Navigation - Ready for go_router, auto_route, and custom navigation systems
• ✅ Crashlytics-Style Init - Familiar API patterns with enhanced flexibility
• ✅ Conflict Prevention - Safe coexistence with existing crash reporting systems

Core Capabilities #

• Automatic UI, navigation, network, console and crash capture
• Optional screenshot capture on UI and rage-click events
• Performance transactions and steps
• Custom metrics (counter, gauge, histogram timer)
• Tags, context, session and user identification

For API parity details, see the browser SDK documentation in the repository browser/README.md.

Table of Contents #

• Installation
• Framework-Agnostic Initialization
• App Wrapping (Any Architecture)
• Framework Examples
  • MaterialApp Integration
  • CupertinoApp Integration
  • Custom Architecture Integration
• Advanced Features
  • Navigation Integration
  • Error Handling & Conflict Prevention
• Configuration
• Developer Methods
  • Manage Sessions
  • Client Identification
  • Application Identification
  • Tag
  • Screenshot
  • Performance
  • Metrics
  • Application Context
  • SDK Control
  • Miscellaneous
• Debug tools
• Migration Guide
• Requirements
• Getting Help
• License

Installation #

Add the dependency:

dependencies:
  obsly_flutter: ^0.2.0

Framework-Agnostic Initialization #

🔥 Crashlytics-Style Setup (Recommended) #

The new API provides Crashlytics-style initialization patterns that work with any Flutter architecture:

import 'package:flutter/material.dart';
import 'package:obsly_flutter/obsly_sdk.dart';

void main() async {
  // 🔥 Optional: Configure async error capture (conflict-safe)
  ObslySDK.enableAsyncErrorCapture(
    global: true,
    preventConflicts: true, // Safe with Crashlytics, Sentry, etc.
  );

  // 🔥 Crashlytics-style initialization
  ObslySDK.runWithAsyncErrorCapture(() async {
    WidgetsFlutterBinding.ensureInitialized();
    
    await ObslySDK.instance.init(
      const InitParameters(
        obslyKey: 'YOUR_OBSLY_KEY',
        instanceURL: 'https://api.obsly.io',
        debugMode: true,
        logLevel: LogLevel.debug,
        config: ObslyConfig(
          enableDebugTools: true,
          enableScreenshotOnUi: true,
          rageClick: RageClickConfig(
            active: true,
            screenshot: true,
            screenshotPercent: 0.25,
          ),
        ),
      ),
    );

    runApp(MyApp()); // Works with ANY Flutter app!
  });
}

App Wrapping (Any Architecture) #

Framework-Agnostic Wrapping #

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    // Your app - MaterialApp, CupertinoApp, or Custom
    final yourApp = MaterialApp(
      title: 'My App',
      home: HomePage(),
    );

    // 🎯 Framework-agnostic wrapping - auto-detects app type
    return ObslySDK.instance.wrapApp(
      app: yourApp,
      enableDebugTools: true,
    );
  }
}

Framework Examples #

MaterialApp Integration (Backward Compatible) #

class MaterialBankingApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final materialApp = MaterialApp(
      title: 'Banking App',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
      ),
      initialRoute: '/',
      routes: {
        '/': (context) => LoginScreen(),
        '/dashboard': (context) => DashboardScreen(),
        '/transactions': (context) => TransactionsScreen(),
      },
    );

    // ✅ All MaterialApp properties preserved exactly
    return ObslySDK.instance.wrapApp(
      app: materialApp,
      enableDebugTools: true,
    );
  }
}

CupertinoApp Integration (iOS Native) #

class iOSBankingApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final cupertinoApp = CupertinoApp(
      title: 'iOS Banking',
      theme: CupertinoThemeData(
        primaryColor: CupertinoColors.systemBlue,
      ),
      home: CupertinoPageScaffold(
        navigationBar: CupertinoNavigationBar(
          middle: Text('Banking'),
        ),
        child: iOSHomeScreen(),
      ),
    );

    // ✅ Native iOS styling preserved, no MaterialApp forced
    return ObslySDK.instance.wrapApp(
      app: cupertinoApp,
      enableDebugTools: true,
    );
  }
}

Custom Architecture Integration #

class CustomArchitectureApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final customApp = Container(
      decoration: BoxDecoration(
        gradient: LinearGradient(
          colors: [Colors.purple, Colors.blue],
        ),
      ),
      child: CustomNavigationSystem(
        child: MyCustomScreens(),
      ),
    );

    // ✅ No forced MaterialApp wrapper
    return ObslySDK.instance.wrapApp(
      app: customApp,
      customNavigationProvider: CustomNavigationProvider(),
      enableDebugTools: true,
    );
  }
}

Advanced Features #

Navigation Integration #

go_router Support

final GoRouter _router = GoRouter(
  routes: [
    GoRoute(path: '/', builder: (context, state) => HomeScreen()),
    GoRoute(path: '/profile', builder: (context, state) => ProfileScreen()),
  ],
);

class GoRouterApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final app = MaterialApp.router(routerConfig: _router);

    return ObslySDK.instance.wrapApp(
      app: app,
      customNavigationProvider: GoRouterProvider(), // 🔄 Coming soon
    );
  }
}

auto_route Support

@AutoRouterConfig()
class AppRouter extends _$AppRouter {
  @override
  List<AutoRoute> get routes => [
    AutoRoute(page: HomeRoute.page, path: '/'),
    AutoRoute(page: ProfileRoute.page, path: '/profile'),
  ];
}

class AutoRouteApp extends StatelessWidget {
  final _appRouter = AppRouter();

  @override
  Widget build(BuildContext context) {
    final app = MaterialApp.router(routerConfig: _appRouter.config());

    return ObslySDK.instance.wrapApp(
      app: app,
      customNavigationProvider: AutoRouteProvider(), // 🔄 Coming soon
    );
  }
}

Error Handling & Conflict Prevention #

Coexistence with Crashlytics

void main() async {
  // Initialize Firebase Crashlytics
  await Firebase.initializeApp();
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  // Initialize Obsly with conflict prevention
  ObslySDK.enableAsyncErrorCapture(
    global: true,
    preventConflicts: true, // 🛡️ Won't interfere with Crashlytics
  );

  ObslySDK.runWithAsyncErrorCapture(() async {
    await ObslySDK.instance.init(params);
    runApp(MyApp());
  });
}

Custom Error Handling

void main() async {
  // Configure with custom error handler
  ObslySDK.enableAsyncErrorCapture(
    global: true,
    captureIsolateErrors: false,
    preventConflicts: true,
  );

  // Listen to async errors
  ObslySDK.onAsyncError.listen((error) {
    print('Custom handling: ${error.error}');
    // Your custom logic here
  });

  ObslySDK.runWithAsyncErrorCapture(() async {
    await ObslySDK.instance.init(params);
    runApp(MyApp());
  });
}

Advanced Setup (Manual Control) #

For cases requiring granular initialization control:

import 'package:flutter/widgets.dart';
import 'package:obsly_flutter/obsly_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  ObslySDK.run(() async {
    try {
      await ObslySDK.instance.init(
        InitParameters(
          obslyKey: 'YOUR_OBSLY_KEY',
          instanceURL: 'https://api.obsly.com',
          appName: 'MyFlutterApp',
          appVersion: '1.0.0',
          logLevel: LogLevel.error,
          debugMode: false,
          config: const ObslyConfig(
            enableAutomaticCapture: true,
            enableScreenshotOnUi: false,
            enableRageClickScreenshot: false,
          ),
          // sessionID: 'optional-custom-session-id',
        ),
      );
      
      runApp(const MyApp());
    } catch (e) {
      // App continues without Obsly if initialization fails
      runApp(const MyApp());
    }
  });
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return ObslySDK.instance.wrapAppLegacy(
      app: MaterialApp(
        title: 'My App',
        home: const HomePage(),
      ),
      enableDebugTools: false, // set true to show the debug overlay
    );
  }
}

Configuration #

Init parameters (parity with JS Browser SDK):

ObslyConfig structure:

Rate Limit Configuration #

You can control the rate of captured events. Configure per-event-type limits inside ObslyConfig.rateLimits.

Event types:

• base, request, tag, console, ui, metric, error, performance, navigation

Parameters:

Example:

final params = InitParameters(
  ObslyKey: 'KEY',
  instanceURL: 'https://api.url',
  config: ObslyConfig(
    rateLimits: const RateLimits(
      error: RateLimitConfig(
        interval: 2000,
        bucketSize: 15,
        trailing: true,
        emptyBucketDelay: 2000,
        rejectWhenBucketFull: false,
      ),
      ui: RateLimitConfig(
        bucketSize: 20,
        emptyBucketDelay: 2000,
      ),
    ),
  ),
);

Request Headers Config #

Control which headers are captured for requests within a status range and URL pattern.

Example:

InitParameters(
  ObslyKey: 'KEY',
  instanceURL: 'https://api.url',
  config: const ObslyConfig(
    requestHeadersWhitelist: [
      RequestHeadersConfig(
        url: 'https://api.example.com/sensitive/*',
        fromStatus: 400,
        toStatus: 599,
        headers: ['content-type', 'x-request-id'],
      ),
    ],
  ),
);

Request Body Config #

Capture request and/or response bodies on error ranges for matching URLs.

Example:

const config = ObslyConfig(
  requestBodyWhitelist: [
    RequestBodyConfig(
      url: 'https://api.example.com/*',
      fromStatus: 400,
      toStatus: 599,
      captureRequestBody: true,
      captureResponseBody: true,
    ),
  ],
);

Wildcards #

Use wildcards in URL patterns and header names:

• URL: https://example.com/*, https://*.example.com/*, *.example.com/*
• Header: *content*, content*, *type, x-*

Developer Methods #

All functions are available on ObslySDK.instance. For readability, performance and metrics are also exposed via namespaced getters Performance and Metrics.

Manage Sessions:

await ObslySDK.instance.closeCurrentSession();
await ObslySDK.instance.createNewSession('custom-session-id');

Client Identification:

await ObslySDK.instance.setUserID('user-123');
await ObslySDK.instance.setPersonID('person-456');
await ObslySDK.instance.setPassportID('passport-789');
await ObslySDK.instance.setContractID('contract-000');

Application Identification:

await ObslySDK.instance.setAppName('MyNewApp');
await ObslySDK.instance.setAppVersion('1.2.0');

Tag:

await ObslySDK.instance.addTag(
  [Tag(key: 'user_tier', value: 'premium')],
  'User Properties',
);

Screenshot:

await ObslySDK.instance.addScreenshot();
final base64Image = await ObslySDK.instance.getScreenshot();

Performance:

await ObslySDK.instance.Performance.startTransaction('DASHBOARD', 'Load Dashboard');
await ObslySDK.instance.Performance.startStep('Load Dashboard', 'DASHBOARD');
await ObslySDK.instance.Performance.finishStep('Load Dashboard', 'DASHBOARD');
await ObslySDK.instance.Performance.endTransaction('DASHBOARD');

Metrics:

ObslySDK.instance.Metrics.incCounter('CLICK_EVENT', 'FBL', 'OP', 'VIEW', 'OK');
ObslySDK.instance.Metrics.setGauge('CPU', 0.75, 'FBL', 'OP', 'VIEW', 'OK');
ObslySDK.instance.Metrics.startHistogramTimer('FETCH', 'FBL', 'OP', 'VIEW');
ObslySDK.instance.Metrics.endHistogramTimer('FETCH', 'FBL', 'OP', 'VIEW', 'OK');

Application Context:

await ObslySDK.instance.setView('HOME');
await ObslySDK.instance.setOperation('ONBOARDING');
await ObslySDK.instance.setFunctionalBlock('AUTH');

SDK Control:

await ObslySDK.instance.pauseTracker();
await ObslySDK.instance.resumeTracker();
await ObslySDK.instance.setRequestsBlacklist(['https://*.sensitive.com/*']);
await ObslySDK.instance.setLogLevel('warn'); // 'null' | 'error' | 'warn' | 'log' | 'debug'

final session = ObslySDK.instance.getSessionInfo();

Miscellaneous:

await ObslySDK.instance.addFeedback('5', 'Great experience');

Migration Guide #

Migrating to Framework-Agnostic SDK #

From v0.x.x to v1.0.0 (Zero Breaking Changes)

Your existing MaterialApp code works unchanged:

Before (Old SDK - Still Works):

void main() {
  ObslySDK.run(() {
    runApp(
      ObslySDK.wrapApp(
        app: MaterialApp(...),
        obslyKey: 'your-key',
        instanceURL: 'https://api.obsly.io',
      ),
    );
  });
}

After (New SDK - Recommended):

void main() async {
  ObslySDK.runWithAsyncErrorCapture(() async {
    WidgetsFlutterBinding.ensureInitialized();
    
    await ObslySDK.instance.init(
      const InitParameters(
        obslyKey: 'your-key',
        instanceURL: 'https://api.obsly.io',
      ),
    );

    runApp(MyApp());
  });
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ObslySDK.instance.wrapApp(
      app: MaterialApp(...), // Works exactly the same
    );
  }
}

Benefits of Migration

• ✅ CupertinoApp Support - Add iOS native support
• ✅ Custom Architecture - Use any Flutter widget hierarchy
• ✅ Better Error Handling - Crashlytics-style async error capture
• ✅ Conflict Prevention - Safe with existing crash reporting
• ✅ Navigation Flexibility - Ready for go_router, auto_route

Migration Checklist

1. Update Initialization (Optional but recommended):

   // Replace ObslySDK.run() with:
   ObslySDK.runWithAsyncErrorCapture(() async {
     await ObslySDK.instance.init(params);
     runApp(MyApp());
   });
   

2. Update App Wrapping (Optional but recommended):

   // Replace ObslySDK.wrapApp() with parameters with:
   return ObslySDK.instance.wrapApp(app: yourApp);
   

3. Enable Conflict Prevention (If using other crash tools):

   ObslySDK.enableAsyncErrorCapture(preventConflicts: true);
   

4. Test Different Architectures (Optional):

   // Try CupertinoApp
   return ObslySDK.instance.wrapApp(app: CupertinoApp(...));
      
   // Or custom architecture
   return ObslySDK.instance.wrapApp(app: CustomWidget(...));
   

Debug tools #

Enable the overlay by passing enableDebugTools: true to wrapApp. The overlay lets you inspect captured events and screenshots during development.

Requirements #

• Flutter >= 3.0.0
• Dart >= 3.0.0

Getting Help #

Questions or feedback? Email us at info@obsly.tech.

License #

MIT License - see LICENSE file for details.

Support #

• 📝 Documentation
• 🐛 Issues
• 💬 Discussions

Contributing #

Contributions are welcome! Please read our Contributing Guide for details.