Skip to content

Advanced Setup

User Info

Use the User Info object to customize the delivery moment and content of a message.

Standard

User Info - Standard can be used to personalise content within messages.

Class container for the user info.

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

Custom

User Info - Custom can be used to personalize content within messages or to segment/trigger messages for users.

User Info - Custom values 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.

Constants

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 messages (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

Identities

The User Info - Identity 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
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.

Topics

The OpenBack SDK can be used to message users that are subscribed to certain topics. For more information on topics, contact integrations@openback.com

Events

The OpenBack SDK can be used to track events. An event is an action at a particular moment in time for each user, which is then used to target users and personalize content. For more information on events, contact integrations@openback.com

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.

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.

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.

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
    }