push_notification_sdk Free

Push notification feature SDK with per-provider packages (FCM, OneSignal). Provides token lifecycle, foreground/tap streams, and topic subscriptions.

Version: 1.0.0

Variables

Variable	Type	Default	Description
includeFcm	boolean	true	Include Firebase Cloud Messaging (FCM) provider package
includeOneSignal	boolean	false	Include OneSignal provider package

At least one provider must be enabled. Enabling both is unusual but supported.

Generated Packages

Package	Condition	Description
push_notification_api	Always	Contract + models (no plugin deps)
push_notification_impl	Always	Orchestrator
push_notification_fcm_impl	includeFcm	FCM provider
push_notification_onesignal_impl	includeOneSignal	OneSignal provider

Usage

Interactive

archipelago generate push_notification_sdk

Non-interactive (CI)

archipelago generate push_notification_sdk --config my_config.json

Generated Structure

features/
└── push_notification/
    ├── push_notification_api/
    │   └── lib/src/
    │       └── models/
    ├── push_notification_impl/
    │   └── lib/src/
    │       └── di/
    ├── push_notification_fcm_impl/       # if includeFcm
    │   └── lib/src/
    │       └── di/
    └── push_notification_onesignal_impl/ # if includeOneSignal
        └── lib/src/
            └── di/

FCM Setup

1. Add google-services.json (Android) to apps/template_app/android/app/.
2. Add GoogleService-Info.plist (iOS) to apps/template_app/ios/Runner/.
3. In ios/Runner/AppDelegate.swift, ensure FirebaseApp.configure() is called.
4. Enable the Push Notifications capability in Xcode (Runner target > Signing & Capabilities).
5. Enable Background Modes > Remote notifications.
6. Android: no extra steps — FCM is configured via google-services.json.

FCM token is available via getIt<PushNotificationSDK>().getToken() after requestPermission() is granted.

OneSignal Setup

1. Create an app at onesignal.com and note the App ID.
2. Initialise OneSignal early in main.dart (before runApp):

   OneSignal.initialize('<YOUR_ONESIGNAL_APP_ID>');

3. iOS: add Push Notifications capability and Background Modes > Remote notifications in Xcode.
4. Android: no extra steps.

OneSignal subscription ID is available via getIt<PushNotificationSDK>().getToken().

Tap-Driven Navigation

Subscribe to tapStream in your app shell:

getIt<PushNotificationSDK>().tapStream.listen((notification) {
  if (notification.route != null) {
    router.push(RouteUri.parse(notification.route!));
  }
});

The route field is populated from data['route'] in the notification payload.

Android Notification Channel (API 26+)

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    val channel = NotificationChannel(
        "default", "General", NotificationManager.IMPORTANCE_DEFAULT,
    )
    getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
}

ANR Prevention

When a notification is tapped while the app is dead, Android cold-starts MainActivity directly. The generated project includes a NotificationActivity trampoline that receives the tap intent, extracts the route payload, forwards it to MainActivity via the deeplink EventChannel, then finishes itself immediately — avoiding potential ANR on slow devices.

Configure FCM to target NotificationActivity

{
  "to": "<FCM_TOKEN>",
  "data": {
    "click_action": "com.example.yourapp.NOTIFICATION_TAP",
    "route": "/destination"
  }
}

Topic Subscriptions (OneSignal)

OneSignal does not support native topics. Topics are simulated via tags:

• subscribeToTopic('premium') sets tag topic_premium = "true"
• unsubscribeFromTopic('premium') removes tag topic_premium