Flutter SDK

Prerequisites#

• Dart 3.9 or newer (the package requires sdk: ^3.9.0)
• A Firebase project with Cloud Messaging enabled
• A notifySphere app with an App ID and API Token, and your Firebase service account uploaded. See Push setup.
• For iOS: your APNs authentication key (.p8) uploaded in Firebase → Project settings → Cloud Messaging

Install#

Add the SDK and the Firebase packages to pubspec.yaml, then run flutter pub get.

dependencies:
  flutter:
    sdk: flutter
  flutter_notify_sphere: ^1.0.0
  firebase_core: ^4.3.0
  firebase_messaging: ^16.1.0

Android setup#

1. Add google-services.json

   Download google-services.json from the Firebase console into android/app/, and apply the com.google.gms.google-services Gradle plugin.

2. Update AndroidManifest.xml

   Add the permissions and the default icon and channel entries:

   android/app/src/main/AndroidManifest.xmlCopy

   <manifest xmlns:android="http://schemas.android.com/apk/res/android">
       <uses-permission android:name="android.permission.INTERNET"/>
       <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
       <uses-permission android:name="android.permission.VIBRATE"/>
   
       <!-- Only if you pass useLocationData: true to registerUser() -->
       <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
       <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
   
       <application ...>
           <meta-data
               android:name="com.google.firebase.messaging.default_notification_icon"
               android:resource="@mipmap/ic_launcher" />
           <meta-data
               android:name="com.google.firebase.messaging.default_notification_channel_id"
               android:value="notify_sphere_channel" />
       </application>
   </manifest>

3. Optional: custom sound

   Put the audio file in android/app/src/main/res/raw/ (for example custom_sound.mp3) and enter custom_sound, without the extension, in the campaign's sound field.

Images in the payload (imageUrl) are downloaded and shown as expandable BigPictureStyle notifications automatically.

iOS setup#

1. Add GoogleService-Info.plist

   Open ios/Runner.xcworkspace in Xcode and add GoogleService-Info.plist to the Runner folder with "Copy items if needed" checked.

2. Enable capabilities on Runner

   Under Signing & Capabilities, add Push Notifications, Background Modes (Remote notifications, Background fetch), and App Groups with a group named group.<your.bundle.id>.

3. Add a Notification Service Extension

   Choose File → New → Target → Notification Service Extension (Swift), for example named ImageNotification. Give it the same App Group as Runner.

4. Confirm delivery from the extension

   Add NotifySphereExtension.swift to the extension and call it from NotificationService.swift. Copy both files from the package README. The service also attaches images and applies custom sounds.

   NotificationService.swiftCopy

   // In NotificationService.swift, inside didReceive(_:withContentHandler:)
   NotifySphereExtension.didReceive(request) {
       NSLog("NotifySphere delivery confirmed")
   }

Usage#

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter/material.dart';
import 'package:flutter_notify_sphere/flutter_notify_sphere.dart';

// Must be a top-level function
@pragma('vm:entry-point')
Future<void> backgroundMessageHandler(RemoteMessage message) async {
  debugPrint('Background message: ${message.data}');
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  await FlutterNotifySphere().initialize(
    showForegroundNotification: true,
    onForegroundMessage: (RemoteMessage message) {
      debugPrint('Foreground notification: ${message.data}');
    },
    onNotificationClick: (RemoteMessage? message) {
      // Route to the screen this notification is about
    },
    backgroundMessageHandler: backgroundMessageHandler,
  );

  runApp(const MyApp());
}

await FlutterNotifySphere().registerUser(
  appId: 'YOUR_NOTIFYSPHERE_APP_ID',
  apiKey: 'YOUR_NOTIFYSPHERE_API_TOKEN',
  userData: {
    'applicationUserId': 12345, // your internal user ID
    'name': 'Jane Doe',
    'email': 'jane@example.com',
  },
  useLocationData: false,
  onFcmToken: (String? token) => debugPrint('FCM token: $token'),
  onRegistrationComplete: (String? subscriptionId) {
    debugPrint('Registered: $subscriptionId');
  },
  onError: (Object error) => debugPrint('Registration error: $error'),
);

API reference#

Verify the integration#

1. Run the app on a device and check the logs for the subscription ID from onRegistrationComplete.
2. Send a test notification from the dashboard. The campaign's Delivered count should increase.
3. Tap the notification. The Clicked count should increase.
4. On iOS, test with the app closed to confirm the Notification Service Extension reports delivery.