iOS Legacy Integration Guide

This section is dedicated to the integration guide for previous versions of the OpenBack SDK.

OpenBack is a fast and easy integration for iOS apps and should take less than 15 minutes for each app.

  • Include framework in the project
  • Copy sample configuration code
  • Configure your project capabilities
  • Setup APNs certificates

The iOS SDK, which is a framework, is about 240 KB (after compression and for a specific device).


A sample application is available on Github here.

Often a cross team discussion before integration will help confirm what Custom Triggers, what Goals should be setup during OpenBack SDK integration. Contact the Onboarding team if you would like a simple template to document and agree these.

Step by Step Integration

1- Adding the OpenBack SDK

pod 'OpenBack'

Although it is prefered to use Cocoapods or Carthage to keep the library updated, if you need to integrate OpenBack manually, add OpenBack.framework to the Embedded Binaries section of your project.

Updating the OpenBack SDK

For updating the OpenBack SDK with Cocoapods or Carthage, use the commands below.

pod update OpenBack
#### Optional - Add Run Script

This step is optional if you are using the latest Cocoapods (1.4+) which already includes a fat binary stripping code.

OpenBack framework comes with multiple architectures, including ones needed for the simulator. When deploying your app to the App Store, the x86_x64/i386 architectures must be removed.

Add a Run Script in your project build phase and copy the following code:




This script comes originally from Realm. If you already are using a tool to strip unused architectures, you can skip this one.

2 - Update Your Project Capabilities

Enable Background Modes.
Check Background fetch and Remote notifications.

Background fetch is a common permission that does not prompt a user for access but can be turned off by a user in their settings,

Enabling background modes allows OpenBack to check and run messages in the background. If the "Noise" trigger is to be used in the background, Audio and Airplay needs to be checked. Similarly, if a highly accurate or precise Location trigger is required for messages, check Location updates. See Permissions for more info.


Push Notifications should be also enabled. See the Setup APNs Certificates for Push Notifications for more info.


3 - Configuring pList

OpenBack is a single version SDK built with optional features that can link to frameworks like CoreLocation.framework, CoreBluetooth.framework, etc. in iOS. Apple now require the application to have a usage description for each of these linked frameworks (from iOS10 onwards may require them), even if they are not used or enabled in your app or OpenBack configuration. As such, please include the following usage description strings, even if they are never displayed to the user - suggested text for you to edit is shared here also:

  • NSMotionUsageDescription - ">YOUR_APP< may use motion detection to improve your app experience" - OpenBack Activity Trigger
  • NSMicrophoneUsageDescription - ">YOUR_APP< uses the microphone as part of the mobile app experience" – OpenBack Noise Trigger
  • NSLocationAlwaysUsageDescription - ">YOUR_APP< uses your location for app features and to improve your experience" – OpenBack Exact Location Trigger
  • NSLocationWhenInUseUsageDescription - ">YOUR_APP< uses your location for app features and to improve your experience” - OpenBack Exact Location Trigger
  • NSLocationAlwaysAndWhenInUseUsageDescription - ">YOUR_APP< uses your location for app features and to improve your experience” - OpenBack Exact Location Trigger
  • NSBluetoothPeripheralUsageDescription - ">YOUR_APP< uses your Bluetooth information to improve your app experience" Required if targeting iOS12 and below, deprecated from iOS13 but can be left in regardless - Bluetooth Trigger
  • NSBluetoothAlwaysUsageDescription - ">YOUR_APP< uses your Bluetooth information to improve your app experience" - Bluetooth Trigger

4 - Configuring Notifications

By default, OpenBack will prompt the user for all the permissions required for all message triggers - it is recommended that this behaviour is disabled and custom permission prompts are used to ensure the best user experience for the app, by adding kOBKConfigRequestAlertNotificationsAuthorization: @(NO) to your config.

kOBKConfigRequestAlertNotificationsAuthorizationLet OpenBack prompt the user for system alert notifications authorization (BOOL, Optional, Default:YES)

A good guide for creating custom permission prompts and the best method for asking users to allow push notifications can be found here.

The Apple developer docs on asking for notification permissions can be found here.

5 - Setup APNs Certificates for Push Notifications

In the background, OpenBack uses silent Push Notifications to update messages and ensure triggers are checked regularly. As such, OpenBack requires a valid certificate from your Apple Developer Account to be uploaded into the OpenBack Dashboard.

If Push Notifications are used already, OpenBack recommends creating a specific certificate for the OpenBack library, but this isn’t required. iOS applications can have multiple APNs certificates and this additional OpenBack certificate does not interfere with any existing certificates or services in any way.

Please note APNs Certificates expire – once expired you must create a new certificate in your Apple Developer Account and upload it into the OpenBack Dashboard.

Follow the APNs Certificates Guide to create a Push Notification certificate, then upload the .p12 certificate file on the OpenBack Dashboard under App Settings for the relevant app, as shown below.


When exporting your .p12, make sure it only contains a single production push certificate. Use production certificates even for development apps.

Add the APNs certificate to the application details in the OpenBack Dashboard:

APNs Dashboard


We usually allow 15 - 30 minutes for the device to register its push token with APNs/Firebase and for our backend system to sync up.

6 - Initializing the OpenBack SDK

Note the App Code found in the Dashboard. You will need it when configuring the library.

App Code

Include the following header:

import OpenBack

Configure OpenBack in the application delegate application:didFinishLaunchingWithOptions:. For example, a typical configuration would look like this:

let config : [AnyHashable: Any] = [
// Core settings
kOBKConfigAppCode: "YOUR_APP_CODE",
// Enable options
kOBKConfigEnableAlertNotifications: true,
kOBKConfigEnableInAppNotifications: true,
kOBKConfigEnableRemoteNotifications: true,
// Don't let OpenBack request for alert notification permissions
kOBKConfigRequestAlertNotificationsAuthorization: false
do {
try OpenBack.setup(withConfig: config)
// Config was successful - You can now start OpenBack
try OpenBack.start()
} catch let err as NSError {
print("Failed to setup OpenBack: \(err)")

The configuration parameters can also be passed using in a file named OpenBackConfig.plist. Starting with 1.7.3, the configuration can also be done in the application Info.plist. In either case, setupWithConfig still needs to be called before start but can be passed an empty dictionary or local overrides.


If your app requires a user to login, make sure to start the OpenBack SDK when they login and similarly, stop the OpenBack SDK if they logout.

If you have any difficulties with the integration process, email for a quick response or message the live chat below.

Verifying the OpenBack Integration

When you have completed the basic integration of the OpenBack SDK, running your app will register your device as a user to the OpenBack Engine. You can verify that this is working properly and that you're ready to send messages by going to the Developer Tab in your App Settings and checking that your device has registered.

Checking Recent Users