Preferences

Overview#

Two things share the word "preferences" in this package, and they take different shapes:

NotificationPreference represents opt-in and opt-out decisions across channels: global toggles (push, email, in-app) and per-type overrides (typePreferences). Its isEnabled method combines both layers to answer "should this notification be delivered through this channel?". The package fetches nothing into this model.

NotificationPreference Model#

import 'package:magic_notifications/magic_notifications.dart';

class NotificationPreference {
  final bool pushEnabled;
  final bool emailEnabled;
  final bool inAppEnabled;
  final Map<String, ChannelPreference> typePreferences;

  const NotificationPreference({
    this.pushEnabled = true,
    this.emailEnabled = true,
    this.inAppEnabled = true,
    this.typePreferences = const {},
  });
}

Properties#

Deserialisation#

import 'package:magic_notifications/magic_notifications.dart';

NotificationPreference deserialise() {
  final pref = NotificationPreference.fromMap({
    'push_enabled': true,
    'email_enabled': false,
    'in_app_enabled': true,
    'type_preferences': {
      'monitor_down': {'push': true, 'email': true, 'in_app': true},
      'monitor_up': {'push': false, 'email': false, 'in_app': true},
    },
  });

  return pref;
}

A missing toggle reads as true.

Serialisation#

import 'package:magic_notifications/magic_notifications.dart';

Map<String, dynamic> serialise(NotificationPreference pref) {
  final map = pref.toMap();
  // {
  //   'push_enabled': true,
  //   'email_enabled': false,
  //   'in_app_enabled': true,
  //   'type_preferences': {...},
  // }

  return map;
}

copyWith#

import 'package:magic_notifications/magic_notifications.dart';

NotificationPreference enableEmail(NotificationPreference pref) {
  final updated = pref.copyWith(emailEnabled: true);

  return updated;
}

ChannelPreference Model#

class ChannelPreference {
  final bool push;
  final bool email;
  final bool inApp;

  const ChannelPreference({
    this.push = true,
    this.email = true,
    this.inApp = true,
  });
}

ChannelPreference holds the per-type override for each channel. It deserialises from one entry of the type_preferences map:

import 'package:magic_notifications/magic_notifications.dart';

ChannelPreference monitorDownPreference() {
  final monitorDown = ChannelPreference.fromMap({
    'push': true,
    'email': true,
    'in_app': false,
  });

  return monitorDown;
}

Global Toggles vs Per-Type Preferences#

isEnabled(notificationType, channel) applies a two-stage gate:

import 'package:magic_notifications/magic_notifications.dart';

abstract class PreferenceGate {
  Map<String, ChannelPreference> get typePreferences;

  bool _isGlobalChannelEnabled(String channel);

  bool _isTypeChannelEnabled(ChannelPreference preference, String channel);

  bool isEnabled(String notificationType, String channel) {
    // Stage 1: global toggle
    final globalEnabled = _isGlobalChannelEnabled(channel);
    if (!globalEnabled) return false;

    // Stage 2: type-specific override
    final typePref = typePreferences[notificationType];
    if (typePref == null) return true; // default: enabled

    return _isTypeChannelEnabled(typePref, channel);
  }
}

Channel alias resolution:

Example: global push is true but monitor_up.push is false, so isEnabled('monitor_up', 'push') returns false and PushChannel skips delivery.

PushChannel.send runs this check when the Notifiable has a non-null notificationPreference:

import 'package:magic_notifications/magic_notifications.dart';

Future<void> send(Notifiable notifiable, Notification notification) async {
  final preference = notifiable.notificationPreference;
  if (preference != null) {
    if (!preference.isEnabled(notification.type, 'push')) return;
  }
}

API Endpoints#

The preferences screen needs two endpoints from the backend:

magic-starter-laravel implements both. It differs from the contract only on the inbox: its unread-count shape and its per_page query key do not match what the client reads and sends, and a backend written to the contract is not affected. See Laravel Backend Setup.

GET /notification-preferences Response#

A type by channel matrix. Each cell carries enabled and locked; a locked cell is one the backend refuses to change (a security mail, an account alert), and the screen renders its switch disabled rather than letting a tap earn a 422. The channel names are whatever your backend offers; the screen has labels for mail, database, push and sms, and capitalises any other.

{
  "data": {
    "monitor_down": {
      "label": "Monitor down",
      "channels": {
        "mail": { "enabled": true, "locked": false },
        "database": { "enabled": true, "locked": true },
        "push": { "enabled": false, "locked": false }
      }
    }
  },
  "meta": { "push_provisioned": true }
}

