Installation

Table of Contents#

• Overview
• pub.dev Dependency Setup
• CLI Installation Wizard
• Service Provider Registration
• Config Factory in main.dart
• Platform Setup Summary
• Next Steps

Overview#

Magic Notifications is a multi-channel notification plugin for Flutter apps built on the Magic Framework. It ships with a built-in CLI that automates the entire setup process — dependency declaration, config file creation, platform-specific files, and provider injection.

pub.dev Dependency Setup#

Add the package to your pubspec.yaml:

dependencies:
  magic_notifications: ^0.2.0

Then fetch dependencies:

flutter pub get

For local development within a monorepo (e.g., plugins/magic_notifications):

dependencies:
  magic_notifications:
    path: ./plugins/magic_notifications

CLI Installation Wizard#

Run the interactive wizard from your Flutter project root:

dart run magic_notifications install

The wizard guides you through four steps:

1. OneSignal App ID — prompts for your UUID-format App ID (get it from the OneSignal Dashboard)
2. Platform selection — detects existing platform directories; confirm each one
3. Web configuration (web only) — optional Safari Web ID, optional notify button
4. Soft prompt — whether to show a custom dialog before the OS permission prompt

Non-Interactive Mode (CI/CD)#

dart run magic_notifications install \
  --non-interactive \
  --app-id 12345678-1234-1234-1234-123456789012 \
  --platforms android,ios,web

# With web extras
dart run magic_notifications install \
  --non-interactive \
  --app-id YOUR_APP_ID \
  --platforms web \
  --safari-web-id web.onesignal.auto.xxx \
  --notify-button

# Disable soft prompt and overwrite any existing config
dart run magic_notifications install \
  --non-interactive \
  --app-id YOUR_APP_ID \
  --no-soft-prompt \
  --force

What the CLI Produces#

Service Provider Registration#

If you ran the CLI, lib/config/app.dart is already updated. For manual setup, add the import and provider entry:

import 'package:magic_notifications/magic_notifications.dart';

final providers = [
  // ... other providers
  (app) => NotificationServiceProvider(app),
];

The NotificationServiceProvider runs two phases during framework boot:

• register() — binds NotificationManager as a singleton under the 'notifications' key
• boot() — reads config, initializes the OneSignal push driver, starts no polling on its own

See Service Provider Architecture for the full boot sequence.

Config Factory in main.dart#

The notification config must be passed to Magic.init as a config factory:

import 'config/notifications.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Magic.init(
    configFactories: [
      () => appConfig,
      () => notificationConfig,  // add this
    ],
  );

  runApp(MyApp());
}

The notificationConfig getter is defined in lib/config/notifications.dart (created by the CLI or publish command). Its shape:

Map<String, dynamic> get notificationConfig => {
  'notifications': {
    'push': {
      'driver': 'onesignal',
      'app_id': const String.fromEnvironment('ONESIGNAL_APP_ID'),
      '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.',
    },
  },
};

Add the App ID to your .env:

ONESIGNAL_APP_ID=your-onesignal-app-id-here

Platform Setup Summary#

iOS#

The CLI writes the three project-file markers a push needs directly, without opening Xcode: UIBackgroundModes gains remote-notification in ios/Runner/Info.plist, aps-environment is declared in ios/Runner/Runner.entitlements (created if the project never had one), and CODE_SIGN_ENTITLEMENTS in ios/Runner.xcodeproj/project.pbxproj is pointed at that entitlements file (without which Xcode never reads it, and signing silently ignores the entitlement).

What is still manual, because it needs an Apple/OneSignal account rather than a project-file edit:

1. Run cd ios && pod install --repo-update && cd ..
2. Create an APNs key in Apple Developer Portal (.p8 file + Key ID + Team ID)
3. Upload the .p8 key to OneSignal Dashboard → Settings → Platforms → Apple iOS (APNs)

Android#

android/app/build.gradle — set minimum SDK:

android {
    defaultConfig {
        minSdkVersion 21
    }
}

android/app/src/main/AndroidManifest.xml — add permissions (the CLI injects POST_NOTIFICATIONS automatically):

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

Web#

The CLI creates the service worker and injects the SDK script. Manually:

web/OneSignalSDKWorker.js:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

web/manifest.json — add GCM sender ID:

{
  "gcm_sender_id": "482941778795",
  "gcm_sender_id_comment": "Do not change. Required for OneSignal Web Push."
}

For the full platform guides, see README.md.

Next Steps#

1. Run dart run magic_notifications doctor to confirm setup health
2. Read Configuration for all config key details
3. Add polling and push login to your auth flow — see README.md
4. Explore Channels and Drivers

Related

• Configuration
• Channels
• CLI Reference