GitHub project

Set up push notifications

Our iOS SDK supports push notifications over APN or FCM. This page can help you get started with either service.

Before you begin

This page explains how to register for push notifications using our SDK. But, before you can send push notifications, you need to add your push service credentials to Customer.io. See our push service certificates to learn more.

If you haven’t already, you’ll need to install the push package for the push service you use, APNs or FCM, and enable the Push Notifications capability in Xcode. For FCM users, you’ll also need to install the CioFirebaseWrapper dependency. See our quick start guide page for installation instructions.

Adopting UIScene or building with Xcode 27?

Keep initializing Customer.io, registering APNs tokens, and configuring notification handling in your AppDelegate as shown below. If your app adopts UIScene, see the iOS 27 UIScene migration guide for the additional scene-lifecycle steps.

Send a copy of your push to the notification inbox

Sending a copy lets people read your message after they dismiss the push, or when their device can’t receive push notifications. To send a copy of a push notification to your inbox, check Add to Notification Inbox when you draft your push notification.

Before you can send a copy of a push notification to your inbox, you need to enable in-app messaging, set up and publish an inbox, and add the inbox to your app. You can add our visual inbox, which includes a ready-made UI, or build your own and render the messages yourself.

Register for push notifications

The instructions in this section set you up to receive push notifications and report them back to Customer.io. Complete all three steps. Step 3 adds the Notification Service Extension (NSE), which your app needs to report Delivered metrics for iOS push notifications. It also lets your app show images in rich push notifications.

The SDK automatically handles push registration and push clicks for you. However, you’ll still need to identify users before you can send them push notifications.

1. Initialize the push service

After you initialize the SDK, initialize the push service that you use in your app. Your code changes slightly depending on the push service you use.

SWIFT
import CioDataPipelines
import CioMessagingPushAPN
import UIKit

@main
// Add the CioAppDelegateWrapper to handle push notifications and device token registration
class AppDelegateWithCioIntegration: CioAppDelegateWrapper<AppDelegate> {}

class AppDelegate: UIResponder, UIApplicationDelegate {
 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
     var cdpApiKey = YOUR_CDP_API_KEY
     var siteId = YOUR_SITE_ID
     
     let config = SDKConfigBuilder(cdpApiKey: cdpApiKey)
         .autoTrackDeviceAttributes(true)
         .autoTrackUIKitScreenViews()
         .migrationSiteId(siteId)

     CustomerIO.initialize(withConfig: config.build())

     // Initialize messaging features after initializing Customer.io SDK        
     MessagingPushAPN.initialize(
         withConfig: MessagingPushConfigBuilder()
             // optionally, configure the push module by calling functions on the builder. Such as: 
             .autoFetchDeviceToken(true)
             // See section below to find all the configuration options you can set. 
             .build()
     )

     return true
 }
} 
SWIFT
import CioDataPipelines
import CioFirebaseWrapper
import CioMessagingPushFCM
import FirebaseCore
import FirebaseMessaging
import Foundation
import UIKit

@main
// Add the CioAppDelegateWrapper to handle push notifications and device token registration
class AppDelegateWithCioIntegration: CioAppDelegateWrapper<AppDelegate> {}

class AppDelegate: NSObject, UIApplicationDelegate {
 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
     // FCM provides a device token to the app that
     // you send to the Customer.io SDK.

     // Initialize the Firebase SDK.
     FirebaseApp.configure()

     let siteId = YOUR_SITE_ID
     let cdpApiKey = YOUR_CDP_API_KEY

     // Configure and initialize the Customer.io SDK
     let config = SDKConfigBuilder(cdpApiKey: cdpApiKey)
         .migrationSiteId(siteId)
         .autoTrackUIKitScreenViews()
         .autoTrackDeviceAttributes(true)

     CustomerIO.initialize(withConfig: config.build())

     // Initialize messaging features after initializing Customer.io SDK        
     MessagingPushFCM.initialize(
         withConfig: MessagingPushConfigBuilder()
             // optionally, configure the push module by calling functions on the builder. Such as: 
             .autoFetchDeviceToken(true)
             // See section below to find all the configuration options you can set. 
             .build()
     )

     return true
 }
}

If you use FCM, you can migrate to Firebase Installation IDs, Firebase’s newer kind of device ID.

2. Identify your audience

Identify the person if you have not already. Even after you add a device token, you can’t use it until you associate it with a person.

SWIFT
CustomerIO.shared.identify(userId: "989388339", traits: ["first_name": firstName]) 

When you identify a person, you should see their device token in your workspace. If you don’t see a device token, see Troubleshoot a missing device token.

Note that when you identify a different person or stop identifying a person, the SDK automatically removes the device token from any previously identified person. This ensures that a device token is only registered to the currently identified person in the SDK and prevents you from sending duplicate messages messaging the wrong person.

3. Add a Notification Service Extension

