Push notifications

Our iOS SDK supports push notifications over APN or FCM. Use this page to get started with either service.

This page is part of a setup flow for the SDK. Before you continue, make sure you've implemented previous features—i.e. you can't receive push notifications before you identify people!

Before you begin

This page explains how to receive push notifications using our SDK. However, before you can send push notifications to your audience, you need to enable Customer.io to send push notifications through your preferred service: Apple Push Notification Service (APNs) or Firebase Cloud Messaging (FCM).

This process lets you receive basic push notifications in your app—a title and a message body. To send a more complicated push, complete the process on this page, and then see our rich push documentation.

Install the push package

Before you can receive push notifications, you need to install the push package supporting the push service you use—APNs or FCM.

1. Use Swift Package Manager to install your push package. See our Getting Started page for installation instructions.

   • APNs: install MessagingPushAPN
   • FCM: install MessagingPushFCM

2. Enable the Push Notifications capability in XCode ↗.

Register for push notifications

To send a push notification, you have to register for a device token and identify the user, which associates the device token with a profile in Customer.io. You can do these things in any order—it doesn’t matter whether you register for a token before or after you identify the current user.

When you identify a profile or stop identifying a profile, the SDK automatically removes the device token from any previously identified profile and then associates any existing device token with the newly identified profile. This ensures that a device token is only registered to the currently identified profile in the SDK. This prevents you from sending duplicate messages or sending messages to the wrong profile.

1. After you initialize the SDK, register for remote push to receive a device token from your push service. Your code changes slightly depending on the push service you use.

   APNsFCM

   APNs

   import CioTracking
   import CioMessagingPushAPN
   
   class AppDelegate: NSObject, UIApplicationDelegate {
   
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        CustomerIO.initialize(siteId: "YOUR SITE ID", apiKey: "YOUR API KEY")
   
        // It's a good practice to register for remote push when the app starts.
        // This asserts that the Customer.io SDK always has a valid device token.
        UIApplication.shared.registerForRemoteNotifications()
   
        return true
    }
   
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        MessagingPush.shared.application(application, didRegisterForRemoteNotificationsWithDeviceToken: deviceToken)
    }
   
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        MessagingPush.shared.application(application, didFailToRegisterForRemoteNotificationsWithError: error)
    }
   }

   FCM

   import CioMessagingPushFCM
   import CioTracking
   import Firebase
   import FirebaseMessaging
   
   class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        FirebaseApp.configure()
   
        CustomerIO.initialize(siteId: "YOUR SITE ID", apiKey: "YOUR API KEY")
   
        // Set FCM messaging delegate
        Messaging.messaging().delegate = self
   
        // You should register for remote push when the app starts.
        // This asserts that the Customer.io SDK always has a valid device token.
        UIApplication.shared.registerForRemoteNotifications()
   
        return true
    }
   }
   
   extension AppDelegate: MessagingDelegate {
    func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
        MessagingPush.shared.messaging(messaging, didReceiveRegistrationToken: fcmToken)
    }
   }

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

   CustomerIO.shared.identify(identifier: "989388339", body: ["first_name": firstName])

When you identify a profile, you should see their device token in your workspace. You can send a simple push notification to test your implementation. See Rich push if you want to send a push with images, action buttons, or deep links.

Capture push metrics

Customer.io supports device-side metrics that help you determine the efficacy of your push notifications: delivered when a push notification is received by the app and opened when a push notification is clicked.

If you already configured rich push notifications, the SDK will automatically track opened and delivered events for push notifications originating from Customer.io.

Otherwise, you can:

• Record push metrics with UserNotifications.
• Extract delivery ID and Delivery Token parameters directly.

Capture push metrics with UserNotifications

If you’re using a version of iOS that supports UserNotifications, you can track metrics using our UNNotificationContent helper.

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    // This 1 line of code might be all that you need!
    MessagingPush.shared.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)

    // If you use `UserNotifications` for more then Customer.io push notifications, you can check
    // if the SDK handled the push for you or not.
    let handled = MessagingPush.shared.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)
    if !handled {
        // Notification was *not* displayed by Customer.io. Handle the notification yourself.
    }
}

Extract delivery ID and token

If you’re not using a version of iOS that supports UserNotifications, you should send the push metric manually by extracting the CIO-Delivery-ID and CIO-Delivery-Token parameters directly to track push metrics.

guard let deliveryID: String = notificationContent.userInfo["CIO-Delivery-ID"] as? String,
      let deviceToken: String = notificationContent.userInfo["CIO-Delivery-Token"] as? String else {
    // Not a push notification delivered by Customer.io
    return
}

MessagingPush.shared.trackMetric(deliveryID: deliveryID, event: .delivered, deviceToken: deviceToken)

Disable automatic push tracking

Automatic push metric recording is enabled by default when you install the SDK. You can disable this behavior.

CustomerIO.config {
  $0.autoTrackPushEvents = false
}