Integrating the Braze Android SDK

Learn how to integrate the Braze Android SDK. To learn more about the SDK in general, see Getting started: Integration overview.

Integrating the SDK

Step 1: Configure braze.xml

Create a 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. Make sure to substitute YOUR_APP_IDENTIFIER_API_KEY with the identifier found in the Manage Settings page of the Braze dashboard. Log in at dashboard.braze.com to find your cluster address.

1
2
3
4
5
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="com_braze_api_key">YOUR_APP_IDENTIFIER_API_KEY</string>
<string translatable="false" name="com_braze_custom_endpoint">YOUR_CUSTOM_ENDPOINT_OR_CLUSTER</string>
</resources>

Step 2: Add permissions to AndroidManifest.xml

Next, 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" />

Step 3: Enable user session tracking

Calls to openSession(), closeSession(),ensureSubscribedToInAppMessageEvents(), and InAppMessageManager registration are optionally handled automatically.

To register activity lifecycle callbacks, add the following code to the onCreate() method of your Application class:

• java
• kotlin

1
2
3
4
5
6
7
public class MyApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    registerActivityLifecycleCallbacks(new BrazeActivityLifecycleCallbackListener());
  }
}

1
2
3
4
5
6
class MyApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    registerActivityLifecycleCallbacks(BrazeActivityLifecycleCallbackListener())
  }
}

See our SDK reference documentation for more information on the parameters available for BrazeActivityLifecycleCallbackListener.

Step 4: Enable location tracking

To enable Braze location collection, update your braze.xml file to include com_braze_enable_location_collection and ensure its value is set to true:

1
<bool name="com_braze_enable_location_collection">true</bool>

Step 5: Test session tracking (optional)

If you experience issues while testing, enable verbose logging, then use logcat to detect missing openSession and closeSession calls in your activities.

1. In Braze, go to Overview, select your app, then in the Display Data For dropdown choose Today.
2. Open your app, then refresh the Braze dashboard. Verify that your metrics have increased by 1.
3. Navigate through your app and verify that only one session has been logged to Braze.
4. Send the app to the background for at least 10 seconds, then bring it to the foreground. Verify that a new session was logged.

Optional configurations

Google Advertising ID

The Google Advertising ID (GAID) is an optional user-specific, anonymous, unique, and resettable ID for advertising, provided by Google Play services. GAID gives users the power to reset their identifier, opt-out of interest-based ads within Google Play apps, and provides developers with a simple, standard system to continue to monetize their apps.

The Google Advertising ID is not automatically collected by the Braze SDK and must be set manually via the Braze.setGoogleAdvertisingId() method.

• java
• kotlin

1
2
3
4
5
6
7
8
9
10
11
new Thread(new Runnable() {
  @Override
  public void run() {
    try {
      AdvertisingIdClient.Info idInfo = AdvertisingIdClient.getAdvertisingIdInfo(getApplicationContext());
      Braze.getInstance(getApplicationContext()).setGoogleAdvertisingId(idInfo.getId(), idInfo.isLimitAdTrackingEnabled());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}).start();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
suspend fun fetchAndSetAdvertisingId(
  context: Context,
  scope: CoroutineScope = GlobalScope
) {
  scope.launch(Dispatchers.IO) {
    try {
      val idInfo = AdvertisingIdClient.getAdvertisingIdInfo(context)
      Braze.getInstance(context).setGoogleAdvertisingId(
        idInfo.id,
        idInfo.isLimitAdTrackingEnabled
      )
    } catch (e: Exception) {
      e.printStackTrace()
    }
  }
}

Logging

By default, the Braze Android SDK log level is set to INFO. You can suppress these logs or set a different log level, such as VERBOSE, DEBUG, or WARN.

Enabling logs

To help troubleshoot issues in your app, or reduce turnaround times with Braze Support, you’ll want to enable verbose logs for the SDK. When you send verbose logs to Braze Support, ensure they begin as soon as you launch your application and end far after your issue occurs.

Keep in mind, verbose logs are only intended for your development environment, so you’ll want to disable them before releasing your app.

• application
• xml

1
BrazeLogger.setLogLevel(Log.MIN_LOG_LEVEL);

1
BrazeLogger.logLevel = Log.MIN_LOG_LEVEL

1
BrazeLogger.setLogLevel(Log.VERBOSE);

1
BrazeLogger.logLevel = Log.VERBOSE

1
<integer name="com_braze_logger_initial_log_level">MIN_LOG_LEVEL</integer>

1
<integer name="com_braze_logger_initial_log_level">2</integer>

Verifying verbose logs

To verify that your logs are set to VERBOSE, check if V/Braze occurs somewhere in your logs. If it does, then verbose logs have been successfully enabled. For example:

1
2077-11-19 16:22:49.591 ? V/Braze v9.0.01 .bo.app.d3: Request started

Suppressing logs

The default log level for the Braze Android SDK is INFO. To suppress all logs for the Braze Android SDK, call BrazeLogger.SUPPRESS in your application’s onCreate() method before any other methods.

• java
• kotlin

1
BrazeLogger.setLogLevel(BrazeLogger.SUPPRESS);

1
BrazeLogger.setLogLevel(BrazeLogger.SUPPRESS)

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. By default, new Android projects are configured with debug and release build types and no product flavors.

For each relevant build variant, create a new braze.xml in the src/<build variant name>/res/values/ directory. When the build variant is compiled, it will use the new API key.

1
2
3
4
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="com_braze_api_key">REPLACE_WITH_YOUR_BUILD_VARIANT_API_KEY</string>
</resources>

Enable exclusive in-app message TalkBack

In adherence to the Android accessibility guidelines, the Braze Android SDK offers Android Talkback by default. To ensure that only the contents of in-app messages are read out loud—without including other screen elements like the app title bar or navigation—you can enable exclusive mode for TalkBack.

To enable exclusive mode for in-app messages:

• braze xml
• kotlin
• java

1
<bool name="com_braze_device_in_app_message_accessibility_exclusive_mode_enabled">true</bool>

1
2
3
val brazeConfigBuilder = BrazeConfig.Builder()
brazeConfigBuilder.setIsInAppMessageAccessibilityExclusiveModeEnabled(true)
Braze.configure(this, brazeConfigBuilder.build())

1
2
3
BrazeConfig.Builder brazeConfigBuilder = new BrazeConfig.Builder()
brazeConfigBuilder.setIsInAppMessageAccessibilityExclusiveModeEnabled(true);
Braze.configure(this, brazeConfigBuilder.build());

R8 and ProGuard

Code shrinking configuration is automatically included with your Braze integration.

Client apps that obfuscate Braze code must store release mapping files for Braze to interpret stack traces. If you want to continue to keep all Braze code, add the following to your ProGuard file:

1
2
-keep class bo.app.** { *; }
-keep class com.braze.** { *; }