Drivers

Driver Concept#

A push driver wraps a platform push SDK behind one API, so the manager and PushChannel never touch SDK internals. The manager resolves the driver lazily from a name-keyed registry (see Push Driver Setup); notifications.push.driver selects the name, and 'onesignal' is the only driver the package ships.

import 'package:magic_notifications/magic_notifications.dart';

final PushDriver? driver = Notify.manager.pushDriverOrNull; // null when push is not configured

PushDriver Abstract Class#

Key Members#

PushNotificationEvent#

class PushNotificationEvent {
  final Map<String, dynamic> data;
  const PushNotificationEvent(this.data);
}

data is the notification's additionalData payload (mobile) or the same field from the JS event (web).

PushIdentityChange#

class PushIdentityChange {
  final String? externalId;
  final String? subscriptionId;
  final bool? optedIn;
  const PushIdentityChange({this.externalId, this.subscriptionId, this.optedIn});
}

Every field is nullable because one SDK event reports only part of the state: a user change carries the external id, a subscription change carries the subscription id and the opt-in flag. A null field means "this event did not report it", never "it is empty".

Reachability#

PushDriver.reachability() derives a four-state answer, so every driver answers the same way:

import 'package:magic_notifications/magic_notifications.dart';

Future<PushReachability> currentReachability() async {
  final reachability = await Notify.manager.pushDriver.reachability();

  return reachability;
}

This is the read a soft prompt gates on before showing itself, and the read that answers "can I send this device a push" without raising the OS dialog.

OneSignalDriver (iOS and Android)#

OneSignalDriver wraps the onesignal_flutter package.

Listening to Events#

Prefer the manager's streams over the driver's own. They are filtered to the signed-in identity, and onPushClicked holds taps that arrive before anything listens, which is the cold-start case, and replays them when a listener attaches.

import 'package:magic/magic.dart';
import 'package:magic_notifications/magic_notifications.dart';

void listenToPush() {
  Notify.manager.onPushReceived.listen((event) {
    final title = event.data['title'];
    // show an in-app banner
  });

  Notify.manager.onPushClicked.listen((event) {
    // `event.data` is the notification's `additionalData`, so a destination is
    // only here when the backend put it there. Four keys, first match wins,
    // because that is what `magic_deeplink`'s own handler looks for.
    final url = event.data['url'] ??
        event.data['deep_link'] ??
        event.data['link'] ??
        event.data['uri'];

    // Guarded: a notification with nowhere to go is a valid notification.
    if (url is String && url.isNotEmpty) MagicRoute.to(url);
  });
}

A push received in the foreground also triggers a fetchNotifications(), so the in-app list catches up.

Opening a screen from a tap#

The snippet above is the whole of what this package does about a tap: it hands you the payload and stops. Nothing here routes anywhere, and a tapped push that opens the app on its own initial route rather than on the notification's screen is this package working as built.

The ecosystem's answer is magic_deeplink, and the wiring between the two is already done in both directions:

• DeeplinkServiceProvider attaches OneSignalDeeplinkHandler to this package's click stream whenever notifications is bound, so no consumer code joins them.
• That handler reads the first of url, deep_link, link or uri it finds in the payload, which is the same key list the magic-starter-laravel OneSignal channel writes.

What is not done for you is the last link: an app has to register a handler of its own, because magic_deeplink publishes no handler stubs at install time. Without one, DeeplinkManager.handleUri walks an empty list, returns false, and nothing is logged. A pipeline that is correct at every step and does nothing at the end looks exactly like a notification that was never tapped.

import 'package:magic/magic.dart';
import 'package:magic_deeplink/magic_deeplink.dart';

class AppServiceProvider extends ServiceProvider {
  AppServiceProvider(super.app);

  @override
  void register() {}

  @override
  Future<void> boot() async {
    app.make<DeeplinkManager>('deeplinks').registerHandler(
      RouteDeeplinkHandler(paths: const ['/notifications', '/orders/:id']),
    );
  }
}

RouteDeeplinkHandler navigates to the path the link names through MagicRoute.to, so the paths you list are your own in-app routes. Handlers form a first-match chain in registration order; write your own DeeplinkHandler when a tap has to do something other than navigate.

See magic_deeplink handlers and its installation guide for the handler chain and the platform association files (apple-app-site-association, assetlinks.json) a Universal or App Link needs before any of this is reached.

OneSignalWebDriver (Web)#

OneSignalWebDriver talks to the OneSignal Web SDK v16 through JavaScript interop (OneSignalJsInterop).

