Push notifications SDK for iOS

This page details how to install Ortto’s iOS software development kit (SDK) in your app to deliver push notifications to contacts.

The following instructions assume your app is built using Xcode.

Each of the code snippets provided is copyable. Simply hover over the snippet and click the copy icon in the top-right corner.

Example code snippet showing copy function

These instructions cover the key steps to installing the Ortto iOS SDK and configuring your app to handle Ortto’s push notifications:

Install the Ortto iOS SDK
Identify people (contacts)
Track events
Complete the setup in Ortto.

Once you complete these key steps, you’ll be ready to create and send push campaigns.

Prerequisites

iOS developers have 2 options for enabling push notifications:

If using Firebase, you’ll need to:

Create a new (or use an existing) Firebase project and configure Google Cloud roles and permissions.
Upload the .json file created in your Firebase project to Ortto, so that Ortto’s notifications APIs can access your Firebase data.

Learn about creating the Firebase project and enabling Ortto access in Firebase cloud messaging setup.

If using APNS, in your Ortto account Settings Push notifications iOS notifications Setup you simply need to select the Keys tab and provide the keys and IDs specified.

Push notifications only work on real devices and the iOS simulator will not be able to register for push notifications from Apple.

Install

There are three key elements to the SDK installation:

Install the and initialize SDK — install and initialize the relevant Firebase or APNs packages along with Ortto’s iOS SDK.
Create a service extension — enable your app to receive notifications when the customer does not have the app open.
Firebase additional setup — required if using Firebase Cloud Messaging.
Deep links — enable deep linking in push notifications.
Authorization token — register the contact’s device with Ortto.

Install and initialize the SDK

Firstly, you’ll need to set up your dependencies. Below are instructions for each Swift package manager and Cocoapods, simply expand the section relevant to you.

Instructions for Swift package manager

In Xcode, in your app’s project, select File Add Packages.
In the package manager, paste the URL for Ortto’s iOS SDK GitHub repository: https://github.com/autopilot3/ortto-push-ios-sdk.

At Dependency Rule, we recommend you set Up to Next Major Version to keep your app up to date with the latest SDK, including new features that are added.

Click Add package.
You’ll see a list of packages available to install. Select:
- OrttoSDKCore (required, this is the SDK for Ortto’s push notifications), and
- OrttoPushMessagingAPNS (required for APNs-based projects) or OrttoPushMessagingFCM (required for Firebase-based projects) as relevant.
  
  Example selection for installing Ortto SDK and APNS packages
  
  Click Add package.

Instructions for Cocoapods

In your Podfile, add the relevant dependencies:

OrttoSDKCore (required, this is the SDK for Ortto’s push notifications), and
OrttoPushMessagingAPNS (required for APNs-based projects) or OrttoPushMessagingFCM (required for Firebase-based projects).

pod 'OrttoSDKCore', '~> 1.2.2'
pod 'OrttoPushMessagingFCM', '~> 1.2' # For Firebase
pod 'OrttoPushMessagingAPNS', '~> 1.2' # For Apple APNS

After you have added the core (OrttoSDKCore) and push (OrttoPushMessagingFCM or OrttoPushMessagingAPNS) pods to your Podfile, run pod install to install the required dependencies.

To install OrttoSDKCore, add the following to your project’s AppDelegate object:

import OrttoSDKCore

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

	func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
		// Prepare Ortto SDK
    //see note below regarding push endpoint regions
		Ortto.initializeOrtto.initialize(appKey: <APPLICATION_KEY_HERE>, endpoint: <API_ENDPOINT_HERE>, shouldSkipNonExistingContacts: true)
  }

  func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
		PushMessaging.shared.registerDeviceToken(apnsToken: deviceToken)
  }

	func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    let handled = PushMessaging.shared.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)

	    if !handled {
        // tell the app that we have finished processing the user’s action / response
        completionHandler()
	    }
	  }

  func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
      print("didFailToRegisterForRemoteNotificationsWithError")
//			PushM
  }

  // Receive displayed notifications for iOS 10 devices.
  func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification) async -> UNNotificationPresentationOptions {
    return [[.alert, .sound]]
	}
}

Your <OrttoApplicationKey> value can be found in your Ortto account, at Settings Push notifications iOS notifications Application key.

The <OrttoEndpoint> value can be found in your Ortto account, at Settings Push notifications iOS notifications API endpoint.

Ortto’s default push API service endpoint is: https://capture-api.autopilotapp.com/.

Ortto customers who have their instance region set to Australia or Europe will use specific push endpoints relative to the region:

Australia: https://capture-api.au.autopilotapp.com/
Europe: https://capture-api.eu.autopilotapp.com/

Learn more about shouldSkipNonExistingContacts under Skip non-existing contacts in the Identify people section.

