iOS Legacy API

This section is dedicated to the various functions available within previous versions of the OpenBack SDK.

import OpenBack

Logging a Goal

To log a goal, first follow the steps on Goal Creation to set up your goal on the dashboard.

+ (BOOL)logGoal:(NSString * _Nonnull)goal step:(NSUInteger)step value:(double)value error:(NSError * _Nullable * _Nullable)error;

At any point, you can log a goal with the step number and value associated with it. Goals are created in the OpenBack Dashboard. You can then associate a message to a goal. When logging a goal, use the goal code.

do {
try OpenBack.logGoal("test", step:1, value:12.3)
} catch let err as NSError {
print("Failed to log goal: \(err)")
}
info

Available since: 1.7.0

Methods

+ coppaCompliant:

+ (void)coppaCompliant:(BOOL)compliant;

If your application needs COPPA to be enabled, set the COPPA compliant status with this function. If COPPA is enabled, messages will not run unless compliant is set to true.

OpenBack.coppaCompliant(true)
info

Available since: 1.7.1

+ gdprForgetUser:error:

+ (BOOL)gdprForgetUser:(BOOL)forgetUser error:(NSError * _Nullable * _Nullable)error;

When your user requests that all the data should be erased, set this value to true. It will inform the OpenBack server to remove all logs for the current user. All future logs will be erased after processing. If you wish to be fully GDPR complient, you also need to enable GDPR in your application settings on the OpenBack Dashboard.

do {
try OpenBack.gdprForgetUser(true)
} catch let err as NSError {
print("Failed to forget user: \(err)")
}
info

Available since: 1.7.0

+ isStarted

+ (BOOL)isStarted;

Checks if OpenBack on-board message campaign manager is started

Example:

var started = OpenBack.isStarted()
info

Available since: 1.4.7

+ resetAll

+ (BOOL)resetAll:(NSError * _Nullable * _Nullable)error;

Call this function to remove all stored OpenBack user data including the cached messages, message counts and username. Use this function when users get individual messages via the API and the user changes (e.g. user logout and login with different account).

Example:

do {
try OpenBack.resetAll()
} catch let err as NSError {
print("Failed to reset all data: \(err)")
}
info

Available since: 1.4.7

+ setupWithConfig:error:

+ (BOOL)setupWithConfig:(nullable NSDictionary *)config
error:(NSError * _Nullable * _Nullable)error;

Configure OpenBack library. The possible configuration keys are listed in Config Core, Config Features and Config Permissions.

Example:

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)")
}
info

Available since: 1.0.0

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

+ setUserInfo:error:

+ (BOOL)setUserInfo:(nullable NSDictionary *)userInfo
error:(NSError * _Nullable * _Nullable)error;

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. See User Info Keys for the possible dictionary keys.

Example:

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)")
}
info

Available since: 1.0.0

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

note

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

+ start:

+ (BOOL)start:(NSError * _Nullable * _Nullable)error;

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.

Example:

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

Available since: 1.0.0

+ stop:

+ (BOOL)stop:(NSError * _Nullable * _Nullable)error;

Stop the OpenBack on-board message manager

Example:

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

Available since: 1.4.7

+ triggerEvent:withDelay:

+ (void)triggerEvent:(NSString * _Nonnull)event withDelay:(NSTimeInterval)delay;

Use this API to trigger an event. If a message matches your event and any other triggers, the message will be displayed after the given delay.

Delay is in seconds. If delay is a non-negative number, it will override the default value is set in the OpenBack Dashboard.

Example:

OpenBack.triggerEvent("MyEvent", withDelay: 10)
info

Available since: 1.9.15

+ cancelEvent:

+ (void)cancelEvent:(NSString * _Nonnull)event;

Use this API to cancel an event. Removes the displayed and scheduled notifications for the message set to use that event.

Example:

OpenBack.cancelEvent("MyEvent")
info

Available since: 1.9.16

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

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

Available since: 1.0.0

User Info Keys

