Introduction

Purpose and Scope

This document provides technical guidelines to install and setup the OpenBack Platform within any native smartphone application for the iOS mobile operating system.

Pre-requisites

This document is intended to be used by a developer with existing experience with XCode 7+ and iOS 8+.

Terminology

Library: Collective software components added into the mobile app

Description

The OpenBack Platform is a smart notification platform built on a real-time rules and reporting engine that automatically uses device and other context triggers (e.g., location, device time, other apps install, signal strength etc.) to send notifications and other messages e.g. interactive display messages, offline push notifications, SMS/text messages etc. and then manage and report on those messages in a user centric way, showing messages to users at the right moment.

The library syncs with the OpenBack Dashboard by downloading and storing the campaign context rules and related content locally and efficiently on the device, meaning notifications and messages work even without a data connection. Once the context triggers and other criteria are met, the device then displays the relevant message for the user to interact with. The Dashboard and Android library support over 30 trigger sets, and multiple trigger sets can be used in any of many campaigns - this means there are over 33 million potential trigger combinations.

The library polls data back to the platform as configured on the dashboard, by uploading the data to the OpenBack Engine (OBE) via HTTPS.

Overview of Process

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

Install the OpenBack Library Framework

Adding the OpenBack framework to your project

  1. Add OpenBack.framework to the Embedded Binaries section of your project.


    Embedded Binaries


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

    The script is from Realm and is used to remove x86_x64/i386 architectures when building for the App Store.

Update your project capabilities

Background Modes must be enabled on the project to allow OpenBack to check and run campaigns in the background. It must use at least Background fetch and Remote notifications. 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.

Background Modes

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

Push Notifications


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
  • 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 send the .p12 certificate file with the password (if any) to the OpenBack integrations team (integrations@openback.com).


Using 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:

Objective-C
Swift

 #import<OpenBack/OpenBack.h>


Objective-C

 #import<OpenBack/OpenBack.h>

Swift

import OpenBack

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

Objective-C
Swift

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  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
  } else {
    // Check error code
  }
}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  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
  } else {
    // Check error code
  }
}

Swift

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
} catch let err as NSError {
    print("Failed to setup OpenBack: \(err)")
}



Core configuration parameters

Changing the application ID or server environment will remove all the cached data and a new user will be created.

Setting the Advertising ID is recommended only if the application already uses the Advertising Identifier. Apple requires disclosing the use of the Advertising Identifier when publishing in the App Store. It should be set to [[ASIdentifierManager sharedManager] advertisingIdentifier].


Parameters Description
kOBKConfigAppCode The OpenBack Application Code (App Code) is found in the Dashboard under the App Settings Menu (NSString, Required)
kOBKConfigAdvertisingId The Advertising ID to be tracked (NSString, Optional)
kOBKConfigUseDevServer Use the development or live server (BOOL, Optional, Default:NO)
kOBKConfigUserInfo The extra user information (NSDictionary, Optional)
kOBKConfigLogLevel Set the logging level (OBKLogLevel, Optional, Default:None)
kOBKConfigMinimumBackgroundFetchInterval Set the minimum background fetch interval (NSTimeInterval, Optional, Default: UIApplicationBackgroundFetchIntervalMinimum)

Enable or Disable Features


Feature Description
kOBKConfigEnableAlertNotifications Enable system alert notifications (BOOL, Optional, Default:YES)
kOBKConfigEnableInAppNotifications Enable in-app notifications (BOOL, Optional, Default:YES)
kOBKConfigEnableRemoteNotifications Enable remote notifications (BOOL, Optional, Default:YES)
kOBKConfigEnableProximity Enable device proximity (BOOL, Optional, Default:NO)
kOBKConfigEnableMotionCoprocessor Enable motion coprocessor for activity trigger (BOOL, Optional, Default:NO)
kOBKConfigEnableMicrophone Enable microphone for noise level detection (BOOL, Optional, Default:NO)
kOBKConfigEnableLocation Enable user location (BOOL, Optional, Default:YES)

Permission Authorization Prompts

By default, OpenBack will prompt the user for all the permissions required for all Campaign triggers - it is recommended that this behaviour is disabled and custom permission prompts are used to ensure the best user experience for the app (click here for more details).


