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

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" }
  }
}

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.

Add Braze Dependency

Add the android-sdk-ui dependency to your app’s build.gradle. For example:

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 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 are on a specific data cluster or have a pre-existing custom endpoint, 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 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">REPLACE_WITH_YOUR_API_KEY</string>
<string translatable="false" name="com_appboy_custom_endpoint">YOUR_CUSTOM_ENDPOINT_OR_CLUSTER</string>
</resources>

Implementation Example

See the appboy.xml in the Droidboy sample app for an implementation example.

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 AndroidManifest.xml in the Droidboy sample app for an implementation example.

Step 4: Tracking User Sessions in Android

Activity Lifecycle Callback Integration (API 14+)

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:

• JAVA
• KOTLIN

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

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>

The 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>

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.