Initial SDK Setup
Installing the Braze SDK will provide you with basic analytics functionality as well as working in-app messages with which you can engage your users.
Android SDK Integration
Step 1: Integrate the Braze Library
The Braze Android SDK can optionally be integrated without UI components. However, Content Cards, News Feed, and In-App Messaging will be rendered inoperable unless you pass the custom data to a UI solely of your design. Additionally, push notifications will not work because our push handling code is in the UI library. Please note that these UI elements are open source and fully customizable. We strongly recommend integration of these features. Please refer to Braze Docs for the benefits of using the Braze Content Cards, News Feed, and In-App Message UI.
Basic Integration
In order to access Braze’s messaging features, you must integrate the UI library. Please see the following directions to integrate the UI library depending on your IDE:
Using Android Studio
Step 1: Add our repository
In your top-level project build.gradle
, add:
1
2
maven { url "https://appboy.github.io/appboy-android-sdk/sdk" }
maven { url "https://maven.google.com" }
as repositories under allprojects
-> repositories
.
For example:
1
2
3
4
5
6
7
allprojects {
repositories {
jcenter()
maven { url "https://appboy.github.io/appboy-android-sdk/sdk" }
maven { url "https://maven.google.com" }
}
}
Alternatively, you may install the android-sdk-ui
as an AAR file to your local maven repository. See the SDK Readme for details.
See the Android Support Library Setup instructions for more information on the google maven repository.
Step 2: Add Braze dependency
See the following example in our Hello Appboy example project:
The below example shows where to place the dependency line in your build.gradle
. Note that the version used in the example below uses an old version. Please visit Braze Android SDK Releases for the most up to date version of the Braze Android SDK.
Step 3: Perform Gradle Sync
Be sure to perform a Gradle Sync to build your project and incorporate the dependency additions noted above.
Step 2: Configure the Braze SDK in appboy.xml
Now that the libraries have been integrated, you have to create an appboy.xml
file in your project’s res/values
folder. If you have a custom endpoint or are on a specific data cluster, you need specify the endpoint in your appboy.xml
file as well. The contents of that file should resemble the following code snippet:
Be sure to substitute the API key found within the App Settings page of the Braze dashboard for
REPLACE_WITH_YOUR_API_KEY
. To find out your specific cluster or custom endpoint, please ask your Customer Success Manager or email open a support ticket.
1
2
3
4
5
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="com_appboy_api_key">REPLACE_WITH_YOUR_API_KEY</string>
<string translatable="false" name="com_appboy_custom_endpoint">YOUR_CUSTOM_ENDPOINT_OR_CLUSTER</string>
</resources>
Step 3: Add Required Permissions to Android Manifest
Now that you’ve added your API key, you need to add the following permissions to your AndroidManifest.xml
:
1
2
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
With the release of Android M, Android switched from an install-time to a runtime permissions model. However, both of these permissions are normal permissions and are granted automatically if listed in the app manifest. For more information, visit Android’s permission documentation.
Implementation Example
See the appboy.xml
in the Droidboy sample app for an implementation example.
Step 4: Tracking User Sessions in Android
Activity Lifecycle Callback Integration (API 14+)
This feature is supported on API 14 and above. Calls to openSession()
, closeSession()
,ensureSubscribedToInAppMessageEvents()
, and InAppMessageManager
registration are optionally handled automatically. See the HelloBraze sample application for a full example.
Instructions
Add the following code to the onCreate()
method of your Application class:
1
registerActivityLifecycleCallbacks(new AppboyLifecycleCallbackListener());
You may refer to the following example inside Hello Appboy:
The first argument instructs the listener to handle openSession()
and closeSession()
calls.
The second argument instructs the listener to handle registerInAppMessageManager()
and unregisterInAppMessageManager()
calls.
See the javadoc for more information. Please note that any non-standard manual session integration is not fully supported.
Step 5: Custom Endpoint Setup
Your Braze representative should have already advised you of the correct endpoint.
To update the default endpoint in your integration of the Braze SDKs please add the following code to your appboy.xml
:
1
<string translatable="false" name="com_appboy_custom_endpoint">YOUR_CUSTOM_ENDPOINT_OR_CLUSTER</string>
SDK Endpoint configuration via appboy.xml
is available starting with Braze Android SDK v2.1.1.
Step 6: Enable Location Tracking
If you would like to enable Braze location collection, update your appboy.xml
file to include com_appboy_enable_location_collection
and ensure its value is set to true
.
1
<bool name="com_appboy_enable_location_collection">true</bool>
Starting with Braze Android SDK version 3.6.0 Braze location collection is disabled by default.
SDK Integration Complete
Braze will now be able to collect specified data from your application and your basic integration should be complete.
Please see the following sections in order to enable custom event tracking, push messaging, the news feed and the complete suite of Braze features.
Test Your Basic Integration
Confirm Session Tracking Is Working
At this point you should have session tracking working in your Braze integration. To test this, go to the App Usage
section of your dashboard, select your application from the select box (defaulted to All Apps
), and set Display Data For
to be Today
. Then open your app and refresh the page - your main metrics should all have increased by 1.
You should continue to test your integration by navigating through your application and ensuring that only one session has been logged. Then, background the app for at least 10 seconds and bring it to the foreground again - by default a new session is created if the app is foregrounded after more than 10 seconds not in the foreground (backgrounded or closed). Once you’ve done this, confirm that another session was logged.
Debugging Session Tracking
If session tracking is behaving unexpectedly, turn on Verbose Logging and observe your app while you reproduce session triggering steps. Observe Braze statements in the logcat to detect where you may have missed logging openSession
and closeSession
calls in your activities.
Confirm Device Data is Collected
At this point you should also have default device data collection working in your app. To observe this working correctly navigate to the Devices & Carriers
section of your dashboard, select your application from the select box (defaulted to All Apps
), and set Display Data For
to be Today
.
Additional Customization and Configuration
Using Proguard with Braze
Proguard configuration is automatically included with your Braze integration.
Client apps that Proguard Braze code must store release mapping files for Braze to interpret stack traces. If you would like to continue to keep all Braze code, add the following to your Proguard configuration:
1
2
-keep class bo.app.** { *; }
-keep class com.appboy.** { *; }
If you are integrating Baidu Cloud Push with Braze, add:
1
2
-dontwarn com.baidu.**
-keep class com.baidu.** { *; }
Braze Log Level
The default Log Level for the Braze Android SDK is INFO
. This level includes push payload logs and basic Braze server communication logs.
To change the Braze Log Level, call AppboyLogger.setLogLevel()
with one of the android.util.Log
priority constants or AppboyLogger.SUPPRESS
. For example:
1
2
3
4
5
// Change log level to VERBOSE
AppboyLogger.setLogLevel(Log.VERBOSE);
// Suppress logs
AppboyLogger.setLogLevel(AppboyLogger.SUPPRESS);
Verbose Logging
When debugging Braze behavior, set the Log level to Verbose
before your first call to Braze, preferably in your Application.onCreate()
. This Log level contains every log made by the Braze SDK. This is only intended to be used in development environments and should not be set in a released application.
If the Braze API Key from the “App Settings” page is not present in
appboy.xml
then an error message is logged to the Android logcat.
If required permissions
ACCESS_NETWORK_STATE
andINTERNET
are not declared in the manifest, an error message is logged to the Android logcat.
Multiple API Keys
The most common usecase for multiple API keys is separating API keys for debug and release build variants.
To easily switch between multiple API keys in your builds, we recommend creating a separate appboy.xml
file for each relevant build variant. A build variant is a combination of build type and product flavor. Note that by default, a new Android project is configured with debug
and release
build types and no product flavors.
For each relevant build variant, create a new appboy.xml
for it in src/<build variant name>/res/values/
:
1
2
3
4
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="com_appboy_api_key">REPLACE_WITH_YOUR_BUILD_VARIANT_API_KEY</string>
</resources>
When the build variant is compiled, it will use the new API key.