📱 Send Mobile Push Notifications with Flutter (iOS)

This guide will walk you through sending push notifications to your Flutter iOS application using NotificationAPI and Apple Push Notification service (APNs).

Overview

Sending push notifications to iOS devices is exclusively handled by Apple’s Push Notification Service (APNs). Implementing this from scratch requires significant backend infrastructure to manage device tokens and communicate with APNs.

NotificationAPI simplifies this process by managing the entire backend complexity for you. Our Flutter SDK handles permission prompts and device token registration, and our service sends the notifications through APNs on your behalf.

The setup process is as follows:

1. NotificationAPI account setup
2. Set up APNs
3. Install and initialize the NotificationAPI Flutter SDK
4. Configure your iOS project
5. Verify device registration
6. Send a notification

1. NotificationAPI account setup

Start in your NotificationAPI dashboard so we can wire everything together later.

1. Sign up or log in to NotificationAPI (choose the correct data region for your needs)
2. Create a new notification named “Hello World” (or any name)
3. Select Mobile Push as the notification type
4. Open the Mobile Integration tab → Apple Push Notification (APNs)

2. Set up APNs

To send push notifications to iOS devices, you need APNs credentials from your Apple Developer account. Then connect them in the NotificationAPI dashboard.

1. Ensure you have a paid Apple Developer account
2. In Apple Developer → Certificates, Identifiers & Profiles → Keys → click “+”
3. Name the key (e.g., NotificationAPI) and enable Apple Push Notifications service (APNs)
4. Prefer enabling both Sandbox and Production; register and download the key file
5. In the notification’s Mobile Integration (NotificationAPI dashboard) → Apple Push Notification (APNs) form, fill in:
   • Key ID (from the Apple Keys page)
   • Team ID (from your Apple Developer account)
   • Topic (your app’s Bundle Identifier, e.g., com.example.flutter_ios_demo)
   • Key (paste the entire contents of the downloaded key file)
6. Save the configuration

3. Install and initialize the NotificationAPI Flutter SDK

Add the Flutter SDK to your project:

flutter pub add notificationapi_flutter_sdk

Initialize the SDK after the user is identified/logged in:

import 'package:flutter/material.dart';
import 'package:notificationapi_flutter_sdk/notificationapi_flutter_sdk.dart';

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    NotificationAPI.setup(
      clientId: 'CLIENT_ID',
      userId: 'USER_ID', // Replace with your app's durable user identifier
      // region: 'eu' | 'ca' // Only if your account is in EU/Canada
    );
  }

  // ... rest of your app
}

Parameters

Notes:

• For better UX, call setup() after login/registration rather than on first app open
• The first run will prompt for notification permissions; users should tap Allow

4. Configure your iOS project

Set up signing and capabilities in Xcode for the Runner target of your Flutter app.

• Open ios/Runner.xcworkspace in Xcode
• In Runner → Signing & Capabilities:
  • Select your Team (paid Apple Developer account)
  • Set the Bundle Identifier (this must exactly match the APNs Topic you configured)
  • Ensure “Automatically manage signing” is enabled for development
• Click “+ Capability” and add Push Notifications
• Deploy to a real iPhone; iOS Simulator does not support push notifications

5. Verify device registration

After running the app with NotificationAPI.setup(...) on a real device:

• Go to the NotificationAPI Users page
• Search for the userId you passed in the code
• Confirm Mobile Push is marked as Enabled (token synced)

6. Send a notification

With the SDK initialized, you can now trigger notifications from your backend. The userId must match the one used to initialize the SDK.

Here’s an example using cURL:

curl -X POST \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "new_comment",
    "to": {
      "id": "test_user_1234",
      "email": "test@example.com"
    },
    "parameters": {
      "comment": "This is a test comment"
    }
  }' \
  "https://api.notificationapi.com/<YOUR_CLIENT_ID>/sender"

Schematic Diagram

This diagram illustrates the entire flow, from app initialization to receiving a notification.

Frequently Asked Questions (FAQs)

Why are my notifications not arriving?

There can be several reasons:

• APNs Setup: Double-check Key ID, Team ID, Topic (Bundle Identifier), and that the APNs key contents were pasted correctly in the dashboard.
• User ID Mismatch: Ensure the userId in your Flutter app is identical to the one you’re sending to in the backend API call.
• Real Device Requirement: iOS Simulator does not support push notifications. Test on a physical iPhone.
• Bundle Identifier: Ensure the Xcode Bundle Identifier exactly matches the Topic configured in NotificationAPI.
• App State: On iOS, delivery behavior can vary if the app is in the foreground, background, or terminated. See Apple’s documentation for details.

How are expiring FCM tockens handled?

NotificationAPI handles expiring FCM tokens automatically. Should tokens stop working for any reason, you’ll see the warnings in the logs in the dashboard. You do not need to handle any errors on your end, and this doesn’t count towards your usage.