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

1- Adding the OpenBack SDK

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.

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

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

BackgroundModes

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

PushNotifications

4 - Configuring 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 - Activity Trigger
  • NSMicrophoneUsageDescription - Noise Trigger
  • NSLocationAlwaysUsageDescription - Location Trigger
  • NSLocationWhenInUseUsageDescription - Location Trigger
  • NSLocationAlwaysAndWhenInUseUsageDescription - Location Trigger
  • NSBluetoothPeripheralUsageDescription - Connectivity Trigger

5 - Setup APN Certificates for Push Notifications

In the background, OpenBack uses silent Push Notifications to update messages and ensure they are delivered and logs are collected in a timely fashion. As such, OpenBack requires a certificate to send those push notification packets which can be uploaded to your App Settings page.

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.

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

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/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 either 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.

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