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 identify people before you initialize the SDK!

graph LR getting-started(Install SDK) -->B(Initialize SDK) B --> identify(identify people) identify -.-> track-events(Send events) identify -.-> register-token(Register
Device Token) register-token -.-> push(Receive push) register-token -.-> rich-push(Receive Rich Push) track-events --> test-support(Write tests) push --> test-support rich-push --> test-support identify -.-> in-app(Receive in-app) in-app --> test-support click getting-started href "/docs/sdk/ios/getting-started" click B href "/docs/sdk/ios/getting-started/#initialize-the-sdk" click identify href "/docs/sdk/ios/identify" click track-events href "/docs/sdk/ios/track-events/" click register-token href "/docs/sdk/ios/push" click push href "/docs/sdk/ios/push" click rich-push href "/docs/sdk/ios/rich-push" click in-app href "/docs/sdk/ios/in-app" click test-support href "/docs/sdk/ios/test-support" style push fill:#B5FFEF,stroke:#007069 style register-token fill:#B5FFEF,stroke:#007069

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.

 Check out our sample app!

Our Remote Habits app, provides a real-world example and can act as a template to help you implement the SDK.

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 person 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 person or stop identifying a person, 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 person.

  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.

    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)
     }
    }
    
    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 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.

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

When you identify a person, 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 three device-side metrics that help you determine the efficacy of your push notifications: delivered, opened, and converted.

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:

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. 
    }
}

 UserNotifications has some inconsistencies when tracking delivered events.

If delivered events are important to you, we recommend that you follow the setup instructions for rich push notifications, even if you do not plan on sending rich push notifications as rich push tracks delivered events more reliably.

Extract delivery ID and token

If you’re not using a version if 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
}
Copied to clipboard!
Latest release
 1.2.6
Is this page helpful?