OneSignalWebDriver is not exported from the package barrel, so reach the web driver through the PushDriver contract (Notify.manager.pushDriver); oneSignalId is a member of the concrete class only.

The page must load the SDK script, and must not call OneSignal.init() itself: the driver initialises from config. The installer adds the right <script> tag; see Installation.

Conditional Imports via onesignal_factory.dart#

The provider never imports OneSignalDriver or OneSignalWebDriver directly. It calls createOneSignalDriver() from onesignal_factory.dart, which selects an implementation with Dart's conditional imports:

import 'onesignal_stub.dart'
    if (dart.library.js_interop) 'onesignal_web.dart'
    if (dart.library.io) 'onesignal_io.dart';

• Web (dart.library.js_interop): onesignal_web.dart returns OneSignalWebDriver(). The guard is js_interop rather than the legacy HTML library because the latter is absent from a wasm compile.
• Any dart:io build (dart.library.io): onesignal_io.dart returns OneSignalDriver(). Desktop builds take this arm too; there OneSignalDriver.isSupported is false, so PushChannel.isAvailable is false and initialize throws PLATFORM_NOT_SUPPORTED.
• Neither guard matches: the stub throws UnsupportedPlatformException. No Flutter build target reaches it; it is the default the conditional import falls back to.

Each build therefore compiles only the driver arm it selects.

Creating a Custom Driver#

To add FCM or another push service, extend PushDriver:

import 'dart:async';
import 'dart:io';

import 'package:flutter/foundation.dart';
import 'package:magic_notifications/magic_notifications.dart';

class FcmDriver extends PushDriver {
  final StreamController<PushNotificationEvent> _receivedController =
      StreamController<PushNotificationEvent>.broadcast();
  final StreamController<PushNotificationEvent> _clickedController =
      StreamController<PushNotificationEvent>.broadcast();
  final StreamController<PushPermissionState> _permissionController =
      StreamController<PushPermissionState>.broadcast();
  final StreamController<PushIdentityChange> _identityController =
      StreamController<PushIdentityChange>.broadcast();

  @override
  String get name => 'fcm';

  @override
  bool get isSupported => !kIsWeb && (Platform.isIOS || Platform.isAndroid);

  @override
  Future<PushPermissionState> permissionState() async =>
      PushPermissionState.notDetermined;

  @override
  bool get isOptedIn => false;

  @override
  Future<void> initialize(Map<String, dynamic> config) async {
    // FirebaseMessaging.instance.getToken(); and so on.
  }

  @override
  Future<void> login(String externalId) async {/* store the token */}

  @override
  Future<void> logout() async {/* remove the token */}

  @override
  Future<String?> currentExternalId() async => null;

  @override
  Future<String?> currentSubscriptionId() async => null;

  @override
  Future<bool> requestPermission() async => false;

  @override
  Future<void> optIn() async {}

  @override
  Future<void> optOut() async {}

  @override
  Future<void> setTags(Map<String, String> tags) async {}

  @override
  Future<void> removeTag(String key) async {}

  @override
  Stream<PushNotificationEvent> get onNotificationReceived =>
      _receivedController.stream;

  @override
  Stream<PushNotificationEvent> get onNotificationClicked =>
      _clickedController.stream;

  @override
  Stream<PushPermissionState> get onPermissionChanged =>
      _permissionController.stream;

  @override
  Stream<PushIdentityChange> get onIdentityChanged =>
      _identityController.stream;

  // reachability() is inherited from the base class.
}

Register it in code before NotificationServiceProvider boots (a provider's register() always runs before any boot()), and select it by name in the config:

import 'package:magic/magic.dart';
import 'package:magic_notifications/magic_notifications.dart';

class FcmServiceProvider extends ServiceProvider {
  FcmServiceProvider(super.app);

  @override
  void register() {
    Notify.extend('fcm', () => FcmDriver());
  }
}

// In `notificationConfig`, under the `notifications` key.
Map<String, dynamic> get notificationConfig => {
  'notifications': {
    'push': {
      'driver': 'fcm',
    },
  },
};

The provider then resolves your driver by that name, registers PushChannel on it and reconciles the push identity through it. A value of driver that nothing was registered under is logged at error level and push stays off. When notifications.push.app_id is non-empty the provider also calls initialize with the OneSignal-shaped config map; leave app_id unset and call initialize yourself when your driver takes other settings.

Gotchas#

Related Documentation#

• Channels: PushChannel and how a driver backs it.
• Notification Manager: driver resolution and identity reconcile.
• Service Provider: where the driver is initialised.
• Configuration: the notifications.push keys the drivers read.
• Handlers in magic_deeplink: routing a tapped push.