Push notifications

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

This page is part of an introductory series to help you get started with the essential features of our SDK. The highlighted step(s) below are covered on this page. 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 -.-> push(Receive push) identify -.-> rich-push(Receive Rich Push) track-events --> test-support(Write tests) push --> test-support rich-push --> 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 push href "/docs/sdk/ios/push" click rich-push href "/docs/sdk/ios/rich-push" click test-support href "/docs/sdk/ios/test-support" style push 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.

How it works

Before a device can receive a push notification, you must:

  1. Set up your push notification service implementation—APNs or FCM.
  2. Register a device token for the device.
  3. Identify a person. This associates a token with the person.
  4. Set up your app to report push metrics back to Customer.io.
  5. Set up a campaign to send a push notification through the Customer.io composer.

Push with APNs

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

  2. Enable the Push Notifications capability in XCode.

  3. After you initialize the SDK, register for remote push to receive a device token from APNs. Then, call the Customer.io SDK to add the token to the person:

    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 APN device token to use.
            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)
        }
    }
       
  4. 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.

    You can identify a person before or after you register a device token. 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.

You should see a device token for the identified person in your workspace. You can send a simple push notification to test your implementation. If you want to use images, action buttons, or deep links follow the instructions to send a Rich push.

Push with FCM

  1. Use Swift Package Manager to install the MessagingPushFCM package. See the Getting Started page for installation instructions.

  2. Follow the instructions to setup FCM on iOS.

  3. Initialize the SDK and register for remote push to receive a device token from FCM. Call the Customer.io SDK to add the token to the identified person.

    import CioMessagingPushFCM
    import CioMessagingPush
    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 APN device token to use.
            UIApplication.shared.registerForRemoteNotifications()
    
            return true
        }
    }
    
    extension AppDelegate: MessagingDelegate {
        func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
            MessagingPush.shared.messaging(messaging, didReceiveRegistrationToken: fcmToken)
        }
    }
       
  4. 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.

    You can identify a person before or after you register a device token. 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.

You should see a device token for the identified person in your workspace. You can send a simple push notification to test your implementation. If you want to use images, action buttons, or deep links follow the instructions to send a Rich push.

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 disable this behavior.

CustomerIO.config {
  $0.autoTrackPushEvents = false
}
Copied to clipboard!