This section is dedicated to the integration guide for previous versions of the OpenBack SDK.
OpenBack is a fast and easy integration for iOS apps and should take less than 15 minutes for each app.
- Include framework in the project
- Copy sample configuration code
- Configure your project capabilities
- Setup APNs certificates
The iOS SDK, which is a framework, is about 240 KB (after compression and for a specific device).
A sample application is available on Github here.
Often a cross team discussion before integration will help confirm what Custom Triggers, what Goals should be setup during OpenBack SDK integration. Contact the Onboarding team if you would like a simple template to document and agree these.
Step by Step Integration
1- Adding the OpenBack SDK
Although it is prefered to use Cocoapods or Carthage to keep the library updated, if you need to integrate OpenBack manually, add OpenBack.framework to the
Embedded Binaries section of your project.
Updating the OpenBack SDK
For updating the OpenBack SDK with Cocoapods or Carthage, use the commands below.
This step is optional if you are using the latest Cocoapods (1.4+) which already includes a fat binary stripping code.
OpenBack framework comes with multiple architectures, including ones needed for the simulator. When deploying your app to the App Store, the x86_x64/i386 architectures must be removed.
Add a Run Script in your project build phase and copy the following code:
This script comes originally from Realm. If you already are using a tool to strip unused architectures, you can skip this one.
2 - Update Your Project Capabilities
Enable Background Modes.
Check Background fetch and Remote notifications.
Background fetch is a common permission that does not prompt a user for access but can be turned off by a user in their settings,
Enabling background modes allows OpenBack to check and run messages in the background. If the "Noise" trigger is to be used in the background,
Audio and Airplay needs to be checked. Similarly, if a highly accurate or precise Location trigger is required for messages, check
Location updates. See Permissions for more info.
Push Notifications should be also enabled. See the Setup APNs Certificates for Push Notifications for more info.
3 - Configuring pList
OpenBack is a single version SDK built with optional features that can link to frameworks like
CoreBluetooth.framework, etc. in iOS. Apple now require the application to have a usage description for each of these linked frameworks (from iOS10 onwards may require them), even if they are not used or enabled in your app or OpenBack configuration. As such, please include the following usage description strings, even if they are never displayed to the user - suggested text for you to edit is shared here also:
NSMotionUsageDescription- ">YOUR_APP< may use motion detection to improve your app experience" - OpenBack Activity Trigger
NSMicrophoneUsageDescription- ">YOUR_APP< uses the microphone as part of the mobile app experience" – OpenBack Noise Trigger
NSLocationAlwaysUsageDescription- ">YOUR_APP< uses your location for app features and to improve your experience" – OpenBack Exact Location Trigger
NSLocationWhenInUseUsageDescription- ">YOUR_APP< uses your location for app features and to improve your experience” - OpenBack Exact Location Trigger
NSLocationAlwaysAndWhenInUseUsageDescription- ">YOUR_APP< uses your location for app features and to improve your experience” - OpenBack Exact Location Trigger
NSBluetoothPeripheralUsageDescription- ">YOUR_APP< uses your Bluetooth information to improve your app experience" Required if targeting iOS12 and below, deprecated from iOS13 but can be left in regardless - Bluetooth Trigger
NSBluetoothAlwaysUsageDescription- ">YOUR_APP< uses your Bluetooth information to improve your app experience" - Bluetooth Trigger
4 - Configuring Notifications
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, by adding
kOBKConfigRequestAlertNotificationsAuthorization: @(NO) to your config.
|kOBKConfigRequestAlertNotificationsAuthorization||Let OpenBack prompt the user for system alert notifications authorization (BOOL, Optional, Default:YES)|
A good guide for creating custom permission prompts and the best method for asking users to allow push notifications can be found here.
The Apple developer docs on asking for notification permissions can be found here.
5 - Setup APNs Certificates for Push Notifications
In the background, OpenBack uses silent Push Notifications to update messages and ensure triggers are checked regularly. As such, OpenBack requires a valid certificate from your Apple Developer Account to be uploaded into the OpenBack Dashboard.
If Push Notifications are used already, OpenBack recommends creating a specific certificate for the OpenBack library, but this isn’t required. iOS applications can have multiple APNs certificates and this additional OpenBack certificate does not interfere with any existing certificates or services in any way.
Please note APNs Certificates expire – once expired you must create a new certificate in your Apple Developer Account and upload it into the OpenBack Dashboard.
Follow the APNs Certificates Guide to create a Push Notification certificate, then upload the
.p12 certificate file on the OpenBack Dashboard under App Settings for the relevant app, as shown below.
When exporting your
.p12, make sure it only contains a single production push certificate. Use production certificates even for development apps.
Add the APNs certificate to the application details in the OpenBack Dashboard:
We usually allow 15 - 30 minutes for the device to register its push token with APNs/Firebase and for our backend system to sync up.
6 - Initializing the OpenBack SDK
App Code found in the Dashboard. You will need it when configuring the library.
Include the following header:
Configure OpenBack in the application delegate
For example, a typical configuration would look like this:
The configuration parameters can also be passed using in a file named
OpenBackConfig.plist. Starting with 1.7.3, the configuration can also be done in the application
Info.plist. In either case,
setupWithConfig still needs to be called before
start but can be passed an empty dictionary or local overrides.
If your app requires a user to login, make sure to start the OpenBack SDK when they login and similarly, stop the OpenBack SDK if they logout.
If you have any difficulties with the integration process, email firstname.lastname@example.org for a quick response or message the live chat below.
Verifying the OpenBack Integration
When you have completed the basic integration of the OpenBack SDK, running your app will register your device as a user to the OpenBack Engine. You can verify that this is working properly and that you're ready to send messages by going to the
Developer Tab in your App Settings and checking that your device has registered.