Create a service extension

A service extension is required to enable your app to receive notifications when the customer does not have the app open (the app is running in the background or not running at all). The service is a special registered class that iOS passes notifications to.

To add the service extension, in Xcode:

Navigate to the File New Target.
At Choose a template… search for "notification" in the modal.
Select Notification Service Extension.
Click Next.
Configure the extension target.
Click Finish.

Once the extension target is added, modify it as follows:

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {

        self.contentHandler = contentHandler
        (1)
        let handled = PushMessaging.shared.didReceive(request, withContentHandler: contentHandler)
        (2)
        if !handled {
            print("Handled!")
        }
    }

    override func serviceExtensionTimeWillExpire() {
        // Called just before the extension will be terminated by the system.
        // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
        (3)
        if let contentHandler = contentHandler,
            let bestAttemptContent =  bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
}

1	Call the `PushMessaging.shared.didReceive()` method with the `UNNotificationRequest` object. The function will return `true` if Ortto has handled the notification and `false` if Ortto has ignored the notification request.
2	If the `handled` var is equal to `false`, this means you need to handle the processing of the notification request yourself.
3	If the notification request timeout is hit (30 seconds) you will have a chance to quickly modify the `UNMutableNotificationContent` object before it is presented to the contact.

Ensure your NotificationService extension target has access to the required SDK packages.

Example required packages for using APNS to send notifications

Firebase additional setup

If you are using Firebase, in addition to the setup described in Firebase cloud messaging setup, you’ll need to perform a few extra steps.

In your AppDelegate object (<project>/AppDelegate.swift):

Add the following to the didFinishLaunchingWithOptions method:

// Set up firebase
FirebaseApp.configure()

// Assign the AppDelegate to Firebase
Messaging.messaging().delegate = self

Extend the Firebase MessagingDelegate protocol to intercept Firebase messages:

extension AppDelegate: MessagingDelegate {
  // [START refresh_token]
  func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {

    PushMessaging.shared.messaging(messaging, didReceiveRegistrationToken: fcmToken)

    NotificationCenter.default.post(
      name: Notification.Name("FCMToken"),
      object: nil,
      userInfo: [:]
    )
  }
}

Deeplinks

All actions utilize deeplinks and are routed to your SceneDelegate. Add code similar to the below to your SceneDelegate (<project>/SceneDelegate.swift) to intercept these inbound deep links and route to your controller:

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {

      guard let context = URLContexts.first else { (2)
          return
      }

      (3)
      guard let navController = window?.rootViewController as?  UINavigationController else {
          return
      }

      (4)
      guard let vc = navController.storyboard?. instantiateViewController(identifier: "controller_deeplink") as? DeeplinkViewController else {
          return
      }

      vc.modalPresentationStyle = .fullScreen (5)
      vc.deepLink = context.url.absoluteString (1)
      navController.present(vc, animated: true)
  }

1	To get an iOS deeplink value to use in a push campaign (at the Content step, as a button destination — see screenshot below), access it from here using the following steps.
2	Look for a URL context passed into the `scene` method.
3	Get the navigation controller for the scene.
4	Route and instantiate a new controller to handle the deeplink.
5	Present the controller to the contact in the navigation controller.

Authorization token

Authorization is handled automatically by your AppDelegate. Ensure you are passing along the appropriate token to the PushMessaging shared instance like below:

# APNs
PushMessaging.shared.registerDeviceToken(apnsToken: deviceToken)

# Firebase
PushMessaging.shared.registerDeviceToken(fcmToken: deviceToken)

You must call registerDeviceToken and receive a session ID before you can identify people (using identify()). Otherwise, Ortto’s API will not be able to handle the identify request.

Identify people

A contact is considered anonymous when they are not logged in to the app or they cannot be identified using the identify function.

While push notifications can be sent to anonymous contacts, we recommend identifying your contacts so they can be linked to your existing CDP records. This then gives you the opportunity to personalize push notifications based on that contact’s data

The identify method identifies contacts who are subscribed to push and recognizes them when they log in to your app. Once logged in, the contact can receive notifications.

Identifying people is also necessary for tracking events.

The identify method can capture the following contact attributes:

firstName,
lastName,
contactId,
email,
externalId,
phone, and
acceptsGDPR.

You must identify contacts by a minimum of 1 of the following attributes:

email,
phone
contactId, or
externalId.

Additional attributes are optional.

To identify contacts, where relevant (such as your login or main activity), create a UserIdentifier object:

let user = UserIdentifier(
    contactID: "abc123",
    email: "name@domain.com",
    phone: "+61404040404",
    externalID: currentUser?.uid,
    firstName: "Potato",
    lastName: "Head"
)

Ortto.shared.identify(userIdentifier: user)

