Integrating the Braze Unity SDK

Learn how to integrate and customize the Braze Unity SDK. For a full list of types, functions, variables, and more, see Unity Declaration File. To learn more about the SDK in general, see Getting started: Integration overview.

Prerequisites

Before you start, verify your environment is supported by the latest Braze Unity SDK version.

Integrating the SDK

Step 1: Choose your Braze Unity package

• android
• swift

Step 2: Import the package

• android
• swift

Step 3: Configure the SDK

• android
• swift

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
<?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.braze.unity.BrazeUnityPlayerActivity" 
      android:theme="@style/UnityThemeSelector"
      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>

1
2
3
4
5
6
implementation 'com.google.firebase:firebase-messaging:22.0.0'
implementation "androidx.swiperefreshlayout:swiperefreshlayout:1.1.0"
implementation "androidx.recyclerview:recyclerview:1.2.1"
implementation "org.jetbrains.kotlin:kotlin-stdlib:1.6.0"
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.1"
implementation 'androidx.core:core:1.6.0'

Customizing the Unity package

Step 1: Clone the repository

In your terminal, clone the Braze Unity SDK GitHub repository, then navigate to that folder:

• macos
• windows powershell

1
2
git clone [email protected]:braze-inc/braze-unity-sdk.git
cd ~/PATH/TO/DIRECTORY/braze-unity-sdk

1
2
git clone git@github.com:braze-inc/braze-unity-sdk.git
cd C:\PATH\TO\DIRECTORY\braze-unity-sdk

Step 2: Export package from repository

First, launch Unity and keep it running in the background. Then, in the repository root, run the following command to export the package to braze-unity-sdk/unity-package/.

• macos
• windows powershell

1
/Applications/Unity/Unity.app/Contents/MacOS/Unity -batchmode -nographics -projectPath "$(pwd)" -executeMethod Appboy.Editor.Build.ExportAllPackages -quit

1
"%UNITY_PATH%" -batchmode -nographics -projectPath "%PROJECT_ROOT%" -executeMethod Appboy.Editor.Build.ExportAllPackages -quit	

Step 3: Import package into Unity

1. In Unity, import the desired package into your Unity project by navigating to Assets > Import Package > Custom Package.
2. If there’s any files you don’t want want to import, deselect them now.
3. Customize the exported Unity package located in Assets/Editor/Build.cs.

Switch to an automated integration (Swift only)

To take advantage of the automated iOS integration offered in the Braze Unity SDK, follow these steps on transitioning from a manual to an automated integration.

1. Remove all Braze-related code from your Xcode project’s UnityAppController subclass.
2. Remove Braze iOS libraries from your Unity or Xcode project (such as Appboy_iOS_SDK.framework and SDWebImage.framework).
3. Import the Braze Unity package into your project again. For a full walkthrough, see Step 2: Import the package.
4. Set your API key again. For a full walkthrough, see Step 3.1: Set your API key.

Optional configurations

Verbose logging

To enable verbose logging in the Unity Editor, do the following:

1. Open the Braze Configuration Settings by navigating to Braze > Braze Configuration.
2. Click the Show Braze Android Settings dropdown.
3. In the SDK Log Level field, input the value “0”.

Prime 31 compatibility

To use the Braze Unity plugin with Prime31 plugins, edit your project’s AndroidManifest.xml to use the Prime31 compatible Activity classes. Change all references of com.braze.unity.BrazeUnityPlayerActivity to com.braze.unity.prime31compatible.BrazeUnityPlayerActivity

Amazon Device Messaging (ADM)

Braze supports integrating ADM push into Unity apps. If you want to integrate ADM push, create a file called api_key.txt containing your ADM API key and place it in the Plugins/Android/assets/ folder. For more information on integrating ADM with Braze, visit our ADM push integration instructions.

Extending the Braze Unity player (Android only)

The example AndroidManifest.xml file provided has one Activity class registered, BrazeUnityPlayerActivity. 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 our BrazeUnityPlayerActivity to integrate your custom functionality with Braze. Before beginning work on extending BrazeUnityPlayerActivity, 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 our Unity-specific functionality, to your Android library project you are building for Unity. The appboy-unity.aar is available from our public repo. After our Unity library is successfully integrated, modify your UnityPlayerActivity to extend BrazeUnityPlayerActivity.
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 BrazeUnityPlayerActivity 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.

Troubleshooting

Error: “File could not be read”

Errors resembling the following may be safely ignored. Apple software uses a proprietary PNG extension called CgBI, which Unity does not recognize. These errors will not affect your iOS build or the proper display of the associated images in the Braze bundle.

1
Could not create texture from Assets/Plugins/iOS/AppboyKit/Appboy.bundle/...png: File could not be read