Skip to main content

Flutter Quickstart

This guide walks you through integrating PushEngage push notifications into a Flutter application targeting both Android and iOS. Estimated time: 15 minutes.

After completing this guide, your app will receive push notifications on both platforms. See the Flutter SDK Reference for the full API.

Prerequisites​

  • Flutter SDK 3.x or higher
  • Android Studio (for Android builds) and/or Xcode (for iOS builds)
  • Firebase account (create one free) — required for Android
  • Apple Developer account with a valid App ID — required for iOS
  • APNs certificate or key (create one) — required for iOS
  • PushEngage account and App ID (see Get Your App ID)

Step 1 — Install the SDK​

Add the dependency to pubspec.yaml:

pubspec.yaml
dependencies:
  pushengage_flutter_sdk: ^0.0.2

Then run:

flutter pub get

Step 2 — Android Setup​

Firebase Cloud Messaging (FCM)​

  1. Open the Firebase console and sign in.
  2. Click Add Project (or select an existing one).
  3. Click the Android icon to add an Android app.
  4. Enter your app's package name (found in android/app/build.gradle under applicationId).
  5. Download google-services.json and place it at android/app/google-services.json.
  6. Generate the Service Account JSON: Firebase console → Settings → Service accounts → Generate new private key.
  7. Retrieve the Sender ID: Firebase console → Settings → Cloud Messaging tab.

Connect to PushEngage Dashboard​

  1. Log in to your PushEngage Dashboard.
  2. Navigate to Site Settings → Installation → Android SDK tab.
  3. Enter your Firebase Sender ID and upload the Service Account JSON.
  4. Click Update and copy the App ID.

Step 3 — iOS Setup​

Open your iOS workspace in Xcode:

your_project_name/ios/Runner.xcworkspace

Enable Xcode Capabilities​

  1. Select the root project and choose the Runner target.
  2. Go to Signing & Capabilities → + Capability → Push Notifications.
  3. Click + Capability → Background Modes, then check Remote notifications and Background fetch.

Connect iOS to PushEngage Dashboard​

  1. PushEngage Dashboard → Site Settings → Installation → iOS SDK tab.
  2. Upload your APNs certificate or key.
  3. Copy the App ID.

Step 4 — Add Notification Service Extension (iOS)​

Create the Extension​

  1. In Xcode, go to File → New → Target → Notification Service Extension → Next.
  2. Name it PushEngageNotificationServiceExtension → Finish. Click Cancel when prompted to activate.
  3. Set the new target's Deployment Target to iOS 10 or above.

Configure Podfile​

Open ios/Podfile. Add the following at the bottom of the file:

ios/Podfile (additions)
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['APPLICATION_EXTENSION_API_ONLY'] = 'No'
    end
  end
end

target 'PushEngageNotificationServiceExtension' do
  use_frameworks!
  pod 'PushEngage', '0.0.6'
end

Run in your ios/ directory:

pod repo update
pod install

Implement the Extension​

Replace the auto-generated NotificationService.swift:

PushEngageNotificationServiceExtension/NotificationService.swift
import UserNotifications
import PushEngage

@available(iOSApplicationExtension 10.0, *)
class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?
    var request: UNNotificationRequest?

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        self.request = request
        self.contentHandler = contentHandler
        self.bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent

        if let bestContent = bestAttemptContent {
            PushEngage.didReceiveNotificationExtensionRequest(request, bestContentHandler: bestContent)
            contentHandler(bestContent)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler,
           let request = request,
           let bestAttemptContent = bestAttemptContent {
            guard let content = PushEngage.serviceExtensionTimeWillExpire(
                request, content: bestAttemptContent
            ) else {
                contentHandler(bestAttemptContent)
                return
            }
            contentHandler(content)
        }
    }
}

Step 5 — Add Notification Content Extension (iOS, Optional)​

  1. In Xcode, go to File → New → Target → Notification Content Extension → Next.
  2. Name it PushEngageNotificationContentExtension → Finish. Click Cancel when prompted.
  3. Set Deployment Target to iOS 10 or above.
  4. Add to ios/Podfile:
target 'PushEngageNotificationContentExtension' do
  use_frameworks!
  pod 'PushEngage', '0.0.6'
end

Run pod install in the ios/ directory.

Step 6 — Add App Groups (iOS)​

  1. Select the Runner target in Xcode → Signing & Capabilities → + Capability → App Groups.
  2. Add a new App Group: group.com.yourcompany.yourapp.
  3. In ios/Runner/Info.plist, add:
    • Key: PushEngage_App_Group_Key
    • Value: group.com.yourcompany.yourapp
  4. In PushEngageNotificationServiceExtension/Info.plist, add the same key and value.
  5. Select the extension target → enable the same App Group under Signing & Capabilities.

Step 7 — Initialize the SDK​

In lib/main.dart:

lib/main.dart
import 'package:flutter/material.dart';
import 'package:pushengage_flutter_sdk/pushengage_flutter_sdk.dart';

void main() {
  runApp(const MyApp());
}

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

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _initPushEngage();
  }

  Future<void> _initPushEngage() async {
    await PushEngage.setAppId('YOUR_APP_ID');
    // Trigger the system permission prompt; on grant, the SDK auto-subscribes.
    await PushEngage.requestNotificationPermission();
  }

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      title: 'My App',
      home: HomeScreen(),
    );
  }
}

For iOS distribution, initialize PushEngage in ios/Runner/AppDelegate.swift:

ios/Runner/AppDelegate.swift
import Flutter
import UIKit
import PushEngage

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {

    override init() {
        super.init()
        PushEngage.swizzleInjection(isEnabled: true)
    }

    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        if #available(iOS 10.0, *) {
            UNUserNotificationCenter.current().delegate = self
        }
        GeneratedPluginRegistrant.register(with: self)
        PushEngage.setBadgeCount(count: 0)
        PushEngage.setNotificationWillShowInForegroundHandler { notification, completion in
            if notification.contentAvailable == 1 {
                completion(nil)
            } else {
                completion(notification)
            }
        }
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
}
note

Replace YOUR_APP_ID with the App ID from Steps 2 or 3.

Step 8 — Send a Test Notification​

  1. Build and run on a physical device (Android or iOS).
  2. Accept the notification permission prompt.
  3. In the PushEngage Dashboard → Campaign → Push Broadcasts → Create New Push Broadcast → send a test.

Troubleshooting​

Android: notifications not received
Verify google-services.json is at android/app/google-services.json and that the Sender ID in the PushEngage Dashboard matches Firebase.

iOS: build sandboxing error
In Xcode → Build Settings → set User Script Sandboxing to No.

Next Steps​

Last updated on