KeyValueDescription
kOBKUserInfoAddressLine1NSStringAddress line 1
kOBKUserInfoAddressLine2NSStringAddress line 2
kOBKUserInfoAdvertisingIdNSStringAdvertising identifier set by the application
kOBKUserInfoAgeNSStringAge
kOBKUserInfoCountryNSStringCountry
kOBKUserInfoCountryCodeNSStringISO-2 country code
kOBKUserInfoStateNSStringState
kOBKUserInfoDateOfBirthNSStringDate of birth YYYY-MM-DD
kOBKUserInfoFirstNameNSStringFirst name
kOBKUserInfoGenderNSStringGender
kOBKUserInfoOptInUpdatesNSStringOpting in for campaign updates "true"/"false"
kOBKUserInfoPostCodeNSStringPostal code
kOBKUserInfoProfessionNSStringProfession
kOBKUserInfoSurnameNSStringSurname
kOBKUserInfoTitleNSStringTitle
kOBKUserInfoCityNSStringCity
kOBKUserInfoEmailAddressNSStringE-Mail address
kOBKUserInfoPhoneNumberNSStringPhone Number
kOBKUserInfoIdentity1NSStringCustom user identifier 1
kOBKUserInfoIdentity2NSStringCustom user identifier 2
kOBKUserInfoIdentity3NSStringCustom user identifier 3
kOBKUserInfoIdentity4NSStringCustom user identifier 4
kOBKUserInfoIdentity5NSStringCustom user identifier 5

Constants

Config Core

ParametersDescription
kOBKConfigAppCodeThe OpenBack Application Code (App Code) is found in the Dashboard under the App Settings Menu (NSString, Required)
kOBKConfigAdvertisingIdThe Advertising ID to be tracked (NSString, Optional)
kOBKConfigUseDevServerUse the development or live server (BOOL, Optional, Default:NO)
kOBKConfigUserInfoThe extra user information (NSDictionary, Optional)
kOBKConfigLogLevelSet the logging level (OBKLogLevel, Optional, Default:None) - see possible levels
kOBKConfigMinimumBackgroundFetchIntervalSet the minimum background fetch interval (NSTimeInterval, Optional, Default: UIApplicationBackgroundFetchIntervalMinimum)
kOBKConfigNotificationSoundThe notification sound file name (NSSString, Optional)
note

Sound file format can be Linear PCM, MA4 (IMA/ADPCM), ¬ĶLaw or aLaw. You can package the audio data in an aiff, wav, or caf file. Sound files must be less than 30 seconds. See UNNotificationSound.

Config Features

FeatureDescription
kOBKConfigEnableAlertNotificationsEnable system alert notifications (BOOL, Optional, Default:YES)
kOBKConfigEnableInAppNotificationsEnable in-app notifications (BOOL, Optional, Default:YES)
kOBKConfigEnablePopupNotificationsEnable alert popup notifications (BOOL, Optional, Default:YES)
kOBKConfigEnableRemoteNotificationsEnable remote notifications (BOOL, Optional, Default:YES)
kOBKConfigEnableProximityEnable device proximity (BOOL, Optional, Default:NO)
kOBKConfigEnableMotionCoprocessorEnable motion coprocessor for activity trigger (BOOL, Optional, Default:NO)
kOBKConfigEnableMicrophoneEnable microphone for noise level detection (BOOL, Optional, Default:NO)
kOBKConfigEnableLocationEnable user "always" location (BOOL, Optional, Default:NO)
kOBKConfigEnableLocationWhenInUseEnable user "when in use" location (BOOL, Optional, Default: NO)

Config Permissions

note

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 (click here for more details).

