Skip to main content

iOS Integration Guide

OpenBack iOS SDK version 4.0.13

Adding the OpenBack SDK to your iOS apps is simple. It should take less than 15 minutes for each app and involves:

  • Include the framework in the project.
  • Configure your project settings.

The iOS SDK framework is ~815kB (after compression and thinning for a specific device).

For a quick walkthrough of the integration, you can watch our tutorial video below.


A sample application is available on Github.

A cross-team discussion before integration will help confirm which custom features should be setup during integration.

Contact the OpenBack Onboarding team if you would like any help to finalize these requirements.

Migration and Deprecated SDK

For migrating from a previous version of the iOS SDK, click here.

For integrating a previous version of the SDK, click here


If you use the Keychain Services API or any other background services, make sure to read the FAQ and our guide on iOS automatic actions. The OpenBack iOS SDK frequently runs in the background using background refresh

1 - Add the OpenBack SDK

pod 'OpenBack'

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

Optional Packages

The OpenBack SDK comes in multiple packages to fit your project requirements. If you wish to send messages based on location/bluetooth/motion information, please add the appropriate package. See the Signals page for more info.

Updating the OpenBack SDK

When using OpenBack, we recommend to use the latest version of the SDK as features are regularly added.

Use the commands below to update the OpenBack SDK with Cocoapods or Carthage.

pod update OpenBack

2 - Configure Your Project

2.1 - Open the Dashboard


If you have already created your app in the dashboard then you can skip to step 2.2

If you have Quick Start enabled, you can quickly create a new app. Add your App Bundle ID and App Name to the Quick Start section.

Quick Start Step 1

After creating your app, you will be brought to the settings page for that app. From here you can copy your App Code and add it to your info.plist.

Quick Start Step 2

2.2 - Adding the App Code to the Info.plist

You can find the unique App Code for your application in the Dashboard.


Copy that code for the next step.


If you can't see your app in the App Settings page, make sure you have Demo Mode disabled!

You can configure OpenBack in your application Info.plist using the OpenBack dictionary or in its own plist file named OpenBack.plist.

AppCodestringThe OpenBack app code for your application
AppGroupstringThe app group used for OpenBack and app extenstions


<plist version="1.0">

This is the minimal setup needed to run OpenBack, for advanced configuration check the Advanced Configuration page.

Setting the App Code programmatically

If you do not provide an App Code in the plist, you can set it using the SDK API.

func application(_ application: UIApplication, 
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
OpenBack.appCode = "YOUR_APP_CODE"
return true

Check the API Docs for more info.

2.3 - Configure the Project Settings

The following steps describe the minimal settings for the core framework to work. You will need to do some extra setup depending on the signals you are expecting to use. See Signals & Authorizations for more info.

Add Capabilities

Add Background Modes

Check Background fetch, Background processing and Remote notifications.


When background processing is enabled, add the following two permitted tasks to the Info.plist:



Add Push Notifications

This should be enabled. See the Setup APNs Certificates section for more info.

Xcode Push Notifications

Add the shared App Group

In order to work with the notification application extensions, you need create an App Group for OpenBack. Make sure to add it to the OpenBack section of your plist. For more info on creating App Groups.


Using the same App Group in multiple apps with the SDK may cause conflicts when they are all installed on the same device.


Add Access WiFi Information

Enable this if you plan on using the Connectivity Signal.

Wifi Info

3 - Setup APNs


We recommend using APNs but it is not required. See more here

In the background, OpenBack can use silent push notifications to update messages and ensure that Signals are checked often. As such, OpenBack requires a valid certificate from your Apple Developer Account to be uploaded into the OpenBack Dashboard. While this is optional, it improves performance and we recommend it unless there are specific privacy (e.g. COPPA) reasons for not implementing, click here to Talk to an Expert

If push notifications are used already, we recommend creating a specific certificate for the OpenBack SDK. iOS applications can have multiple APNs certificates. An additional OpenBack certificate does not interfere with any existing certificates.

Please note that APNs .p12 Certificates expire. When they expire 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. Upload the .p12 certificate file on the OpenBack Dashboard under App Settings for your app, as shown below.


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

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

APN Dashboard


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

4 - Verifying the OpenBack Integration

Running your app will register your device as a user to the OpenBack platform. You can verify that this is working by going to the Verify Latest Installs section within the App Setup tab in your App Settings. If your device has registered, then you are ready to send messages.

Checking Recent Users

When you can see your device registered within this section, follow our guide to create your first push message.


Using the Unlock signal for iOS may take some minutes to work as the check for an unlocked device is not instant

Advanced Features

For integrating features from a previous version of the SDK, click here.

Signals & PermissionsAdd the required settings and permissions in your project settings for signals.
AttributesAttribute values can be set client side by your mobile app, and then used as personalized content within messages.
Custom SegmentsCustom Segments are set client side by your mobile app. They can be used to deliver a message based on the value set in your message campaign which is managed through the OpenBack Dashboard or Client APIs.
GoalsGoals can range from anything such as a user completing a signup process, to a user purchasing a product.
EventsAn event is a user action which is used to deliver a notification. You can pass existing or new events to the OpenBack SDK client-side, making advanced campaigns simple.
App InboxDeliver & manage messages in an inbox within your app – standalone, or as part of a notification.
TopicsMessage users that are subscribed to specific topics.
Advanced ConfigurationAdvanced OpenBack configuration parameters.
NotificationsCustomize the appearance of OpenBack notifications.