Permission Description
kOBKConfigRequestAlertNotificationsAuthorization Let OpenBack prompt the user for system alert notifications authorization (BOOL, Optional, Default:YES)
kOBKConfigRequestMotionCoprocessorAuthorization Let OpenBack prompt the user for motion coprocessor access authorization` (BOOL, Optional, Default:YES)
kOBKConfigRequestMicrophoneAuthorization Let OpenBack prompt the user for microphone authorization (BOOL, Optional, Default:YES)
kOBKConfigRequestLocationAlwaysAuthorization Let OpenBack prompt the user for location always authorization (BOOL, Optional, Default:YES)

Error Codes

OpenBack specific errors use the kOBKErrorDomaindomain, and may help with troubleshooting during setup.

Name Code Description
kOBKErrorAlreadyStarted 1 OpenBack is already running
kOBKErrorAlreadyStopped 2 OpenBack is already stopped
kOBKErrorAlreadySetup 3 OpenBack is already setup / Setup can only be done once
kOBKErrorNotSetup 4 OpenBack is not setup, you must setup OpenBack before using any other functions
kOBKErrorInvalidAppCode 100 Application Code is missing or invalid
kOBKErrorInvalidConfiguration 101 Configuration contains invalid values (see userInfo...)
kOBKErrorInvalidEnvironment 102 Invalid environment (dev or live) for given application
kOBKErrorUnkownCustomTrigger 200 Trying to set an unknown custom trigger
kOBKErrorInvalidCustomTrigger 201 Trying to set an invalid value to the custom trigger (only `NSString` or `NSNumber` supported)
kOBKErrorUnkownCustomLog 202 Trying to set an unknown custom log
kOBKErrorInvalidCustomLog 203 Trying to set an invalid value to the custom log (only `NSString` supported)
kOBKErrorInvalidUserInfo 204 Trying to set an invalid user info
kOBKErrorFatalException 999 Something went really wrong and OpenBack cannot safely recover from it. This should never happen.

Starting OpenBack

After successfully configuring OpenBack, the app must call start: in order for OpenBack to start its runloop. The start time can be deferred, if the framework needs to be configured after some user inputs for example. Once all the required info is available, OpenBack should always be started in the application delegate -application:didFinishLaunchingWithOptions: method.

Objective-C
Swift

if ([OpenBack start:&error]) {
  // OpenBack started successfully
} else {
  // Check error code
}

Objective-C

if ([OpenBack start:&error]) {
  // OpenBack started successfully
} else {
  // Check error code
}

Swift

do {
    try OpenBack.start()
    // OpenBack started successfully
} catch let err as NSError {
    print("Failed to start OpenBack: \(err)")
} 


Setting User Info

User information can be set in the config parameters or at any time using the setUserInfo: functions. Providing a user email or phone number is great if you plan to use intelligent routing from OpenBack.

Objective-C
Swift

NSDictionary *userInfo = @{
  kOBKUserInfoEmailAddress: @"john.snow@stark.com",
  kOBKUserInfoPhoneNumber: @"+3531234567"
}

[OpenBack setUserInfo:userInfo error:&error];

Objective-C

NSDictionary *userInfo = @{
  kOBKUserInfoEmailAddress: @"john.snow@stark.com",
  kOBKUserInfoPhoneNumber: @"+3531234567"
}

[OpenBack setUserInfo:userInfo error:&error];

Swift

let userInfo : [NSObject : AnyObject] = [
  kOBKUserInfoEmailAddress: "john.snow@stark.com",
  kOBKUserInfoPhoneNumber: "+3531234567"
]

do {
  try OpenBack.setUserInfo(userInfo)
} catch let err as NSError {
  print("Failed to set user info: \(err)")
}


List of available user info - all of them take string values:

kOBKUserInfoAddressLine1, kOBKUserInfoAddressLine2, kOBKUserInfoCity, 
kOBKUserInfoState, kOBKUserInfoCountry, kOBKUserInfoCountryCode, kOBKUserInfoPostCode,
kOBKUserInfoFirstName, kOBKUserInfoSurname, kOBKUserInfoTitle, 
kOBKUserInfoAge, kOBKUserInfoDateOfBirth, kOBKUserInfoGender, 
kOBKUserInfoEmailAddress, kOBKUserInfoPhoneNumber, kOBKUserInfoProfession,
kOBKUserInfoOptInUpdates, kOBKUserInfoAdvertisingId,
kOBKUserInfoIdentity1, kOBKUserInfoIdentity2, kOBKUserInfoIdentity3, 
kOBKUserInfoIdentity4, kOBKUserInfoIdentity5

To link your application user ID with the OpenBack user, use the kOBKUserInfoIdentity[1-5] fields.

Modifying the kOBKUserInfoIdentity[1-5] will reset all the user data and stored campaigns!


Setting custom trigger values

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. For example:

Objective-C
Swift

[OpenBack setValue:@"myvalue" forCustomTrigger:kOBKCustomTrigger1 error:&error];
[OpenBack setValue:@(123) forCustomTrigger:kOBKCustomTrigger2 error:&error];

Objective-C

[OpenBack setValue:@"myvalue" forCustomTrigger:kOBKCustomTrigger1 error:&error];
[OpenBack setValue:@(123) forCustomTrigger:kOBKCustomTrigger2 error:&error];

Swift

do {
    try OpenBack.setValue("123", forCustomTrigger: OBKCustomTriggerType.Trigger1)
} catch let err as NSError {
    print("Failed to set custom trigger: \(err)")
}


Further Information

You can find some details on Permissions and Background Modes here.