iOS API

For integrating a previous version of the SDK, click here.

OpenBack iOS SDK version 4+

import OpenBack
  • All fields ands methods are for the OpenBack class.
  • Minimum supported version: iOS 10.

Configuration

@ appCode

Get and set the app code for your application.

Definition
@property (class, nullable) NSString *appCode;
Example
OpenBack.appCode = "YOUR_APP_CODE"
note

Setting the app code using the class property will override the plist configuration. Setting the app code to nil will fallback to the plist configuration if any, otherwise the OpenBack engine will erase all the data and stop. Changing the app code will erase all the OpenBack SDK data.

@ autoStart

Definition
@property (class, getter=isAutoStartEnabled) BOOL autoStart;

Turn on/off the auto-start feature.

Example
OpenBack.autoStart = true
var started = OpenBack.isAutoStartEnabled()
note

Setting the auto-start using the class property will override the plist configuration.

@ gdprForgetUser

Definition
@property (class, getter=isGdprForgetUserSet) BOOL gdprForgetUser;
Example
OpenBack.gdprForgetUser(true)
var isGdprForgetUserSet = OpenBack.isGdprForgetUserSet()

Enable or disable the GDPR forget user flag. 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 compliant, you also need to enable GDPR in your application settings on the OpenBack Dashboard.

@ coppaCompliant

Definition
@property (class, getter=isCoppaCompliant) BOOL coppaCompliant;

Get and set the COPPA compliant flag. If your application has COPPA enabled in the OpenBack Dashboard, you have to set the COPPA compliant user status otherwise only local notifications will be allowed.

Example
OpenBack.isCoppaCompliant(true)
var coppaCompliant = OpenBack.isCoppaCompliant()

@ hipaaCompliant

Definition
@property (class, getter=isHipaaCompliant) BOOL hipaaCompliant;

Get and set the HIPAA compliant flag. If your application has HIPAA enabled in the OpenBack Dashboard, you have to set the HIPAA compliant user status otherwise only local notifications will be allowed.

Example
OpenBack.isHipaaCompliant(true)
var hipaaCompliant = OpenBack.isHipaaCompliant()

Runtime

@ sdkVersion

Definition
@property (class, readonly) NSString *sdkVersion;

Returns the current OpenBack SDK version.

Example
var sdkVersion = OpenBack.sdkVersion()

@ started

Definition
@property (class, readonly, getter=isStarted) BOOL started;

Checks if the OpenBack on-board message campaign manager is started.

Example
OpenBack.isStarted(true)
var started = OpenBack.isStarted()

+ start

Definition
+ (BOOL)start;

Unless you enabled auto-start, you have to call start: in order for OpenBack to start its runloop.

Example
OpenBack.start()

+ stop

Definition
+ (void)stop;

Stops the OpenBack on-board message manager.

Example
OpenBack.stop()

+ resetAll

Definition
+ (void)resetAll;

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
OpenBack.resetAll()

Debug Logs

@ debugLogLevel

Definition
@property (class) OBKLogLevel debugLogLevel;

Set the debug log level. Does no persist on app termination. Default is kOBKLogLevelNone.

note

Setting the debug log level using the class property will override the value from the plist configuration.

Available log levels:

typedef NS_ENUM(NSUInteger, OBKLogLevel) {
kOBKLogLevelNone = 0, kOBKLogLevelError = 1, kOBKLogLevelWarning = 2,
kOBKLogLevelInfo = 3, kOBKLogLevelDebug = 4, kOBKLogLevelVerbose = 5
};

Set the debug logging level.

tip

Make sure you set the level to kOBKLogLevelNone in your release build to avoid leaking information.

Custom Segments

Constants

Definition
enum OBKCustomSegmentType : Int {
case kOBKCustomSegment1 = 0
case kOBKCustomSegment2 = 1
case kOBKCustomSegment3 = 2
case kOBKCustomSegment4 = 3
case kOBKCustomSegment5 = 4
case kOBKCustomSegment6 = 5
case kOBKCustomSegment7 = 6
case kOBKCustomSegment8 = 7
case kOBKCustomSegment9 = 8
case kOBKCustomSegment10 = 9
}

+ setValue:forCustomSegment:

