Skip to content

App API (SDK) Docs

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

@import OpenBack;
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.

BOOL logged = [OpenBack logGoal:@"test" step:1 value:12.3 error:&error];
do {
    try OpenBack.logGoal("test", step:1, value:12.3)
} catch let err as NSError {
    print("Failed to log goal: \(err)")
}

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:YES];
OpenBack.coppaCompliant(true)

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.

[OpenBack gdprForgetUser:YES error:&error];
do {
    try OpenBack.gdprForgetUser(true)
} catch let err as NSError {
    print("Failed to forget user: \(err)")
}

Available since: 1.7.0

+ isStarted

+ (BOOL)isStarted;

Checks if OpenBack on-board message campaign manager is started

Example:

BOOL started = [OpenBack isStarted];
var started = OpenBack.started()

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:

BOOL success = [OpenBack resetAll:&error];
do {
    try OpenBack.resetAll()
} catch let err as NSError {
    print("Failed to reset all data: \(err)")
}

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:

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

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:

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

[OpenBack setUserInfo:userInfo error:&error];
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)")
}

Available since: 1.0.0

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

if ([OpenBack start:&error]) {
  // OpenBack started successfully
} else {
  // Check error code
}
do {
    try OpenBack.start()
    // OpenBack started successfully
} catch let err as NSError {
    print("Failed to start OpenBack: \(err)")
} 

Available since: 1.0.0

+ stop:

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

Stop the OpenBack on-board message manager

Example:

BOOL stopped = [OpenBack stop:&error];
do {
    try OpenBack.stop()
} catch let err as NSError {
    print("Failed to stop: \(err)")
}

Available since: 1.4.7

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:

[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

Constants

Config Core

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) - see possible levels
kOBKConfigMinimumBackgroundFetchInterval Set the minimum background fetch interval (NSTimeInterval, Optional, Default: UIApplicationBackgroundFetchIntervalMinimum)
kOBKConfigNotificationSound The notification sound file name (NSSString, Optional)

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

Feature Description
kOBKConfigEnableAlertNotifications Enable system alert notifications (BOOL, Optional, Default:YES)
kOBKConfigEnableInAppNotifications Enable in-app notifications (BOOL, Optional, Default:YES)
kOBKConfigEnablePopupNotifications Enable alert popup 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 "always" location (BOOL, Optional, Default:NO)
kOBKConfigEnableLocationWhenInUse Enable user "when in use" location (BOOL, Optional, Default: NO)

Config Permissions

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

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)

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.

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.