The UserIdentifier object:

saves the contact’s information on the device and enables tracked events to be associated with the contact, and
associates the authorization token with the contact to handle push notifications (using OrttoSDKCore).

The contact’s device must be authorized (using registerDeviceToken) before you can identify them (using identify()). Otherwise, Ortto’s API will not be able to handle the identify request.

The SDK can only identify one contact at a time, and will save the most recently identified contact. If Jane Smith is identified, then the identify function calls John Smith, the SDK will consider John Smith the contact using the app.

We recommend updating the contact data at least every 2 months with an identify() call to capture any contact attribute changes. This function calls Ortto’s API to collect the current contact attribute data.

Ortto.shared.identify(userIdentifier: user);

Unidentified users

Unidentified users are people who have allowed push notifications but for whom you do not yet have any identifying information.

You have the option to store an unidentified user as a contact immediately when they provide push permission, and be able to send them push notifications, however the contact will have no identifying information.

Or, you can choose to save the contact’s push permission but only record them as a contact once you receive identifying information, and you won’t be able to send messages to them until their identity is confirmed.

Managing unidentified users is performed in the Ortto app, at Settings Push notifications iOS notifications Unidentified users.

Permission prompts

iOS push notification permissions are obtained by the contact (subscriber) accepting the notification request prompt per the app install. Apps are able to query notifications to see the current status of the notification permission.

To obtain a contact’s iOS push notification permission, you need to register your app delegate as the UNUserNotificationCenterDelegate.

If the contact has not yet accepted the Ortto-specific notification permission, iOS will prompt the contact to accept it. To enable this at the`AppDelegate` object, add application.registerForRemoteNotifications():

class AppDelegate: UIApplicationDelegate, UNUserNotificationCenterDelegate {

if #available(iOS 10.0, *) {
  // For iOS 10 display notification (sent via APNS)
  UNUserNotificationCenter.current().delegate = self

  let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
  UNUserNotificationCenter.current().requestAuthorization(
    options: authOptions,
    completionHandler: { _, _ in }
  )
} else {
  let settings: UIUserNotificationSettings =
    UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
  application.registerUserNotificationSettings(settings)
}

application.registerForRemoteNotifications()

let center = UNUserNotificationCenter.current()
center.requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
    if let error = error {
        print("err: \(error.localizedDescription)")
        return
    }
  }
}

Set push permission

We give you more control over contacts' push notification permissions with the setPermission(Permission) method. Use this method if you wish for further control around how Ortto understands your contacts' messaging preferences.

// Let the SDK determine if the user has granted permission (Default)
Ortto.instance().setPermission(Permission.Automatic)

// The user has explicitly granted permission
Ortto.instance().setPermission(Permission.Accept)

// Opt the user out of push notifications
Ortto.instance().setPermission(Permission.Deny)

Skip non-existing contacts

The Ortto class initializer Ortto.initialize accepts a third parameter named skipNonExistingContacts which controls whether the Ortto API should ignore all permission requests for contacts it cannot identify.

This parameter is optional and defaults to false.

// Ignore all requests for contacts which do not exist in your Ortto CDP
Ortto.initialize(
		datasourceID: datasourceID!,
		endpoint: endpoint,
		skipNonExistingContacts: true,
    allowsAnonUsers: false
)

Track actions and events

Delivery events

Push message delivery (receipt) is automatically tracked in the Ortto SDK. Delivery events will be reflected in the Ortto app as a Delivered Push activity associated with a contact.

Click tracking

The Ortto iOS SDK automatically tracks which action the contact clicked in the notification message before calling UIApplication.shared.open(url, options: [:], completionHandler: nil) with the deep link string.

This method will populate the Clicked push activity for a contact, including the deep link URL in the activity attributes.

Ortto setup

In Ortto, at Settings Push notifications iOS notifications. Setup, you have 3 options by which to enable Ortto to send push notification campaign data to your app:

Certificates — follow the instructions at iOS certificate and key to generate a .p12 file to upload.
Keys — follow the instructions at iOS certificate and key to generate a .p8 file to upload.
Firebase cloud messaging (FCM) — use the Service account (.json) file and Bundle ID created during the Firebase Cloud Messaging setup.

The Bundle ID can be found in Xcode in your project at Targets General Identity.

Once the SDK installation and configuration is complete, and you have have provided the required credentials in the Ortto setup, Ortto will wait until it detects activity from your app before your iOS platform can be switched ON. Ortto needs to receive an initial request from your app to enable push permissions for a contact (via the permission prompt or an explicitly set push permission), which confirms that your app is correctly configured and is ready to deliver notifications to subscribers. Once the activity is successfully detected, Ortto sets your iOS notifications to ON, and you can select the platform when creating a push campaign.