Definition
+ (BOOL)setValue:(nullable id)value forCustomSegment:(OBKCustomSegmentType)segment;

Set a custom segment value. Allowed types: NSString, NSNumber.

Example
OpenBack.setValue("123", for: .segment1)
OpenBack.setValue(123, for: .segment2)
Parameters
valueidThe custom segment value. Setting nil will remove the custom segment.
segmentIndexCustomSegmentIndexThe custom segment index.

+ getCustomSegment:

Definition
+ (nullable id)getCustomSegment:(OBKCustomSegmentType)segment;

Get a custom segment value.

Example
// Get the Object value of custom segment 1
// If value is nil, custom segment 1 is not set
var value = OpenBack.getCustomSegment(.segment1)

+ removeAllCustomSegments

Definition
(void)removeAllCustomSegments;

Remove all the custom segments.

Example
OpenBack.removeAllCustomSegments()

Attributes

These are a set of pre-defined attributes but you are free to use your own.

Definition
extern NSString * const kOBKUserAddressLine1;
extern NSString * const kOBKUserAddressLine2;
extern NSString * const kOBKUserAdvertisingId;
extern NSString * const kOBKUserAge;
extern NSString * const kOBKUserCity;
extern NSString * const kOBKUserCountry;
extern NSString * const kOBKUserCountryCode;
extern NSString * const kOBKUserDateOfBirth;
extern NSString * const kOBKUserEmailAddress;
extern NSString * const kOBKUserFirstName;
extern NSString * const kOBKUserGender;
extern NSString * const kOBKUserOptInUpdates;
extern NSString * const kOBKUserPhoneNumber;
extern NSString * const kOBKUserPostCode;
extern NSString * const kOBKUserProfession;
extern NSString * const kOBKUserState;
extern NSString * const kOBKUserSurname;
extern NSString * const kOBKUserTitle;
extern NSString * const kOBKUserIdentity1;
extern NSString * const kOBKUserIdentity2;
extern NSString * const kOBKUserIdentity3;
extern NSString * const kOBKUserIdentity4;
extern NSString * const kOBKUserIdentity5;

+ setValue:forAttribute:

Definition
+ (void)setValue:(nullable id<NSCoding>)value forAttribute:(NSString *)attribute;

Set an attribute value.

Example
OpenBack.setValue("Bob" as NSCoding, forAttribute: "firstName")
Parameters
valueid\<NSCoding>The attribute object value. Setting nil will remove the attribute.
attributeNSStringThe attribute key.

+ setAttributes

Definition
+ (void)setAttributes:(NSDictionary<NSString *, id<NSCoding>> *)attributes;

Set multiple attributes.

Parameters
attributesNSDictionary<NSString, id<NSCoding>>The attribute map values to add/merge.

+ getAttribute:

Definition
+ (nullable id<NSCoding>)getAttribute:(NSString *)attribute;

Get the attribute for the given key.

Example
// Get the Object value of attribute "name"
// If value is null, attribute "name" is not set
var firstName = OpenBack.getAttribute("firstName")
Parameters
attributeNSStringThe attribute key.

+ getAllAttributes

Definition
+ (nullable NSDictionary<NSString *, id<NSCoding>> *)getAllAttributes;

Get all attributes.

Example
var attributes = OpenBack.getAllAttributes()

+ removeAllAttributes

Definition
+ (void)removeAllAttributes;

Removes all attributes.

Example
OpenBack.removeAllAttributes()

Logging Goals

+ logGoal:step:value:currency:

Definition
+ (void)logGoal:(NSString *)goal step:(NSUInteger)step value:(double)value currency:(NSString * _Nullable)currency;

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

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.

Example
OpenBack.logGoal("test", step:1, value:12.3, "USD")
Parameters
goalNSStringThe achieved goal.
stepNSUIntegerThe goal step number.
valuedoubleThe value associated with the goal step.
currencyNSStringThe currency code (ISO 4217)

Signal Event

Definition
// Default delay value set in the OpenBack Dashboard (-1)
extern const NSTimeInterval kEventDelayMessageDefault;

+ signalEvent:withDelay:

Definition
+ (void)signalEvent:(NSString *)event withDelay:(NSTimeInterval)delay;

