SDK Android integration

This reference article covers the Android SDK integration for the Unity platform. Follow these instructions to get Braze running in your Unity application.

Step 1: Choose your Braze Unity package

The Braze .unitypackage bundles native bindings for the Android and iOS platforms, along with a C# interface.

There are several Braze Unity packages available for download on the Braze Unity releases page:

• Appboy.unitypackage
  • This package bundles the Braze Android and iOS SDKs and the SDWebImage dependency for the iOS SDK, which is required for the proper functionality of Braze’s In-App Messaging, and Content Cards features on iOS. The SDWebImage framework is used for downloading and displaying images, including GIFs. If you intend on utilizing full Braze functionality, download and import this package.
• Appboy-nodeps.unitypackage
  • This package is similar to Appboy.unitypackage except for the SDWebImage framework is not present. This package is useful if you do not want the SDWebImage framework present in your iOS app.

iOS: To see if you require the SDWebImage dependency for your iOS project, visit the iOS in-app message documentation.
Android: As of Unity 2.6.0, the bundled Braze Android SDK artifact requires AndroidX dependencies. If you were previously using a jetified unitypackage, then you can safely transition to the corresponding unitypackage.

Step 2: Import the package

In the Unity Editor, import the package into your Unity project by navigating to Assets > Import Package > Custom Package. Next, click Import.

Alternatively, follow the Unity asset package import instructions for a more detailed guide on importing custom Unity packages.

Step 3: Updating your AndroidManifest.xml

Android Unity projects require an AndroidManifest.xml to be present to run the application. Additionally, Braze requires several additions to your AndroidManifest.xml to function.

Configuring the AndroidManifest.xml

If your app does not have an AndroidManifest.xml, you can use the following as a template. Otherwise, if you already have an AndroidManifest.xml, ensure that any of the following missing sections are added to your existing AndroidManifest.xml.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="REPLACE_WITH_YOUR_PACKAGE_NAME">

  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <uses-permission android:name="android.permission.INTERNET" />

  <application android:icon="@drawable/app_icon" 
               android:label="@string/app_name">

    <!-- Calls the necessary Braze methods to ensure that analytics are collected and that push notifications are properly forwarded to the Unity application. -->
    <activity android:name="com.appboy.unity.AppboyUnityPlayerActivity" 
      android:label="@string/app_name" 
      android:configChanges="fontScale|keyboard|keyboardHidden|locale|mnc|mcc|navigation|orientation|screenLayout|screenSize|smallestScreenSize|uiMode|touchscreen" 
      android:screenOrientation="sensor">
      <meta-data android:name="android.app.lib_name" android:value="unity" />
      <meta-data android:name="unityplayer.ForwardNativeEventsToDalvik" android:value="true" />
      <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
      </intent-filter>
    </activity>

    <!-- A Braze specific FirebaseMessagingService used to handle push notifications. -->
    <service android:name="com.braze.push.BrazeFirebaseMessagingService"
      android:exported="false">
      <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
      </intent-filter>
    </service>
  </application>
</manifest>

Your AndroidManifest.xml should exist under Assets/Plugins/Android/AndroidManifest.xml. See the Unity AndroidManifest documentation for more information.

All Activity classes registered in your AndroidManifest.xml file should be fully integrated with the Braze Android SDK. If you add your own Activity class, you must follow Braze’s Unity Activity integration instructions to ensure that analytics are being collected.

Update the AndroidManifest.xml with your package name

To find your package name, click File > Build Settings > Player Settings > Android Tab.

In your AndroidManifest.xml, all instances of REPLACE_WITH_YOUR_PACKAGE_NAME should be replaced with your Package Name from the previous step.

Step 4: Add gradle dependencies

The following dependencies are required:

1
2
3
4
5
6
implementation "org.jetbrains.kotlin:kotlin-stdlib:1.5.21"
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.2"

// Both are required if using the default Content Cards Activity on Android
implementation "androidx.swiperefreshlayout:swiperefreshlayout:+"
implementation "androidx.recyclerview:recyclerview:+"

The following list examples of how to add these dependencies using Unity tools:

Custom Gradle template

1
2
3
4
dependencies {
  implementation "org.jetbrains.kotlin:kotlin-stdlib:1.5.21"
  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.2"
}

External dependency manager for Unity

1
2
3
4
5
6
<dependencies>
  <androidPackages>
    <androidPackage spec="org.jetbrains.kotlin:kotlin-stdlib:1.5.21" />
    <androidPackage spec="org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.2" />
  </androidPackages>
</dependencies>

Step 5: Configure the SDK

Braze provides a native Unity solution for automating the Unity Android integration.

1. In the Unity Editor, open the Braze Configuration Settings by navigating to Braze > Braze Configuration.
2. Check the Automate Unity Android Integration box.
3. In the “Braze API Key” field, input your application’s API key found in Manage Settings from the Braze dashboard.

Basic SDK integration complete

Braze should now be collecting data from your application, and your basic integration should be complete. Check out the following articles for more information on integrating push (Android and iOS), in-app messages, and Content Cards.

Additional advanced implementation options

Extending Braze’s Unity player (Android)

The example AndroidManifest.xml file provided has one Activity class registered, AppboyUnityPlayerActivity. This class is integrated with the Braze SDK and extends UnityPlayerActivity with session handling, in-app message registration, push notification analytics logging, and more. See Unity for more information on extending the UnityPlayerActivity class.

If you are creating your own custom UnityPlayerActivity in a library or plugin project, you will need to extend Braze’s AppboyUnityPlayerActivity to integrate your custom functionality with Braze. Before beginning work on extending AppboyUnityPlayerActivity, follow our instructions for integrating Braze into your Unity project.

1. Add the Braze Android SDK as a dependency to your library or plugin project as described in the Braze Android SDK integration instructions.
2. Integrate our Unity .aar, which contains Braze’s Unity-specific functionality, to your Android library project you are building for Unity. The appboy-unity.aar is available from our public repo. Once our Unity library is successfully integrated, modify your UnityPlayerActivity to extend AppboyUnityPlayerActivity.
3. Export your library or plugin project and drop it into /<your-project>/Assets/Plugins/Android as normal. Do not include any Braze source code in your library or plugin as they will already be present in /<your-project>/Assets/Plugins/Android.
4. Edit your /<your-project>/Assets/Plugins/Android/AndroidManifest.xml to specify your AppboyUnityPlayerActivity subclass as the main activity.

You should now be able to package an .apk from the Unity IDE that is fully integrated with Braze and contains your custom UnityPlayerActivity functionality.