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.

info

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.

note

For integrating a previous version of the SDK, click here

Migration Guide

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

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

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

AppCode

Copy that code for the next step.

tip

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

2.2 - Adding the App Code to the Info.plist

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

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

Example:

<plist version="1.0">
<dict>
...
<key>OpenBack</key>
<dict>
<key>AppCode</key>
<string>YOUR_APP_CODE</string>
<key>AppGroup</key>
<string>group.YOUR_APP_GROUP</string>
</dict>
...
</dict>
</plist>

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"
OpenBack.start()
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.

BackgroundModes

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

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>com.openback.bgtask.refresh</string>
<string>com.openback.bgtask.check</string>
</array>

PermittedTasks

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.

note

For more info on creating App Groups.

AppGroup

Add Access WiFi Information

Enable this if you plan on using the Connectivity Signal.

Wifi Info

3 - Setup APNs

note

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.

note

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

note

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 Engine. You can verify that this is working by going to the Developer Tab in your App Settings. If your device has registered, then you are ready to send messages.

Checking Recent Users

note

If you use the Keychain Services API, make sure to read the FAQ

Advanced Features

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

FeatureOverview
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.