Channels

Channel Concept#

A channel is a delivery mechanism. NotificationManager.send asks the notification which channels it wants through Notification.via(), then dispatches to each registered channel in turn.

import 'package:magic_notifications/magic_notifications.dart';

class MonitorDownNotification extends Notification {
  @override
  List<String> via(Notifiable notifiable) => ['database', 'push'];
}

Future<void> alert(Notifiable user) async {
  await Notify.send(user, MonitorDownNotification());
}

Channels are identified by a string name. For each name the manager:

1. skips it with a logged warning when no channel is registered under it,
2. skips it when isAvailable is false,
3. awaits channel.send(notifiable, notification).

Channels run one after another. A channel that throws does not stop the rest: the manager finishes the list, logs every later failure, and rethrows the first error once all channels have been tried.

Declaring a channel in via() is therefore safe without knowing at compile time whether the device supports it.

NotificationChannel Interface#

import 'package:magic_notifications/magic_notifications.dart';

abstract class NotificationChannel {
  String get name;
  bool get isAvailable;
  Future<void> send(Notifiable notifiable, Notification notification);
}

DatabaseChannel#

NotificationServiceProvider.boot() registers DatabaseChannel whether or not push is configured. It is always available, and its send does nothing:

import 'package:magic_notifications/magic_notifications.dart';

class DatabaseChannel extends NotificationChannel {
  @override
  String get name => 'database';

  @override
  bool get isAvailable => true;

  @override
  Future<void> send(Notifiable notifiable, Notification notification) async {
    // Returns without doing anything: the backend owns the rows.
  }
}

How It Works#

The database channel is asymmetric:

1. The backend creates: the Laravel backend calls $user->notify(new SomeNotification()), which persists a row in the notifications table.
2. The client reads: NotificationPoller calls NotificationManager.fetchNotifications() every 30 seconds by default (notifications.database.polling_interval), which hits GET /notifications. With a socket, Notify.startRealtime() applies each pushed row instead.
3. A stream emits: results go to the broadcast stream behind Notify.notifications().
4. The UI reacts: any widget listening to that stream receives the updated list.

DatabaseChannel.send exists for parity with Laravel's via() vocabulary. A client-created row is not supported by this channel; post to your backend's own endpoint for that.

DatabaseNotification fields:

PushChannel#

PushChannel is registered when a push driver resolves. It is self-addressed and ships switched off.

Ordinary push to other people is sent by your backend through OneSignal; see Laravel Backend Setup. This channel exists so a person can find out whether push reaches their own phone before an incident rather than during one. The backend carries the matching magic-starter.onesignal.self_test_enabled switch; enable both or neither.

How It Works#

1. With the switch off, send logs a debug line and returns.
2. A foreign recipient is refused with the exception above.
3. toPush() is called on the notification; a null return exits early.
4. When the Notifiable has a notificationPreference, isEnabled(notification.type, 'push') must be true (see Preferences).
5. The request is sent.

Creating Custom Channels#

Extend NotificationChannel for any other delivery mechanism:

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

class SlackChannel extends NotificationChannel {
  final String _webhookUrl;

  SlackChannel(this._webhookUrl);

  @override
  String get name => 'slack';

  @override
  bool get isAvailable => _webhookUrl.isNotEmpty;

  @override
  Future<void> send(Notifiable notifiable, Notification notification) async {
    final data = notification.toDatabase(notifiable);
    if (data == null) return;

    await Http.post(_webhookUrl, data: {
      'text': '${data['title']}: ${data['body']}',
    });
  }
}

Then name it in via():

import 'package:magic_notifications/magic_notifications.dart';

class DeployFinishedNotification extends Notification {
  @override
  List<String> via(Notifiable notifiable) => ['database', 'slack'];

  // `SlackChannel.send` reads this: the base `toDatabase` returns `null`.
  @override
  Map<String, dynamic>? toDatabase(Notifiable notifiable) => {
    'title': 'Deploy finished',
    'body': 'The release is live.',
  };
}

Channel Registration#

NotificationServiceProvider registers database and push itself. Register any other channel from the boot() of a provider of your own:

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

// The host's own channel from the section above, and its webhook url.
const String webhookUrl = 'https://hooks.example.com/slack';

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

  @override
  void register() {}

  @override
  Future<void> boot() async {
    NotificationManager().registerChannel(SlackChannel(webhookUrl));
  }
}

Registering a name that already exists replaces the previous instance, which is how a test swaps in a fake. hasChannel answers whether a name is registered:

import 'package:magic_notifications/magic_notifications.dart';

bool hasPushChannel() {
  final bool exists = NotificationManager().hasChannel('push');

  return exists;
}

Gotchas#

Related Documentation#

• Drivers: the push SDK layer behind PushChannel.
• Preferences: the per-type and per-channel opt-outs PushChannel honours.
• Notification Manager: dispatch, polling and realtime.
• Laravel Backend Setup: the backend that creates the rows and sends the pushes.
• Realtime channels with magic_socket: the socket layer Notify.startRealtime subscribes through.