meta.push_provisioned is the backend saying whether it has a push app_id at all. When it is false the push row still renders, with a hint under it, because the preference is a real choice even while nothing can deliver it yet. A response without the flag leaves the hint off.

PUT /notification-preferences Request Body#

One cell, which is what a switch in the matrix sends:

{ "type": "monitor_down", "channel": "push", "is_enabled": false }

Or a batch, which is what the bulk row above the matrix sends:

{
  "preferences": [
    { "type": "monitor_down", "channel": "push", "is_enabled": false },
    { "type": "monitor_up", "channel": "push", "is_enabled": false }
  ]
}

UI Integration#

The package ships NotificationPreferencesView and registers it under notifications.preferences. Mount it through the view registry, and replace or wrap it by registering your own builder under the same key:

import 'package:flutter/widgets.dart' hide Notification;
import 'package:magic_notifications/magic_notifications.dart';

// Once, at boot: wrap the default with a back route.
void registerPreferencesView() {
  Notify.view.register('notifications.preferences', () {
    return const NotificationPreferencesView(backRoute: '/settings');
  });
}

// In the page that hosts it:
class NotificationPreferencesPage extends StatelessWidget {
  const NotificationPreferencesPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Notify.view.make('notifications.preferences');
  }
}

contentClassName takes '' when the screen sits inside a page container that already carries the app's padding. Translation Keys lists every key the screen needs.

Push Prompt Component#

PushPrompt, PushPromptHost and PushOffNotice (lib/src/ui/components/push_prompt/) are the package's own push-permission soft prompt: a row asking for push before the platform's one-shot prompt is spent, built on NotificationManager.pushPromptAdvice().

• PushPrompt is presentational: given reachability, action, declined and busy, it renders the presentation for the device's state and reports onEnable and onDecline. It touches no platform API itself.

• PushPromptHost wires it to the live device. It owns nothing about when to ask (pushPromptAdvice does), but it owns the one thing the package refuses to decide: the key the decline is recorded under on this device. That is why it takes a declinedVaultKey constructor parameter rather than a fixed key:

  import 'package:flutter/widgets.dart';
  import 'package:magic_notifications/magic_notifications.dart';
  
  Widget pushPrompt() {
    return const PushPromptHost(declinedVaultKey: 'my_app.push_prompt_declined');
  }
  

  It writes the decline as an ISO-8601 UTC instant and reads only that shape; a value some other shape wrote reads as "never declined", so an app carrying an older value migrates it once before constructing this widget.

• PushOffNotice is a quiet shell marker (a sidebar row, or a compact glyph with compact: true for a mobile top bar) that tells a person, on a screen they were already looking at, that this device cannot be reached by push. Tapping it calls the required onOpenPreferences callback, which a host wires to wherever PushPromptHost and its controls live:

  import 'package:flutter/widgets.dart';
  import 'package:magic/magic.dart';
  import 'package:magic_notifications/magic_notifications.dart';
  
  Widget offNotice() {
    return PushOffNotice(
      onOpenPreferences: () => MagicRoute.to('/settings/notifications'),
    );
  }
  

PushPrompt and PushOffNotice resolve every string through trans('notifications.push_prompt.*'); Translation Keys lists each one with its English reference copy.

The components expose no per-instance className override. A host that wants a different look copies the component's recipe file into its own source and registers its own builder.

Translation Keys#

The package ships no translation catalogue. Every string the inbox screen, the preferences screen, NotificationDropdown, PushPrompt and PushOffNotice show goes through Magic's trans(), so a host adds each key below to every locale it ships; a missing key renders as the key itself. The English column is reference copy for your own en file, not text the package carries. A :name in the copy is a placeholder the widget fills.

The keys cover the package's own labels only. The dropdown and the inbox draw each notification's title and body exactly as the backend sent them, without trans(), so localising that content is the backend's or the host's job.

The same widgets also read these keys outside the notifications.* namespace. An app whose other screens already define them shares them; any other app adds them too.

Gotchas#

Related Documentation#

• Channels: PushChannel and where isEnabled is consulted.
• Notification Manager: pushPromptAdvice and the optimistic read-state changes behind the inbox screen.
• Configuration: reprompt_after_hours, soft_prompt.enabled and the automatic request.
• Laravel Backend Setup: the backend contract for the preferences endpoints.