This section is dedicated to the integration guide for previous versions of the OpenBack SDK.
OpenBack is a fast and easy integration for Android apps and should take less than 15 minutes for each app and involves:
- Add 2 lines to your Gradle files
- Add a JSON file for configuring OpenBack
- Update the manifest file
- Paste 2 lines of code into the app
The SDK, which is an AAR file, is a tiny 230 KB.
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 integrations team if you would like a simple template to document and agree these.
1 - Gradle Integration
Add OpenBack maven repository to your application build.gradle
Add OpenBack library to your application dependencies
Use the 2.+ format to make sure the latest library is picked up. OpenBack is compiled with Google Play Services version 11.8.0 to support a wider range of devices but you can use a later version if you prefer.
Starting with 2.4.0, Google Play Services are compileOnly dependencies. It allows you to control the packages you want to use and reduce your application methods/fields count. Make sure to add the packages required for the triggers you plan to use (see below), and for the preferred push service (Firebase).
If you are using Android Studio 3.0 or 3.1, you might have to disable Instant Run. There is an issue, known to Google, with Instant Run and compileOnly dependencies in external libraries.
2 - Setting Configuration File
Add a configuration file named openback.json to the application
assets folder. If the application doesn't have an assets folder, simply select the application module, right click and select File > New > Folder > Assets Folder
notification parameter is used to customize the notification icon. It is important to set the material icon for devices using Android 5 and above, otherwise the displayed icon may look like a colored square. For more information, please refer to this page.
You can also customize the light, vibrations, and sound if you like:
- icon: Small notification icon for pre Android 5. Resource
- icon_material: Small notification icon for Android 5+. Resource
coloris the background color.
- bigIcon: Large icon displayed in notification. Resource
lightis the flashing led color,
onMsis the flashing led ON time in ms,
offMsis the flashing led OFF time in ms
patternis an array of ON/OFF vibration in ms
- sound: resource
When providing a sound resource, make sure it is in your application resources. Otherwise notifications will not make noise.
3 - Editing the Application Android Manifest
We recommend that you add all normal permissions that you are comfortable with and only add user prompted permissions if necessary. For a full list of Android permissions, go to the Optional Features page.
4 - Firebase/FCM Settings
As of April 2018, Google has officially deprecated GCM. We highly recommend you use Firebase instead. Find out more about the deprecation here.
To find your Firebase Cloud Messaging key, go to the Firebase console here. Go to your project settings page by clicking the cog wheel in the top left of the page and select
Project Settings. Your Firebase key is in the Cloud Messaging tab. We recommend that you use the Server key but the Legacy server key will also work.
While campaigns/messages are synced with each user as per the settings in the Dashboard, to ensure instant delivery messages, immediately syncing new campaigns to users and using Intelligent Routing features or Instant Campaign Updates you need to setup Firebase Cloud Messaging - FCM. This in no way interferes with any existing FCM implementation or other analytics or push notification services.
After setting FCM for your application, a configuration file named
google-services.json will be generated for the application. Put that configuration file in the /app folder.
For FCM, configuration file is available here.
Select your project -> Settings (Gear) Button -> Project Settings -> google-services.json button
Add the following at the end of the application
Add the Firebase library dependency in your gradle file:
Add the following to the manifest in the application section:
If your application already handles Firebase events with a custom class:
<service android:name="com.openback.OpenBackFcmMessagingService">from the manifest
Call the OpenBack Firebase handler first:
We recommend setting a priority for your custom class in the manifest as shown below.
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.
5 - Initializing the OpenBack SDK
Note the OpenBack App Code for your application. The unique
App Code is displayed in the Dashboard and can be found here. You will need it when configuring the library.
Add the following line to each file that references OpenBack library
Initialise OpenBack library class on the main thread by overriding the “onCreate” function in the Application class of the project with the following:
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.
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.
Configuring the OpenBack Library
The AndroidManifest.xml in OpenBack already contains the required set of Permissions, Services and Receivers. Gradle will merge it into the application manifest. For more information on manifest merge, check the following link. If you have any difficulties with the process, email email@example.com for a quick response or message the live chat below.
It is recommended to include the device features (even if they are implied in most cases) to be fully compliant with the Play Store. Visit this page for more information.
For adding more features such as User Info and Goals, check out the SDK API page.