PermissionDescription
kOBKConfigRequestAlertNotificationsAuthorizationLet OpenBack prompt the user for system alert notifications authorization (BOOL, Optional, Default:YES)
kOBKConfigRequestMotionCoprocessorAuthorizationLet OpenBack prompt the user for motion coprocessor access authorization` (BOOL, Optional, Default:YES)
kOBKConfigRequestMicrophoneAuthorizationLet OpenBack prompt the user for microphone authorization (BOOL, Optional, Default:YES)
kOBKConfigRequestLocationAlwaysAuthorizationLet OpenBack prompt the user for location always authorization (BOOL, Optional, Default:YES)

Debug Log Level

typedef NS_ENUM(NSUInteger, OBKLogLevel) {
kOBKLogLevelNone, kOBKLogLevelError, kOBKLogLevelWarning,
kOBKLogLevelInfo, kOBKLogLevelDebug, kOBKLogLevelVerbose
};
note

In Swift, the enum needs to be converted to an Int

kOBKConfigLogLevel: OBKLogLevel.verbose.rawValue

Error Codes

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

NameCodeDescription
kOBKErrorAlreadyStarted1OpenBack is already running
kOBKErrorAlreadyStopped2OpenBack is already stopped
kOBKErrorAlreadySetup3OpenBack is already setup / Setup can only be done once
kOBKErrorNotSetup4OpenBack is not setup, you must setup OpenBack before using any other functions
kOBKErrorInvalidAppCode100Application Code is missing or invalid
kOBKErrorInvalidConfiguration101Configuration contains invalid values (see userInfo...)
kOBKErrorInvalidEnvironment102Invalid environment (dev or live) for given application
kOBKErrorUnkownCustomTrigger200Trying to set an unknown custom trigger
kOBKErrorInvalidCustomTrigger201Trying to set an invalid value to the custom trigger (only NSString or NSNumber supported)
kOBKErrorUnkownCustomLog202Trying to set an unknown custom log
kOBKErrorInvalidCustomLog203Trying to set an invalid value to the custom log (only NSString supported)
kOBKErrorInvalidUserInfo204Trying to set an invalid user info
kOBKErrorFatalException999Something went really wrong and OpenBack cannot safely recover from it. This should never happen.

Optional Permissions

The messages may use a variety of message triggers and some require permission from the user. It is important to understand how permissions work and their impact on the OpenBack platform. When OpenBack is installed in an application, OpenBack swizzle a few methods of the application delegate to handle system events in order to run the message checks. The more often the application runs, the more often the message triggers are checked.

note

The Activity trigger works using either location updates or motion coprocessor. If only location is used, activity will be calculated from a sample of speed data and unless you enable Location updates in the Background Modes, activity will not be available in the background.

Local Notifications Permission

Required to display notifications when the application is in the background.

It is likely that the majority of messages are triggered while your application is in the backbround. It is therefore very important to get the user's permission to display Alert Notifications. When the application is active, OpenBack can also deduce the current activity (still, walking...) from the location samples.

Location Permission

Required for Location Trigger, Beacon Trigger, and Activity Trigger unless the application enables Motion Coprocessor Permission.

If messages using user location will be used, the Always location permission needs to be enabled. It allows OpenBack to handle significant location changes that can be used to wake up the application in the background even after it was swipe closed (force kill). If a user swipe closes the application and doesn't go anywhere far enough to trigger a significant location change, the application will not re-start and OpenBack will not be able to check the messages. Traditional dumb push notifications aren't ever received after a force kill.

note

When using significant location change, iOS will likely display an alert after a few days to inform users that your application has been using location in the background.

![URL Schemes][locationbg]

Access Wifi Information Permission

Required for Connectivity Trigger as of iOS12. Find more information in the Apple docs here.

Wifi Access

Motion Coprocessor Permission

Required for Activity Trigger unless the application enabled Location Permission

For the activity trigger, OpenBack can use either location or motion coprocessor. The motion coprocessor is more accurate but requires another user permission. You will need to balance the permissions versus the messages you intend to run and the desired accuracy of the data.

Microphone Permission

Required for Noise Trigger messages.

It works by analyzing recording samples on the fly but none of the data is stored anywhere (going to /dev/null). Asking for the microphone permission may cause users to question the need for it, so OpenBack only recommends using this trigger for specific and useful scenarios for the user. Typically, unless the application already uses the micophone, we don't recommend you use noise trigger on iOS.

Background Modes

Location Updates

If very precise location triggers are required for messages when the application is in the background, select Location Updates in Background Modes. Although significant location changes are usually sufficient, extra accuracy may be required. It should be explained to users why background location in the App Description when submitting your applications in Itunes Connect - Apple recommends the following statement in the App description - "Continued use of GPS running in the background can dramatically decrease battery life." and may reject the app during review if it is not included and location updates are setup.

Background Fetch

There is no visual permission request to users to allow background fetch but users can turn it off in the application settings. When selected, the system will wake up the application once in a while to go fetch new data. It allows OpenBack to run a little more often when in the background and also cehck for updated messages.

Remote Notifications

The message campaign manager uses silent push notifications to inform the OpenBack SDK that an update is available. For example, when a new messages is added or updated, OpenBack sends a silent push so the OpenBack SDK fetchs new messages or when a timed message needs to be triggered more precisely. Thankfully these silent push notifications do not require any user permissions but similar to dumb push notifications, only works when the application is either in the foreground or the background. Once the user force close the application, a silent push is not received.

Audio

If the Noise trigger is going to be used when your application is in the background, select Audio and AirPlay in Background Modes. Unless the application already has this for background audio recording.

Reading Data From Notifications

Make sure everything is setup correctly:

  1. Have LSApplicationQueriesSchemes array with your own scheme as part of the list.
  2. Have a URL type with your scheme declared.

Example:

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
print(url)
return true
}