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.

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

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 silently 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 here:

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.

Custom Values & User Info

Custom values and user info (including Identity) can all be used for personalised content within messages. Custom values are used to segment/trigger messages for users. Identity is used when integrating the OpenBack Client API into your backend systems.

Custom Values

Custom value triggers are set by your mobile app and are used to trigger a message when the value set by the mobile app matches the value set in the message through the OpenBack Dashboard or Client API. The values set can also be used as personalised content within messages.

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

User Info can be used to personalise content within messages. The Identity keys (KOBKUserInfoIdentity – Custom User Identifier) is only used when you integrate the OpenBack Client API into your backend systems and want to message a user with that identity.

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:
Identity is 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.

Goals

The OpenBack SDK can be used to track Goals. These can range from anything such as a user completing a signup process, to a user purchasing a product.

Every goal has six components:

  • Goal Code - This is a unique identifier for each goal.
  • Goal Name - A name to easily distinguish between each goal.
  • Goal Description - A short description of what the goal achieves.
  • Number of Steps - The number of steps required for the goal to be completed. For example, step 1 is a user viewing a product, step 2 is the user adding the product to their cart. Step 3 and goal completion is the user purchasing the product.
  • Conversion Window - The length of time after a notification is received that it can be attributed to a goal completion.
  • Default Goal Value - This sets how much the goal completion is worth.

You can find the steps to logging a goal in iOS here.

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.