> This page is part of the [Customer.io documentation](https://docs.customer.io). For the complete index, see [llms.txt](https://docs.customer.io/llms.txt).
> Last updated: September 1, 2026
> To take actions in Customer.io from an agent, use the [Customer.io CLI](https://docs.customer.io/ai/cli/get-started.md) or the [MCP server](https://docs.customer.io/ai/mcp/get-started.md).
# Set up push notifications
Our Flutter SDK supports push notifications over FCM—including rich push messages with links and images. This page helps you add push support to your app.
## How it works
If you’ve followed our [getting started instructions](/integrations/sdk/flutter/getting-started/#install), you’re already set up to send push notifications to your Android audience. But you’ll need to add a bit of code to support your iOS users.
Remember that a device/user can’t receive a push notification until you:
1. (iOS) Register a device token for the device; code samples on this page help you do that.
2. [Identify a profile](/integrations/sdk/flutter/identify/). This associates a token with the profile; you can’t send push notifications to a device until you identify the recipient.
3. (Both iOS and Android) Check for notification permissions. If your app user doesn’t grant permission, notifications will not appear in the system tray.
4. (Optional) Set up your app to report push metrics back to Customer.io.
Did you already set up your push providers?
To send, test, and receive push notifications, you’ll need to set up your push notification service(s) in Customer.io. If you haven’t already, set up [Firebase Cloud Messaging (FCM)](/messaging/channels/push/getting-started/#for-android).
## Set up push for Android
If you followed our [Getting Started instructions](/integrations/sdk/flutter/getting-started/), you’re already set up to send push notifications to Android devices. You just need to [set up iOS push support](#register-push) in your app.
Next, you can set up [deep links](/integrations/sdk/flutter/push-notifications/deep-links/#deep-links-android) if you want your notifications to link into your app.
### Set or change your push icon
You’ll set the icon that appears on push notifications as a part of the `AndroidManifest.xml` file in your app’s `android` folder. If your icon appears in the wrong size, or if you want to change the standard icon that appears with your push notifications, you’ll need to update your app’s manifest.
```
```
## Set up push for iOS
You’ll need to add some additional code to support push notifications for iOS. You’ll need to add push capabilities in XCode and integrate push capabilities in your app.
### Add push capabilities in Xcode
Before you can work with push notifications, you need to add Push Notification capabilities to your project in XCode.
1. In your Flutter project, go to the `ios` subfolder and open `.xcworkspace`.
2. Select your project. Under *Targets*, select your main app.
3. Click the **Signing & Capabilities** tab and click **Capability**.
4. Add **Push Notifications** to your app.
5. Select **File** > **New** > **Target**.
6. Select *Notification Service Extension* and click *Next*.
7. You should see a window such as this:
You can leave many of the options in this window as their defaults, but you should:
* Enter a product name, like *NotificationServiceExtension* (which we use in our examples on this page)
* Confirm that your main app is selected in the *Embed in Application* drop-down menu
When you’re done, click **Finish**.
8. When presented with the dialog below, click **Cancel**. This will help Xcode continue debugging your app and not just the extension you just added.
Now you have another target in your project navigator named `NotificationServiceExtension`. We’ll configure this extension when we [Integrate Push Notifications](#swift-push) in the following section.
### Integrate push capabilities in your app
1. Open the file `ios/Podfile` and make the following modifications:
```
target 'Runner' do # Look for the main app target.
# Required by FCM push notification service
use_frameworks!
# Make all file modifications after these lines:
config = use_native_modules!
# Add the following line to add the Customer.io native dependency:
pod 'customer_io/fcm', :path => '.symlinks/plugins/customer_io/ios
end
# Next, copy and paste the code below to the bottom of your Podfile:
target 'NotificationServiceExtension' do
pod 'customer_io_richpush/fcm', :path => '.symlinks/plugins/customer_io/ios'
end
```
Do you need to fetch updates?
[See our update guide](/integrations/sdk/flutter/update/) for full instructions on how to update the Flutter SDK, including how to update the `Podfile`.
2. Run `pod install --repo-update --project-directory=ios` from the root directory of your Flutter project. When dependencies finish installing, you should see a message like this:
```
Pod installation complete! There are X dependencies from the Podfile and Y total pods installed.
```
3. Update your `AppDelegate.swift` file to handle push notifications.
```
import UIKit
import Flutter
import CioMessagingPushFCM
import FirebaseMessaging
import FirebaseCore
@main
class AppDelegateWithCioIntegration: CioAppDelegateWrapper {}
class AppDelegate: FlutterAppDelegate {
override func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
GeneratedPluginRegistrant.register(with: self)
// Depending on how you install Firebase,
// you may need to add functions to this file, like:
// FirebaseApp.configure()
//
// Read the official Firebase docs to install Firebase correctly!
MessagingPushFCM.initialize(
withConfig: MessagingPushConfigBuilder()
.build()
)
// Add line below only if you want to have custom control over notifications being presented and processed - Customer.io will handle those automatically
UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
override func application(_ application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
super.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
Messaging.messaging().apnsToken = deviceToken
}
}
```
4. Open your `NotificationService.swift` file in XCode and modify it with the highlighted changes below:
```
import CioMessagingPushFCM
class NotificationService: UNNotificationServiceExtension {
override func didReceive(_ request: UNNotificationRequest,
withContentHandler contentHandler:
@escaping (UNNotificationContent) -> Void) {
MessagingPushFCM.initializeForExtension(
withConfig: MessagingPushConfigBuilder(cdpApiKey: "YourCdpApiKey")
// Optional: set your Customer.io account region (.US or .EU). Default: US
.region(.US)
.build()
)
MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)
}
override func serviceExtensionTimeWillExpire() {
MessagingPush.shared.serviceExtensionTimeWillExpire()
}
}
```
Now you can run your app on a physical device and send yourself push notifications with images and deep links to test your implementation. You’ll have to use a physical device because emulators can’t receive push notifications.
### Sound in push notifications (iOS Only)
When you send a push notification to iOS devices that uses our SDK, you can opt to send the *Default* system sound or no sound at all. If your audience’s phone is set to vibrate, or they’ve disabled sound permissions for your app, the *Default* setting will cause the device to vibrate rather than playing a sound.
In most cases, you should use the *Default* sound setting to make sure your audience hears (or feels) your message. But, before you send sound, you should understand:
1. Your app needs permission from your users to play sounds. This is done by your app, not our SDKs. [Here’s an example from our iOS sample app ↗](https://github.com/customerio/customerio-ios/blob/main/Apps/APN-UIKit/APN%20UIKit/Util/NotificationUtil.swift#L12-L13) showing how to request sound permissions.
2. iOS users can go into *System Settings* and disable sound permissions for your app. Enabling the *Default* setting doesn’t guarantee that your audience hears a sound when your message is delivered!
We don't support custom sounds yet
If you want to send a custom sound, you’ll need to handle it on your own, outside the SDK and use a custom payload when you set up your push notifications.
## Test your implementation
After you set up rich push, you should test your implementation. Below, we show the payload structure we use for iOS and Android. In general, you can use our regular rich push editor; it’s set up to send messages using the JSON structure we outline below.
If you want to fashion your own payload, you can use our [custom payload](/messaging/channels/push/custom-payloads/#getting-started-with-custom-payloads).
iOS FCM payloadAndroid payload
#### iOS FCM payload
```
{
"message": {
"apns": {
"payload": {
"aps": {
// basic iOS message and options go here
"mutable-content": 1,
"alert": {
"title": "string", //(optional) The title of the notification.
"body": "string" //(optional) The message you want to send.
}
},
"CIO": {
"push": {
"link": "string", //generally a deep link, i.e. my-app://... or https://yourwebsite.com/...
"image": "string" //HTTPS URL of your image, including file extension
}
}
},
"headers": {
// (optional) headers to send to the Apple Push Notification Service.
"apns-priority": 10
}
}
}
}
```
* messageobjectrequired
The base object for all FCM payloads.
* apnsobjectrequired
Defines a payload for iOS devices sent through Firebase Cloud Messaging (FCM).
* payloadobjectrequired
Contains a push payload.
* apsobject
A push payload intended for an iOS device.
* CIOobject
Contains properties interpreted by the Customer.io iOS SDK.
* Custom key-value pairs \*any type
Additional properties that you've set up your app to interpret outside of the Customer.io SDK.
* headersobject
Headers defined by [Apple's payload reference](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns) that you want to pass through FCM.
#### Android payload
```
{
"message": {
"data": {
"title": "string", //(optional) The title of the notification.
"body": "string", //The message you want to send.
"image": "string", //https URL to an image you want to include in the notification
"link": "string" //Deep link in the format remote-habits://deep?message=hello&message2=world
}
}
}
```
* messageone ofrequired
The parent object for all push payloads.
One of:Data object onlyNotification and data object
* dataobjectrequired
Contains all properties interpreted by the SDK.
* bodystring
The body of your push notification.
* imagestring
The URL of an HTTPS image that you want to use for your message.
* linkstring
A deep link (to a page in your app), or a link to a web page.
* titlestring
The title of your push notification.
* androidobject
Contains properties that are **not** interpreted by the SDK but are defined by FCM. You need to write your own code to handle these Android push features.
* notificationobject
Properties supported specifically by Android on FCM.
* body\_loc\_argstring
Variable string values used in place of the format specifiers in `body_loc_key` to localize the body text to the user's current localization. See Formatting and Styling for more information.
* body\_loc\_keystring
String resource key used to localize the body text. See Android [String resources](https://developer.android.com/guide/topics/resources/string-resource/).
* click\_actionstring
The action that occurs when a user taps on the notification. Launches an activity with a matching intent filter when a person taps the notification.
* colorstring
The notification's icon color in `#rrggbb` format.
* iconstring
Sets the notification icon to `myicon` for drawable resource `myicon`. If you don't send this key, FCM displays the launcher icon from your app manifest.
* soundstring
The sound that plays when the device receives the notification. Supports `"default"` or the filename of a sound resource bundled in your app. Sound files must reside in `/res/raw/`.
* tagstring
An identifier you use to replace an existing notification. If a notification with the same tag is already showing, the new one replaces it. Leave it empty to create a new notification each time.
* title\_loc\_argstring
Variable string values used in place of the format specifiers in `title_loc_key` to localize the title text to the user's current localization. See Formatting and Styling for more information.
* title\_loc\_keystring
String resource key used to localize the title text. See Android [String resources](https://developer.android.com/guide/topics/resources/string-resource/).
[GitHub project](https://github.com/customerio/customerio-flutter "View the Flutter SDK on GitHub")
Version
4.4.0 (Current)2.x (2.9.0)1.x (1.5.2)
©2026 Peaberry Software, Inc. [Status](https://status.customerio.com/) [Terms of Service](https://customer.io/legal/terms-of-service/) [Privacy Policy](https://customer.io/legal/privacy-policy/)
[](https://www.linkedin.com/company/customer-io)[](https://twitter.com/customerio)[](https://www.youtube.com/channel/UCkCaWdezRoa8ZyR9pEVaipA)[](https://www.instagram.com/customer.io/)