Refactor BindingUtils to enable the use of custom bindings

CHANGELOG.md

@@ -26,9 +26,11 @@
     - theme
   - Removed isolate name from Dart context. It's now reported via the threads interface. It can be enabled via `options.attachThreads`
 - Use `sentryClientName` instead of `sdk.identifier` ([#1135](https://github.com/getsentry/sentry-dart/pull/1135))
+- Refactor `BindingUtils` to `BindingWrapper` to enable the use of custom bindings ([#1184](https://github.com/getsentry/sentry-dart/pull/1184))
 - Bump Flutter min to 3.0.0 and Dart to 2.17.0 ([#1180](https://github.com/getsentry/sentry-dart/pull/1180))
 
 ## Unreleased
+
 ## 6.18.1
 
 ### Fixes

flutter/lib/src/binding_wrapper.dart

@@ -0,0 +1,37 @@
+import 'dart:developer';
+
+import 'package:flutter/widgets.dart';
+
+import '../sentry_flutter.dart';
+
+// The methods and properties are modelled after the the real binding class.
+class BindingWrapper {
+  /// The current [WidgetsBinding], if one has been created.
+  /// Provides access to the features exposed by this mixin.
+  /// The binding must be initialized before using this getter;
+  /// this is typically done by calling [runApp] or [WidgetsFlutterBinding.ensureInitialized].
+  WidgetsBinding? get instance {
+    try {
+      return _ambiguate(WidgetsBinding.instance);
+    } catch (e, s) {
+      log(
+        'WidgetsBinding.instance was not yet initialized',
+        level: SentryLevel.error.toDartLogLevel(),
+        error: e,
+        stackTrace: s,
+        name: 'Sentry',
+      );
+      return null;
+    }
+  }
+
+  /// Returns an instance of the binding that implements [WidgetsBinding].
+  /// If no binding has yet been initialized, the [WidgetsFlutterBinding] class
+  /// is used to create and initialize one.
+  /// You only need to call this method if you need the binding to be
+  /// initialized before calling [runApp].
+  WidgetsBinding ensureInitialized() =>
+      WidgetsFlutterBinding.ensureInitialized();
+}
+
+WidgetsBinding? _ambiguate(WidgetsBinding? binding) => binding;

flutter/lib/src/event_processor/flutter_enricher_event_processor.dart

@@ -5,7 +5,6 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import 'package:sentry/sentry.dart';
 
-import '../binding_utils.dart';
 import '../sentry_flutter_options.dart';
 
 typedef WidgetBindingGetter = WidgetsBinding? Function();
@@ -14,19 +13,7 @@ typedef WidgetBindingGetter = WidgetsBinding? Function();
 /// FlutterEnricher only needs to add information which aren't exposed by
 /// the Dart runtime.
 class FlutterEnricherEventProcessor extends EventProcessor {
-  FlutterEnricherEventProcessor(
-    this._options,
-    this._getWidgetsBinding,
-  );
-
-  factory FlutterEnricherEventProcessor.simple({
-    required SentryFlutterOptions options,
-  }) {
-    return FlutterEnricherEventProcessor(
-      options,
-      BindingUtils.getWidgetsBindingInstance,
-    );
-  }
+  FlutterEnricherEventProcessor(this._options);
 
   final SentryFlutterOptions _options;
 
@@ -36,8 +23,8 @@ class FlutterEnricherEventProcessor extends EventProcessor {
   // We can't use `WidgetsBinding` as a direct parameter
   // because it must be called inside the `runZoneGuarded`-Integration.
   // Thus we call it on demand after all the initialization happened.
-  final WidgetBindingGetter _getWidgetsBinding;
-  WidgetsBinding? get _widgetsBinding => _getWidgetsBinding();
+  WidgetsBinding? get _widgetsBinding => _options.bindingUtils.instance;
+
   SingletonFlutterWindow? get _window => _widgetsBinding?.window;
   Map<String, String> _packages = {};
 

flutter/lib/src/integrations/on_error_integration.dart

@@ -3,7 +3,6 @@ import 'dart:ui';
 
 import 'package:flutter/widgets.dart';
 import 'package:sentry/sentry.dart';
-import '../binding_utils.dart';
 import '../sentry_flutter_options.dart';
 
 typedef ErrorCallback = bool Function(Object exception, StackTrace stackTrace);
@@ -29,15 +28,11 @@ class OnErrorIntegration implements Integration<SentryFlutterOptions> {
   @override
   void call(Hub hub, SentryFlutterOptions options) {
     _options = options;
-    final binding = BindingUtils.getWidgetsBindingInstance();
-
-    if (binding == null) {
-      return;
-    }
+    final binding = options.bindingUtils.instance;
 
     // WidgetsBinding works with WidgetsFlutterBinding and other custom bindings
     final wrapper = dispatchWrapper ??
-        PlatformDispatcherWrapper(binding.platformDispatcher);
+        PlatformDispatcherWrapper(binding?.platformDispatcher);
 
     _defaultOnError = wrapper.onError;
 
@@ -97,15 +92,15 @@ class OnErrorIntegration implements Integration<SentryFlutterOptions> {
 class PlatformDispatcherWrapper {
   PlatformDispatcherWrapper(this._dispatcher);
 
-  final PlatformDispatcher _dispatcher;
+  final PlatformDispatcher? _dispatcher;
 
   /// Should not be accessed if [isOnErrorSupported] == false
   ErrorCallback? get onError =>
-      (_dispatcher as dynamic).onError as ErrorCallback?;
+      (_dispatcher as dynamic)?.onError as ErrorCallback?;
 
   /// Should not be accessed if [isOnErrorSupported] == false
   set onError(ErrorCallback? callback) {
-    (_dispatcher as dynamic).onError = callback;
+    (_dispatcher as dynamic)?.onError = callback;
   }
 
   bool isOnErrorSupported(SentryFlutterOptions options) {

flutter/lib/src/integrations/widgets_binding_integration.dart

@@ -1,7 +1,6 @@
 import 'dart:async';
 
 import 'package:sentry/sentry.dart';
-import '../binding_utils.dart';
 import '../sentry_flutter_options.dart';
 import '../widgets_binding_observer.dart';
 
@@ -10,10 +9,12 @@ import '../widgets_binding_observer.dart';
 ///   - [SentryWidgetsBindingObserver]
 ///   - [WidgetsBindingObserver](https://api.flutter.dev/flutter/widgets/WidgetsBindingObserver-class.html)
 class WidgetsBindingIntegration extends Integration<SentryFlutterOptions> {
-  SentryWidgetsBindingObserver? _observer;
+  late SentryWidgetsBindingObserver _observer;
+  late SentryFlutterOptions _options;
 
   @override
   FutureOr<void> call(Hub hub, SentryFlutterOptions options) {
+    _options = options;
     _observer = SentryWidgetsBindingObserver(
       hub: hub,
       options: options,
@@ -22,23 +23,16 @@ class WidgetsBindingIntegration extends Integration<SentryFlutterOptions> {
     // We don't need to call `WidgetsFlutterBinding.ensureInitialized()`
     // because `WidgetsFlutterBindingIntegration` already calls it.
     // If the instance is not created, we skip it to keep going.
-    final instance = BindingUtils.getWidgetsBindingInstance();
-    if (instance != null) {
-      instance.addObserver(_observer!);
+    final instance = _options.bindingUtils.instance;
+    if (instance == null) {
+      instance?.addObserver(_observer);
       options.sdk.addIntegration('widgetsBindingIntegration');
-    } else {
-      options.logger(
-        SentryLevel.error,
-        'widgetsBindingIntegration failed to be installed',
-      );
     }
   }
 
   @override
   FutureOr<void> close() {
-    final instance = BindingUtils.getWidgetsBindingInstance();
-    if (instance != null && _observer != null) {
-      instance.removeObserver(_observer!);
-    }
+    final instance = _options.bindingUtils.instance;
+    instance?.removeObserver(_observer);
   }
 }

flutter/lib/src/integrations/widgets_flutter_binding_integration.dart

@@ -10,15 +10,9 @@ typedef OnWidgetsBinding = WidgetsBinding Function();
 /// call into the native code.
 class WidgetsFlutterBindingIntegration
     extends Integration<SentryFlutterOptions> {
-  WidgetsFlutterBindingIntegration([OnWidgetsBinding? ensureInitialized])
-      : _ensureInitialized =
-            ensureInitialized ?? WidgetsFlutterBinding.ensureInitialized;
-
-  final OnWidgetsBinding _ensureInitialized;
-
   @override
   FutureOr<void> call(Hub hub, SentryFlutterOptions options) {
-    _ensureInitialized();
+    options.bindingUtils.ensureInitialized();
     options.sdk.addIntegration('widgetsFlutterBindingIntegration');
   }
 }

flutter/lib/src/sentry_flutter.dart

@@ -94,8 +94,7 @@ mixin SentryFlutter {
       options.transport = FileSystemTransport(channel, options);
     }
 
-    var flutterEventProcessor =
-        FlutterEnricherEventProcessor.simple(options: options);
+    var flutterEventProcessor = FlutterEnricherEventProcessor(options);
     options.addEventProcessor(flutterEventProcessor);
 
     if (options.platformChecker.platform.isAndroid) {

flutter/lib/src/sentry_flutter_options.dart

@@ -1,6 +1,7 @@
 import 'package:meta/meta.dart';
 import 'package:sentry/sentry.dart';
 
+import 'binding_wrapper.dart';
 import 'renderer/renderer.dart';
 
 /// This class adds options which are only availble in a Flutter environment.
@@ -251,4 +252,9 @@ class SentryFlutterOptions extends SentryOptions {
       useFlutterBreadcrumbTracking();
     }
   }
+
+  /// Setting this to a custom [BindingWrapper] allows you to use a custom [WidgetsBinding].
+  @experimental
+  @internal
+  BindingWrapper bindingUtils = BindingWrapper();
 }

flutter/lib/src/widgets_binding_observer.dart

@@ -4,7 +4,6 @@ import 'dart:ui';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import '../sentry_flutter.dart';
-import 'binding_utils.dart';
 
 /// This is a `WidgetsBindingObserver` which can observe some events of a
 /// Flutter application.
@@ -39,7 +38,7 @@ class SentryWidgetsBindingObserver with WidgetsBindingObserver {
           .skip(1) // Skip initial event added below in constructor
           .listen(_onScreenSizeChanged);
 
-      final window = BindingUtils.getWidgetsBindingInstance()?.window;
+      final window = _options.bindingUtils.instance?.window;
       _screenSizeStreamController.add(window);
     }
   }
@@ -87,7 +86,7 @@ class SentryWidgetsBindingObserver with WidgetsBindingObserver {
     if (!_options.enableWindowMetricBreadcrumbs) {
       return;
     }
-    final window = BindingUtils.getWidgetsBindingInstance()?.window;
+    final window = _options.bindingUtils.instance?.window;
     _screenSizeStreamController.add(window);
   }
 
@@ -110,7 +109,7 @@ class SentryWidgetsBindingObserver with WidgetsBindingObserver {
       return;
     }
     final brightness =
-        BindingUtils.getWidgetsBindingInstance()?.window.platformBrightness;
+        _options.bindingUtils.instance?.window.platformBrightness;
     final brightnessDescription =
         brightness == Brightness.dark ? 'dark' : 'light';
 
@@ -134,7 +133,8 @@ class SentryWidgetsBindingObserver with WidgetsBindingObserver {
       return;
     }
     final newTextScaleFactor =
-        BindingUtils.getWidgetsBindingInstance()?.window.textScaleFactor;
+        _options.bindingUtils.instance?.window.textScaleFactor;
+
     _hub.addBreadcrumb(Breadcrumb(
       message: 'Text scale factor changed to $newTextScaleFactor.',
       type: 'system',

flutter/test/event_processor/flutter_enricher_event_processor_test.dart

@@ -295,10 +295,7 @@ class Fixture {
       dsn: fakeDsn,
       checker: platformChecker,
     )..reportPackages = reportPackages;
-    return FlutterEnricherEventProcessor(
-      options,
-      binding,
-    );
+    return FlutterEnricherEventProcessor(options);
   }
 }