Migrating to iOS V4

This migration guide is for users that are moving from OpenBack's iOS SDK V1 to <=V4.0.0. You can update to the latest version of OpenBack with the code below.

pod update OpenBack

After updating, the steps for migrating are as follows:

  • Remove the openback.json file and switch to our latest plist configuration.
  • Use the latest API calls from V4.
  • Add in the background modes for iOS 13+.

1 - plist Configuration

  • Remove the openback.json as this is no longer needed in V4.
  • You can now configure OpenBack in your application Info.plist using the OpenBack dictionary or in its own plist file named OpenBack.plist.
<plist version="1.0">
<dict>
...
<key>OpenBack</key>
<dict>
<key>AppCode</key>
<string>YOUR_APP_CODE</string>
<key>AppGroup</key>
<string>group.YOUR_APP_GROUP</string>
<key>DebugLogLevel</key>
<integer>5</integer>
<key>EnableAutoStart</key>
<true/>
<key>EnableProximity</key>
<false/>
<key>EnableSwizzle</key>
<true/>
<key>NotificationSound</key>
<string>ding.m4r</string>
</dict>
...
</dict>
</plist>

Available configuration keys:

KeyTypeDefaultDescription
AppCodestring-The OpenBack app code for your application
AppGroupstring-The app group used for OpenBack and notification app extenstions
DebugLevel1integer0The debug log level - see debug levels
EnableAutoStart2booleantrueControls if OpenBack starts automatically
ClearBadgeCount5booleanfalseControls if OpenBack clears the badge number when app is opened (only if badge is enabled)
EnableCoreMotionActivitybooleanfalseControls if library can use Core Motion Activity manager.
EnableMicrophonebooleanfalseControls if OpenBack can use the microphone (noise trigger)
EnableProximity3booleanfalseControls if OpenBack can use the proximity sensor (proximity trigger)
EnableSwizzle4booleantrueControls if swizzle is enabled
LargeIconstring-Default large icon for notification (filename in main bundle or image asset name)
NotificationSoundstring-Set the default notification sound (filename in main bundle)
  • [1]: Using the debug level in the plist during development can be useful to get startup logs that might occur before you have a chance to call the API.
  • [2]: If you disable auto-start, you will need to manually call `+ start:` in your application.
  • [3]: Enabling proximity on iOS has the side effect of turning the screen off when the device is close to the face.
  • [4]: If you disable delegate swizzling, you will need to manually call OpenBack functions. See below for more details.
  • [5]: If you enable clearing the badge count on app launch, the SDK will set the badge count to 0 but keep the notifications in the notification center. This is done by setting the `applicationIconBadgeNumber` to -1. Setting a value of 0 would have the side effect of removing all the delivered notifications.

Alternatively, if you do not provide an App Code in the plist, you can set it manually using the API.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
OpenBack.appCode = "YOUR_APP_CODE"
OpenBack.start()
return true
}

2 - Update Your API Calls

The iOS SDK API has been updated to match the naming scheme of our Android API for ease of use across both platforms. Our iOS API calls no longer return errors as the errors are now logged in the console. The following API calls have been changed in V4:

Config

warning

You no longer need to call the OpenBack Config as the configuration is completed in the plist.

3 - Project Configuration

Frameworks

In line with Apple's specifications, the OpenBack iOS V4 SDK has been split into several different modules depending on the required permissions. See below for the list of which modules you will need to include for certain signals:

iOS13+ Background Modes

Check Background fetch, Background processing and Remote notifications.

BackgroundModes

When background processing is enabled, add the following two permitted tasks to the Info.plist:

<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
<string>com.openback.bgtask.refresh</string>
<string>com.openback.bgtask.check</string>
</array>

You're now ready to use V4 of the OpenBack SDK, see our full API documentation here or look at some of our other features below.

FeatureOverview
Signals & PermissionsAdd the required settings and permissions in your project settings for signals.
AttributesAttribute values can be set client side by your mobile app, and then used as personalized content within messages.
Custom SegmentsCustom Segments are set client side by your mobile app. They can be used to deliver a message based on the value set in your message campaign which is managed through the OpenBack Dashboard or Client APIs.
GoalsGoals can range from anything such as a user completing a signup process, to a user purchasing a product.
EventsAn event is an action at a particular moment in time for each user, which can then be used to deliver a notification. You can easily pass existing or new events to the OpenBack SDK client side, making advanced campaigns simple.
App InboxDeliver & manage messages in an inbox within your app – standalone, or as part of a notification.
TopicsMessage users that are subscribed to specific topics.
Advanced ConfigurationAdvanced OpenBack configuration parameters.
NotificationsCustomize the appearance of OpenBack notifications.