Your app reports Delivered for iOS push notifications from a Notification Service Extension (NSE). If you skip this step, your iOS messages don’t report Delivered unless you report delivery yourself. Your app still reports Opened when people tap a notification. A test push still appears on your device, so you might not notice the gap until you check your metrics. See iOS delivery reporting for how this affects your numbers.

  1. Add a Notification Service Extension target to your project in Xcode. In the Embed in Application dropdown, select your app. Then, under the extension’s General tab, set Deployment Target to the same iOS version as your app.

  2. Add the Customer.io push package to the extension target. The extension is a separate target, so it can’t use the packages you added to your app.

    • Swift Package Manager: Select your extension target. Under General > Frameworks and Libraries, click + and add MessagingPushAPN or MessagingPushFCM.
    • CocoaPods: Add a target block for your extension to your Podfile, then run pod install. Use the target name you gave your extension in Xcode.
      RUBY
      target 'NotificationServiceExtension' do
        pod 'CustomerIO/MessagingPushAPN'  # or 'CustomerIO/MessagingPushFCM' if you use FCM
      end
  3. Replace the contents of the NotificationService file that Xcode created with the code for your push service.

    Xcode 16.3+ users

    If you encounter errors like “not available due to missing import of defining module ‘CioMessagingPush’”, go to your extension target’s Build Settings and set Member Import Visibility (SWIFT_MEMBER_IMPORT_VISIBILITY) to “Package” or disable it.

    SWIFT
    import CioMessagingPushAPN
    import UserNotifications
    
    class NotificationService: UNNotificationServiceExtension {
        override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
            MessagingPushAPN.initializeForExtension(
                withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_CDP_API_KEY")
                    // Optional: specify the region where your Customer.io account is located (.US or .EU). Default: US
                    .region(.US)
                    // Optional: set an App Group ID for reliable push delivery tracking
                    // .appGroupId("group.com.example.myapp.cio")
                    .build()
            )
    
            MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)
        }
    
        override func serviceExtensionTimeWillExpire() {
            MessagingPush.shared.serviceExtensionTimeWillExpire()
        }
    }
    SWIFT
    import CioMessagingPushFCM
    import UserNotifications
    
    class NotificationService: UNNotificationServiceExtension {
        override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
            MessagingPushFCM.initializeForExtension(
                withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_CDP_API_KEY")
                    // Optional: specify the region where your Customer.io account is located (.US or .EU). Default: US
                    .region(.US)
                    // Optional: set an App Group ID for reliable push delivery tracking
                    // .appGroupId("group.com.example.myapp.cio")
                    .build()
            )
    
            MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)
        }
    
        override func serviceExtensionTimeWillExpire() {
            MessagingPush.shared.serviceExtensionTimeWillExpire()
        }
    }

If Customer.io isn’t your only push provider, or you want to add features like action buttons, see rich push for code that handles those cases.

After you add the NSE, check that your messages report Delivered. Send a broadcast or automation message to your own profile, and check that message for Delivered. Test sends from the composer or Workspace settings might not create delivery metrics, so they can’t confirm that delivery tracking works. If your message arrives but doesn’t report Delivered, see Problems with rich push notifications and confirm that your extension’s Deployment Target matches your app’s.

Push configuration options

When you initialize your preferred push package (CioMessagingPushAPN or CioMessagingPushFCM), you can pass configuration options determining how the push package functions.

OptionTypeDefaultDescription
autoFetchDeviceTokenbooleantrueWhen true, the package automatically fetches the device token for push notifications.
autoTrackPushEventsbooleantrueAutomatically track opened and delivered metrics based on push notifications.
showPushAppInForegroundbooleantrueShow push notifications when the app is in the foreground. Used only if customer’s AppDelegate doesn’t implement UNUserNotificationCenterDelegate.
appGroupIdStringnilSets the App Group identifier for reliable push delivery tracking. When set, the SDK stores undelivered metrics in shared storage so they can be recovered on the next app launch. See App Groups for push tracking for setup instructions.

Troubleshoot a missing device token

If your app never receives device tokens, verify the following things in your app, in the order described below. If you use FCM, work through all four: the SDK gets an APNs token first and hands it to Firebase, so you can have a working APNs token and still have no FCM token.

  1. Confirm that your app target’s .entitlements file contains the aps-environment key, set to development or production. Xcode adds this key when it manages your entitlements. In projects where you keep a hand-maintained entitlements file in source control (React Native, Flutter, Expo prebuild, CI builds, manual signing), the key can go missing. Without it, the SDK doesn’t receive tokens. When CioAppDelegateWrapper is your app delegate, the SDK logs the registration failure; otherwise, your logs may not show why.
  2. Confirm that your provisioning profile includes the Push Notifications capability, not just your Xcode project.
  3. Confirm that CioAppDelegateWrapper is your app delegate and that you initialize MessagingPushAPN or MessagingPushFCM after you initialize the SDK. The SDK calls registerForRemoteNotifications() for you as long as you leave autoFetchDeviceToken at its default of true. If you set it to false, your app has to call registerForRemoteNotifications() itself and hand the token to MessagingPush.shared.registerDeviceToken.
  4. If you use FCM and your app has an APNs token but no FCM token, confirm that you call FirebaseApp.configure() before you initialize MessagingPushFCM. The SDK passes the APNs token to Firebase and waits for Firebase to return an FCM token. When the Firebase wrapper isn’t initialized, the SDK logs firebaseService is nil and never gets that far.

Next steps

To make delivery tracking more reliable, set up App Groups. iOS can end the Notification Service Extension before it finishes reporting a delivery. With App Groups, the SDK sends those deliveries the next time someone opens your app.

To send images and deep links in push notifications, or to use another push service alongside Customer.io, see rich push.

Updated November 9, 2026