Configuration

On this page

Table of Contents#

Overview
Full Config Map Reference
notifications.push
notifications.database
notifications.mail
notifications.soft_prompt
Environment Variables
Runtime Config Access

Overview#

All configuration lives in a single Dart map returned by notificationConfig, typically at lib/config/notifications.dart. The Magic Framework's ConfigRepository merges this map at boot time so that Config.get(key) resolves values at any point in the application lifecycle.

Full Config Map Reference#

dart

Map<String, dynamic> get notificationConfig => {
  'notifications': {
    'push': {
      'driver': 'onesignal',
      'app_id': const String.fromEnvironment('ONESIGNAL_APP_ID'),
      // 'safari_web_id': 'web.onesignal.auto.xxx',  // web only, optional
      'notify_button_enabled': false,
    },
    'database': {
      'enabled': true,
      'polling_interval': 30,
    },
    'mail': {
      'enabled': false,
    },
    'soft_prompt': {
      'enabled': true,
      'title': 'Stay Updated',
      'message': 'Get notified about important events.',
    },
  },
};

notifications.push#

Controls the push notification channel and its driver.

Key	Type	Default	Description
`driver`	`String`	`'onesignal'`	Push driver identifier. `'onesignal'` is the only built-in driver.
`app_id`	`String`	`''`	OneSignal App ID (UUID format). Must be non-empty for push to function.
`safari_web_id`	`String?`	`null`	Safari Web Push ID for Safari browser support. Optional — omit for non-Safari targets.
`notify_button_enabled`	`bool`	`false`	Whether to show the floating OneSignal notification bell widget on web.

notifications.database#

Controls the in-app (database) notification channel and its polling behavior.

Key	Type	Default	Description
`enabled`	`bool`	`true`	Whether the database channel is active.
`polling_interval`	`int`	`30`	Seconds between `GET /notifications` requests. Valid range: 5–600.

NotificationPoller uses the default interval of 30 seconds when no config override is applied. Change it with:

bash

dart run magic_notifications configure --polling-interval 60

notifications.mail#

Controls the mail notification channel.

Key	Type	Default	Description
`enabled`	`bool`	`false`	Whether mail notifications are active. Mail dispatch is handled server-side.

notifications.soft_prompt#

Controls the pre-permission soft prompt dialog rendered by PushPromptDialog.

Key	Type	Default	Description
`enabled`	`bool`	`true`	Whether to show the soft prompt before the OS permission dialog.
`title`	`String`	`'Stay Updated'`	Dialog title text.
`message`	`String`	`'Get notified about important events.'`	Dialog body text.

When enabled is true, show PushPromptDialog before calling Notify.requestPushPermission(). The dialog gives the user context before the non-dismissable OS prompt appears.

Environment Variables#

Variable	Used In	Description
`ONESIGNAL_APP_ID`	`notifications.push.app_id`	OneSignal App ID injected at compile time via `String.fromEnvironment`.

Set in .env (or your CI secrets):

text

ONESIGNAL_APP_ID=12345678-1234-1234-1234-123456789012

Build with the variable injected:

bash

flutter build apk --dart-define-from-file=.env
flutter build web --dart-define-from-file=.env

Runtime Config Access#

After the Magic Framework boots, any config value is accessible via Config.get:

dart

// Read the push App ID
final appId = Config.get<String>('notifications.push.app_id');

// Read the polling interval (returns int)
final interval = Config.get<int>('notifications.database.polling_interval');

// Read soft prompt enabled flag
final softPromptEnabled = Config.get<bool>('notifications.soft_prompt.enabled');

Config.get returns null when the key is absent; use the typed overload with a default:

dart

final enabled = Config.get<bool>('notifications.database.enabled') ?? true;

Related