Preferences

On this page

Table of Contents#

Overview
NotificationPreference Model
ChannelPreference Model
Global Toggles vs Per-Type Preferences
API Endpoints
UI Integration Example

Overview#

NotificationPreference represents a user's opt-in/opt-out decisions across all notification channels. The model has two layers: global channel toggles (push, email, in-app), and per-notification-type overrides (typePreferences). The isEnabled method combines both layers to answer "should this notification be delivered via this channel?"

NotificationPreference Model#

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#

Property	Type	Default	Description
`pushEnabled`	`bool`	`true`	Global push notifications toggle
`emailEnabled`	`bool`	`true`	Global email notifications toggle
`inAppEnabled`	`bool`	`true`	Global in-app (database) notifications toggle
`typePreferences`	`Map<String, ChannelPreference>`	`{}`	Per-notification-type channel overrides

Deserialization#

dart

// From API response
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},
  },
});

Serialization#

dart

// For PUT /notification-preferences
final map = pref.toMap();
// {
//   'push_enabled': true,
//   'email_enabled': false,
//   'in_app_enabled': true,
//   'type_preferences': {...},
// }

copyWith#

dart

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

ChannelPreference Model#

dart

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 deserializes from the type_preferences sub-map:

dart

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

Global Toggles vs Per-Type Preferences#

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

dart

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:

Argument	Maps to property
`'push'`	`pushEnabled` / `ChannelPreference.push`
`'mail'` or `'email'`	`emailEnabled` / `ChannelPreference.email`
`'database'` or `'in_app'`	`inAppEnabled` / `ChannelPreference.inApp`

Example: global push is true, but monitor_up.push is false → isEnabled('monitor_up', 'push') returns false. PushChannel will skip delivery.

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

dart

final preference = notifiable.notificationPreference;
if (preference != null) {
  if (!preference.isEnabled(notification.type, 'push')) return;
}

API Endpoints#

The backend must implement two endpoints:

Method	Path	Description
`GET`	`/notification-preferences`	Fetch current user preferences
`PUT`	`/notification-preferences`	Update preferences

GET /notification-preferences Response#

json

{
  "data": {
    "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 }
    }
  }
}

PUT /notification-preferences Request Body#

json

{
  "push_enabled": true,
  "email_enabled": true,
  "in_app_enabled": true,
  "type_preferences": {
    "monitor_down": { "push": true, "email": true, "in_app": true }
  }
}

UI Integration Example#

A typical preferences screen fetches, renders, and persists the preference model:

dart

import 'package:magic_notifications/magic_notifications.dart';

class NotificationPreferencesPage extends StatefulWidget {
  const NotificationPreferencesPage({super.key});

  @override
  State<NotificationPreferencesPage> createState() =>
      _NotificationPreferencesPageState();
}

class _NotificationPreferencesPageState
    extends State<NotificationPreferencesPage> {
  NotificationPreference? _pref;

  @override
  void initState() {
    super.initState();
    _load();
  }

  Future<void> _load() async {
    final response = await Http.get('/notification-preferences');
    if (response.successful) {
      setState(() {
        _pref = NotificationPreference.fromMap(
          response.data['data'] as Map<String, dynamic>,
        );
      });
    }
  }

  Future<void> _save(NotificationPreference updated) async {
    await Http.put('/notification-preferences', data: updated.toMap());
    setState(() => _pref = updated);
  }

  @override
  Widget build(BuildContext context) {
    final pref = _pref;
    if (pref == null) return const CircularProgressIndicator();

    return ListView(
      children: [
        SwitchListTile(
          title: const Text('Push Notifications'),
          value: pref.pushEnabled,
          onChanged: (v) => _save(pref.copyWith(pushEnabled: v)),
        ),
        SwitchListTile(
          title: const Text('Email Notifications'),
          value: pref.emailEnabled,
          onChanged: (v) => _save(pref.copyWith(emailEnabled: v)),
        ),
        SwitchListTile(
          title: const Text('In-App Notifications'),
          value: pref.inAppEnabled,
          onChanged: (v) => _save(pref.copyWith(inAppEnabled: v)),
        ),
      ],
    );
  }
}

dart

class User extends Model with Notifiable {
  NotificationPreference? _cachedPreference;

  @override
  String get notifiableId => id.toString();

  @override
  dynamic get notificationPreference => _cachedPreference;

  void setPreference(NotificationPreference pref) {
    _cachedPreference = pref;
  }
}

Related