Skip to content

Integration Guide

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 APN certificates

A sample application is available here.

Step by Step Integration

Adding the OpenBack framework to your project

pod 'OpenBack'
binary "https://openbacklive.blob.core.windows.net/ios/OpenBack.json"

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.

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:

bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/OpenBack.framework/strip-frameworks.sh"

Strip

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

Update your project capabilities

Enable Background Modes.
Check Background fetch and Remote notifications.

BackgroundModes

Enabling background modes allows OpenBack to check and run campaigns 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 campaigns, check Location updates. See Permissions for more info.

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

PushNotifications

Add usage description in the plist

OpenBack is built with features that link to frameworks like CoreLocation.framework, CoreBluetooth.framework, etc. Apple may require the application to have a usage description for each of these linked frameworks (iOS10 may require), even if they are not enabled in your OpenBack configuration. As such, it is highly recommended to add the following usage description strings, even if they are never displayed to the user.

  • NSMotionUsageDescription
  • NSMicrophoneUsageDescription
  • NSLocationAlwaysUsageDescription
  • NSLocationWhenInUseUsageDescription
  • NSLocationAlwaysAndWhenInUseUsageDescription
  • NSBluetoothPeripheralUsageDescription

Other Apps Trigger

If using the Other Apps trigger or plan to deep link into other apps, the list of Other Apps must be set in the project PList beforehand. Applications have to declare the list of URL Schemes they are wish to check using canOpenURL:.
Use the LSApplicationQueriesSchemes key of an array of strings.

The list of other apps to check is defined during setup using either the Dashboard or email them to integrations@openback.com

URL Schemes

Setup APN Certificates for Push Notifications

In the background, OpenBack often uses silent Push Notifications to silently update campaigns and ensure campaigns are delivered and logs are collected in a timely fashion. As such, OpenBack requires a certificate to send those push notification packets. In the project, a certificate must be created and provided to OpenBack (send to the OpenBack integrations team or upload to the Dashboard in your App settings if available on in the OpenBack account).

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. Depending on the testing being planned for the app, we recommend a combined sandbox/production certificate, or just the production certificate.

Follow the APN Certificates Guide to create a Push Notification certificate, then upload the .p12 certificate file on the OpenBack Dashboard for your app.

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

APN Dashboard

Initializing the OpenBack Library

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

App Code

Include the following header:

#import <OpenBack/OpenBack.h>
import OpenBack

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

NSDictionary *config = @{
  // Core settings
  kOBKConfigAppCode: @"YOUR_APP_CODE",
  // Enable options
  kOBKConfigEnableAlertNotifications: @(YES),
  kOBKConfigEnableInAppNotifications: @(YES),
  kOBKConfigEnableRemoteNotifications: @(YES),
  // Let OpenBack prompt for permissions
  kOBKConfigRequestAlertNotificationsAuthorization: @(YES)
};

NSError *error = nil;
if ([OpenBack setupWithConfig:config error:&error]) {
  // Config was successful - You can now start OpenBack
  if ([OpenBack start:&error]) {
    // Started successfully
  }
} else {
  // Check error code
}
let config : [AnyHashable: Any] = [
    // Core settings
    kOBKConfigAppCode: "YOUR_APP_CODE",
    // Enable options
    kOBKConfigEnableAlertNotifications: true,
    kOBKConfigEnableInAppNotifications: true,
    kOBKConfigEnableRemoteNotifications: true,
    // Let OpenBack prompt for permissions
    kOBKConfigRequestAlertNotificationsAuthorization: true
]

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 wither case, setupWithConfig still needs to be called before start but can be passed an empty dictionary or local overrides.

See plist configuration for more info.