Skip to content

iOS Setup

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

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 Values, what Goals and which Other Apps triggers should be setup during OpenBack SDK integration. Contact the integrations team if you would like a simple template to document and agree these.

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.

Updating the OpenBack SDK

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

pod update OpenBack
carthage 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:

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.

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.

BackgroundModes

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

PushNotifications

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

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.

Permission Description
kOBKConfigRequestAlertNotificationsAuthorization Let 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 APN 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 APN Certificates expire – once expired you must create a new certificate in your Apple Developer Account and upload it into the OpenBack Dashboard.

Follow the APN 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 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;
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),
  // Don't let OpenBack request for alert notification permissions
  kOBKConfigRequestAlertNotificationsAuthorization: @(NO)
};

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

See plist configuration for more info.

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 integrations@openback.com for a quick response or message the live chat below.