Signal an event.

Messages using the event signal that match the event name will be displayed after the given delay (seconds). To use the default delay value set in the OpenBack Dashboard, use kEventDelayMessageDefault. Any non-negative number will override the default value set in the OpenBack Dashboard.

Example
OpenBack.signalEvent("testEvent", withDelay:-1)
Parameters
eventNSStringThe event signal.
delayNSTimeIntervalThe delay to wait before displaying the messages in seconds.

+ cancelEvent:

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

Cancel an event.

Example
OpenBack.cancelEvent("EnergyEmpty")
Parameters
eventNSStringThe event to cancel.
tip

If you already have a class for tracking events, you can also call OpenBack at the same time.

Topics

+ getSubscribedTopics:

Definition
+ (void)getSubscribedTopics:(void (^)(NSArray<NSString *> *topics))completion;

Get the list of subscribed topics.

Example
// Get the list of subscribed topics
OpenBack.getSubscribedTopics { (topics) in
}

+ isSubscribedToTopic:completion:

Definition
+ (void)isSubscribedToTopic:(NSString *)topic completion:(void (^)(BOOL subscribed))completion;

Check if the given topic is part of the current subscribed topics.

Example
// Check if subscribed to a topic
OpenBack.isSubscribed(toTopic: "WRTGHGES") { (subscribed) in
}
Parameters
topicStringThe topic code.

+ subscribeToTopic:completion:

Definition
+ (void)subscribeToTopic:(NSString *)topic completion:(nullable void (^)(NSError * _Nullable error))completion;

Subscribe to a topic.

Example
// Subscribe to a topic
OpenBack.subscribe(toTopic: "WRTGHGES") { (error) in
}
Parameters
topicNSStringThe topic code.

+ subscribeToTopics:completion:

Definition
+ (void)subscribeToTopics:(NSArray<NSString *> *)topics completion:(nullable void (^)(NSError * _Nullable error))completion;

Subscribe to multiple topics.

Example
// Subscribe to multiple topics
OpenBack.subscribe(toTopics: ["WRTGHGES", "HHTTXXVB"]) { (error) in
}
Parameters
topicsNSArray<NSString>The list of topic codes.

+ unsubscribeFromTopic:completion:

Definition
+ (void)unsubscribeFromTopic:(NSString *)topic completion:(nullable void (^)(NSError * _Nullable error))completion;

Unsubscribe from a topic.

Example
// Subscribe to a topic
OpenBack.unsubscribeFromTopic(topic: "WRTGHGES") { (error) in
}
Parameters
topicNSStringThe topic code.

+ unsubscribeFromTopics:completion:

Definition
+ (void)unsubscribeFromTopics:(NSArray<NSString *> *)topics completion:(nullable void (^)(NSError * _Nullable error))completion;

Unsubscribe from multiple topics.

Example
// Unsubscribe from all topics
OpenBack.unsubscribeFromTopics { (error) in
}
Parameters
topicNSArray<NSString>The list of topic codes.

+ unsubscribeFromAllTopics:

Definition
+ (void)unsubscribeFromAllTopics:(nullable void (^)(NSError * _Nullable error))completion;

Unsubscribe from all topics.

Example
// Unsubscribe from a topic
OpenBack.unsubscribeFromAllTopic(topic: "SRHBSRCSG") { (error) in
}

App Inbox

+ getAppInboxMessageCount:

+ (void)getAppInboxMessageCount:(void (^)(NSUInteger messageCount))completion;

Get the total number of inbox messages

+ getAppInboxUnreadMessageCount:

+ (void)getAppInboxUnreadMessageCount:(void (^)(NSUInteger unreadMessageCount))completion;

Get the number of unread inbox messages

+ getAppInboxMessages:

+ (void)getAppInboxMessages:(void (^)(NSArray<OpenBackAppInboxMessage *> *inboxMessages))completion;

Get all the inbox messages

+ getAppInboxReadMessages:

+ (void)getAppInboxReadMessages:(void (^)(NSArray<OpenBackAppInboxMessage *> *inboxMessages))completion;

Get all the read inbox messages

+ getAppInboxUnreadMessages:

+ (void)getAppInboxUnreadMessages:(void (^)(NSArray<OpenBackAppInboxMessage *> *inboxMessages))completion;

