SDK Android Integration

Follow the below instructions to get Braze running in your Unity application. If you are transitioning from a manual integration, please read the instructions on Transitioning From a Manual to an Automated Integration.

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 at Braze Unity Releases Page:

  • Appboy.unitypackage
    • This package bundles the Braze Android and iOS SDKs as well as the SDWebImage dependency for the iOS SDK, which is required for 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 not being 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, please 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 above.

Step 2: Import the Package

  1. In the Unity Editor, import the package into your Unity project by navigating to Assets > Import Package > Custom Package.
  2. Click Import.

Alternatively, follow the Unity instructions for Importing Asset packages for a more detailed guide on importing custom Unity packages.

Step 3a: 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 in order to function.

Part 1: 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 missing sections below 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
33
34
35
36
37
38
39
40
41
<?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.appboy.AppboyFirebaseMessagingService"
      android:exported="false">
      <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
      </intent-filter>
    </service>

    <!-- BroadcastReceiver used to forward certain Braze push notification events to Unity -->
    <receiver android:name="com.appboy.unity.AppboyUnityPushBroadcastReceiver" android:exported="false" >
      <intent-filter>
        <action android:name="REPLACE_WITH_YOUR_PACKAGE_NAME.intent.APPBOY_PUSH_RECEIVED" />
        <action android:name="REPLACE_WITH_YOUR_PACKAGE_NAME.intent.APPBOY_NOTIFICATION_OPENED" />
        <action android:name="REPLACE_WITH_YOUR_PACKAGE_NAME.intent.APPBOY_PUSH_DELETED" />
      </intent-filter>
    </receiver>
  </application>
</manifest>

Your AndroidManifest.xml should exist under Assets/Plugins/Android/AndroidManifest.xml. Please 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.

Part 2: Finding your Package Name

  • Click File -> Build Settings -> Player Settings -> Android Tab Unity Package Name

Part 3: Make Replacements in the AndroidManifest

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
implementation "androidx.appcompat:appcompat:+"

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

Examples on how to add these dependencies using Unity tools are provided below.

Custom Gradle Template

Custom Gradle Template

1
2
3
dependencies {
  implementation "androidx.appcompat:appcompat:+"
}

External Dependency Manager for Unity

External Dependency Manager for Unity

1
2
3
4
5
<dependencies>
  <androidPackages>
    <androidPackage spec="androidx.appcompat:appcompat:+" />
  </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 from the Braze Dashboard.

Your Braze API key can be found within the Settings page of the Braze dashboard. To find out your specific cluster or endpoint, please ask your Customer Success Manager or open a support ticket.

Basic SDK Integration Complete

Braze should now be collecting data from your application and your basic integration should be complete.

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 this documentation 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.

WAS THIS PAGE HELPFUL?
New Stuff!