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 the 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 braze.xml

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 to 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 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 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.

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 braze.xml:

1
<string translatable="false" name="com_appboy_custom_endpoint">YOUR_CUSTOM_ENDPOINT_OR_CLUSTER</string>

SDK Endpoint configuration via braze.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 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>

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 braze.xml then an error message is logged to the Android logcat.

If required permissions ACCESS_NETWORK_STATE and INTERNET are not declared in the manifest, an error message is logged to the Android logcat.

Multiple API Keys

The most common use case 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 braze.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 braze.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.