Get all the unread inbox messages

+ markAppInboxMessageAsRead:completion:

+ (void)markAppInboxMessageAsRead:(OpenBackAppInboxMessage *)inboxMessage completion:(nullable void (^)(NSError * _Nullable error))completion;

Mark a inbox message as read

Parameters
inboxMessageAppInboxMessageThe app inbox message.

+ markAppInboxMessagesAsRead:completion:

+ (void)markAppInboxMessagesAsRead:(NSArray<OpenBackAppInboxMessage *> *)inboxMessages completion:(nullable void (^)(NSError * _Nullable error))completion;

Mark multiple inbox messages as read

Parameters
inboxMessagesNSArray<AppInboxMessage>The list of app inbox messages.

+ markAllAppInboxMessagesAsRead:

+ (void)markAllAppInboxMessagesAsRead:(nullable void (^)(NSError * _Nullable error))completion;

Mark all the inbox messages as read

+ removeAppInboxMessage:completion:

+ (void)removeAppInboxMessage:(OpenBackAppInboxMessage *)inboxMessage completion:(nullable void (^)(NSError * _Nullable error))completion;

Remove an inbox message

Parameters
inboxMessageAppInboxMessageThe app inbox message.

+ removeAppInboxMessages:completion:

+ (void)removeAppInboxMessages:(NSArray<OpenBackAppInboxMessage *> *)inboxMessages completion:(nullable void (^)(NSError * _Nullable error))completion;

Remove multiple inbox messages

Parameters
inboxMessagesNSArray<AppInboxMessage>The list app inbox messages.

+ removeAllAppInboxMessages:

+ (void)removeAllAppInboxMessages:(nullable void (^)(NSError * _Nullable error))completion;

Remove all the inbox messages

+ executeAppInboxMessage:completion:

+ (void)executeAppInboxMessage:(OpenBackAppInboxMessage *)inboxMessage completion:(nullable void (^)(NSError * _Nullable error))completion;

Execute the inbox message if actionable

Parameters
inboxMessageAppInboxMessageThe app inbox message.

+ setAppInboxDelegate:

+ (void)setAppInboxDelegate:(_Nullable id<OpenBackAppInboxDelegate>)appInboxDelegate;

Set the inbox event delegate

App Inbox Message

@interface OpenBackAppInboxMessage : NSObject
/** Inbox message read status */
@property (nonatomic, readonly, getter=isRead) BOOL read;
/** Inbox message is can open a url, deep-link, image, etc... */
@property (nonatomic, readonly, getter=isActionable) BOOL actionable;
/** Inbox message delivery time (epoch) */
@property (nonatomic, readonly) uint64_t deliveryTime;
/** Inbox message title */
@property (nonatomic, readonly, copy) NSString *title;
/** Inbox message content */
@property (nonatomic, readonly, copy) NSString *content;
/** Inbox message payload */
@property (nonatomic, readonly, copy) NSString *payload;
@end

App Inbox Delegate

@protocol OpenBackAppInboxDelegate <NSObject>
@optional
/** A message was added to the app inbox. */
- (void)appInboxMessageAdded:(OpenBackAppInboxMessage *)inboxMessage;
/** A message was marked as read because its notification was selected. */
- (void)appInboxMessageRead:(OpenBackAppInboxMessage *)inboxMessage;
/** A message has expired and was removed from the inbox. */
- (void)appInboxMessageExpired:(OpenBackAppInboxMessage *)inboxMessage;
/** A message was updated. */
- (void)appInboxMessageUpdated:(OpenBackAppInboxMessage *)inboxMessage;
@end

Developer Tools

+ checkMessagesNow

Definition
+ (void)checkMessagesNow;

Call this function to check if the current messages on the device are ready to be delivered.

Example
OpenBack.checkMessagesNow()

+ reloadMessagesNow

Definition
+ (void)reloadMessagesNow;

Call this function to force the SDK to download messages from the server.

Example
OpenBack.reloadMessagesNow()

+ areMessagesLoaded

Definition
+ (BOOL)areMessagesLoaded;

Call this function to check if messages are loaded.

Example
let loaded = OpenBack.areMessagesLoaded()