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.
For apps targeting Android 11 (API 30) be sure to view our Android 11 Support article
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
Add Our Repository
In your top-level project build.gradle
, add the following as repositories under allprojects
-> repositories
.
For example:
1
2
3
4
5
6
allprojects {
repositories {
google()
maven { url "https://appboy.github.io/appboy-android-sdk/sdk" }
}
}
The Braze Android SDK uses AndroidX Jetpack dependencies as of SDK version 10.0.0.
Alternatively, you can directly find the artifact AAR files on our maven repository.
Add Braze Dependency
Add the android-sdk-ui
dependency to your app’s build.gradle
:
1
2
3
dependencies {
implementation "com.appboy:android-sdk-ui:+"
}
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.
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 braze.xml
Note that as of December 2019, custom endpoints are no longer given out, if you have a pre-existing custom endpoint, you may continue to use it. For a list of our available endpoints, click here.
Now that the libraries have been integrated, you have to create an braze.xml
file in your project’s res/values
folder. If you are on a specific data cluster or have a pre-existing custom endpoint, you need specify the endpoint in your braze.xml
file as well. The contents of that file should resemble the following code snippet:
Be sure to substitute your App Identifier API Key found within the App Settings page of the Braze dashboard for
YOUR_APP_IDENTIFIER_API_KEY
. To find out your specific cluster or endpoint, please ask your Customer Success Manager or open a support ticket.
1
2
3
4
5
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="com_appboy_api_key">YOU_APP_IDENTIFIER_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.
Step 4: Tracking User Sessions in Android
Activity Lifecycle Callback Integration
Calls to openSession()
, closeSession()
,ensureSubscribedToInAppMessageEvents()
, and InAppMessageManager
registration are optionally handled automatically.
Instructions
Add the following code to the onCreate()
method of your Application class:
1
2
3
4
5
6
7
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
registerActivityLifecycleCallbacks(new AppboyLifecycleCallbackListener(sessionHandlingEnabled, inAppMessagingRegistrationEnabled));
}
}
1
2
3
4
5
6
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
registerActivityLifecycleCallbacks(AppboyLifecycleCallbackListener(sessionHandlingEnabled, inAppMessagingRegistrationEnabled))
}
}
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
Note that as of December 2019, custom endpoints are no longer given out, if you have a pre-existing custom endpoint, you may continue to use it. For a list of our available endpoints, click here.
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 braze.xml
:
1
<string translatable="false" name="com_appboy_custom_endpoint">YOUR_CUSTOM_ENDPOINT_OR_CLUSTER</string>
Step 6: Enable Location Tracking
If you would like to enable Braze location collection, update your braze.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.