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

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.

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

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

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.

User Data - Custom Values

Custom Triggers

typedef NS_ENUM(NSUInteger, OBKCustomTriggerType) {
    kOBKCustomTrigger1, kOBKCustomTrigger2, kOBKCustomTrigger3, 
    kOBKCustomTrigger4, kOBKCustomTrigger5, kOBKCustomTrigger6, 
    kOBKCustomTrigger7, kOBKCustomTrigger8, kOBKCustomTrigger9, 
    kOBKCustomTrigger10
};

+ setValue:forCustomTrigger:error:

+ (BOOL)setValue:(nullable id)value 
forCustomTrigger:(OBKCustomTriggerType)trigger 
           error:(NSError * _Nullable * _Nullable)error;

If using custom triggers in campaigns (where values are passed from elsewhere in the app), the application is in charge of setting the values for those triggers. The value can be of type NSString or NSNumber. See Custom Triggers for the possible custom trigger list.

Example:

[OpenBack setValue:@"myvalue" forCustomTrigger:kOBKCustomTrigger1 error:&error];
[OpenBack setValue:@(123) forCustomTrigger:kOBKCustomTrigger2 error:&error];
do {
    try OpenBack.setValue("123", forCustomTrigger: OBKCustomTriggerType.Trigger1)
} catch let err as NSError {
    print("Failed to set custom trigger: \(err)")
}

Available since: 1.0.0

User Info Keys

Key Value Description
kOBKUserInfoAddressLine1 NSString Address line 1
kOBKUserInfoAddressLine2 NSString Address line 2
kOBKUserInfoAdvertisingId NSString Advertising identifier set by the application
kOBKUserInfoAge NSString Age
kOBKUserInfoCountry NSString Country
kOBKUserInfoCountryCode NSString ISO-2 country code
kOBKUserInfoState NSString State
kOBKUserInfoDateOfBirth NSString Date of birth YYYY-MM-DD
kOBKUserInfoFirstName NSString First name
kOBKUserInfoGender NSString Gender
kOBKUserInfoOptInUpdates NSString Opting in for campaign updates "true"/"false"
kOBKUserInfoPostCode NSString Postal code
kOBKUserInfoProfession NSString Profession
kOBKUserInfoSurname NSString Surname
kOBKUserInfoTitle NSString Title
kOBKUserInfoCity NSString City
kOBKUserInfoEmailAddress NSString E-Mail address
kOBKUserInfoPhoneNumber NSString Phone Number
kOBKUserInfoIdentity1 NSString Custom user identifier 1
kOBKUserInfoIdentity2 NSString Custom user identifier 2
kOBKUserInfoIdentity3 NSString Custom user identifier 3
kOBKUserInfoIdentity4 NSString Custom user identifier 4
kOBKUserInfoIdentity5 NSString Custom user identifier 5

Note on Custom User Identifiers:
Identities are for use with the OpenBack API. If you are not an OpenBack API client, don't use them. Identities are bound to the current OpenBack user, so changing any one of them will reset user and campaign usage. A usage example: when your application has users that can login and logout, you can set one of the Identity to a token used in your system to identify that user. Later on, using the OpenBack API, you can fetch details from that user.

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

App Inbox

The OpenBack iOS SDK supports an App Inbox feature which allows users to read messages even after they have dismissed the notification. Your application is in charge of managing and displaying the messages. For more information on implementing this feature in your app, go here.