Push notifications

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

 Our mobile SDKs are in alpha and subject to change

While we’re very excited about our mobile SDKs, they’re still works in progress! If you want to try them out, contact product@customer.io

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 --> testing-error-handling(handle errors) push --> testing-error-handling rich-push --> testing-error-handling 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 testing-error-handling href "/docs/sdk/ios/testing-error-handling" 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.

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. Enabling Push Notifications In XCode, go to App > Capabilities and enable Push Notifications.

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

    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")
    
            // You can provide a Region to set the Region for your Workspace:
            CustomerIO.initialize(siteId: "YOUR SITE ID", apiKey: "YOUR API KEY", region: Region.EU)
    
            // 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) { [weak self] result in 
            // It's recommended to use `[weak self]` in the callback. 
            guard let self = self else { return }
    
            switch result {
            case .success: 
            // Device token successfully added to profile!
            break 
            case .failure(let customerIOError):
            // An error occurred. You should parse the `customerIOError` to learn more.
            break 
            }
        }
        }
        
        func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        MessagingPush.shared.application(application, didFailToRegisterForRemoteNotificationsWithError: error) { [weak self] result in 
            // It's recommended to use `[weak self]` in the callback. 
            guard let self = self else { return }
    
            switch result {
            case .success: 
            // Device token successfully removed from profile!
            break 
            case .failure(let customerIOError):
            // An error occurred. You should parse the `customerIOError` to learn more.
            break 
            }
        }
        }
    }
       
  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. The SDK automatically adds and removes the device token from the person when you identify and stop identifying them.

You should now see a device token in your Customer.io Workspace for the identified person. 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 APN. Call the Customer.io SDK to add the token to the identified person.

    import CioMessagingPushFCM
    import CioTracking
    import Firebase
    import FirebaseMessaging
    import Foundation
    import UIKit
    
    class AppDelegateFCM: NSObject, UIApplicationDelegate {
        func application(
            _ application: UIApplication,
            didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
        ) -> Bool {
            FirebaseApp.configure() // run first so crashes are caught before all other initialization.
            // If you're using the shared singleton method, initialize the SDK here in the `AppDelegate`.
            CustomerIO.initialize(siteId: "YOUR SITE ID", apiKey: "YOUR API KEY", region: Region.US)
    
            // 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 AppDelegateFCM: MessagingDelegate {
        func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
            guard let fcmToken = fcmToken else { return }
            
            MessagingPush.shared.messaging(messaging, didReceiveRegistrationToken: fcmToken) { result in
                // We recommend using `[weak self]` in the callback. 
                guard let self = self else { return }
       
                switch result {
                case .success: 
                    // Device token successfully removed from profile!
                    break 
                case .failure(let customerIOError):
                    // An error occurred. You should parse the `customerIOError` to learn more.
                    break 
                }
            }
        }
    }
       
  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. The SDK automatically adds and removes the device token from the person when you identify and stop identifying them.

You should now see a device token in your Customer.io Workspace for the identified person. 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

You must configure your app to report device-side metrics back to Customer.io when people interact with your messages. Customer.io supports three device-side metrics: delivered, opened, and converted. You can find more information about these metrics in our push developer guide.

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
    ) {
        MessagingPush.shared.trackMetric(notificationContent: response.notification.request.content, event: .delivered) { [weak self] result in 
             // We recommend using `[weak self]` in the callback. 
            guard let self = self else { return }
      
            switch result {
            case .success: 
              // Metric successfully tracked
              break 
            case .failure(let customerIOError):
              // An error occurred. You should parse the `customerIOError` to learn more.
              break 
            }
        }
    }

Extract delivery ID and token

If you’re not using a version if iOS that supports userNotifications, you should extract 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){ [weak self] result in 
     // We recommend using `[weak self]` in the callback. 
    guard let self = self else { return }

    switch result {
    case .success: 
      // Metric successfully tracked
      break 
    case .failure(let customerIOError):
      // An error occurred. You should parse the `customerIOError` to learn more.
      break 
    }
}

Disable automatic push tracking

If you configured rich push notifications, the SDK will automatically track opened and delivered events for push notifications originating from Customer.io. You can call configure on your initialized CustomerIO instance or the shared instance to disable this behavior.

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