Step 1: Choosing A Braze Unity Package
.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:
- 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.
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
Step 2: Importing a Braze Unity Package
- In the Unity Editor, import the package into your Unity project by navigating to
Assets > Import Package > Custom Package.
- Click “Import”.
Alternatively, follow the Unity instructions for Importing Asset packages for a more detailed guide on importing custom Unity packages.
If you only wish to import the Android plugin, deselect the
Plugins/iOS subdirectory when importing the Braze
Step 3: Updating your AndroidManifest.xml
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
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>
AndroidManifest.xmlshould exist under
Assets/Plugins/Android/AndroidManifest.xml. Please see the Unity AndroidManifest documentation for more information.
All Activity classes registered in your
AndroidManifest.xmlfile 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
- The Player Settings pane looks like this in Unity 2019:
Part 3: Make Replacements in the AndroidManifest
AndroidManifest.xml, all instances of
REPLACE_WITH_YOUR_PACKAGE_NAME should be replaced with your
Package Name from the previous step.
Step 4: Configure the SDK
Braze provides a native Unity solution for automating the Unity Android integration. This solution modifies the built Gradle project using Unity’s
OnPostGenerateGradleAndroidProject and auto-generates a resource file called
/unity-android-resources/res/values/appboy-generated.xml in your temporary
- In the Unity Editor, open the Braze Configuration Settings by navigating to Braze > Braze Configuration.
- Check the “Automate Unity Android Integration” box.
- 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 App 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.
This automatic integration should not be used in conjunction with a manually created
braze.xml file since the configuration values may conflict during project building.
Step 5: Basic SDK Integration Complete
Braze should now be collecting data from your application and your basic integration should be complete.
See the Push documentation for information on integrating push.
See the In-App Message documentation for information on integrating in-app messages.
Content Cards Integration
See the Content Cards documentation for information on integrating Content Cards.
News Feed Integration
See the News Feed documentation for information on integrating the News Feed.
Extending the SDK
To extend the SDK’s behaviors, fork our Braze Unity SDK Github project and make your required changes.
To publish your modified code as a Unity package, see Advanced Use Cases.
Advanced Android Integration Options
Extending Braze’s Unity Player
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
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.
Add the Braze Android SDK as a dependency to your library or plugin project as described in the first three steps of our Android Studio integration instructions.
Integrate our Unity
.aar, which contains Braze’s Unity-specific functionality, to your Android library project you are building for Unity. The
androidXdependencies) is available from our public repo. Once our Unity library is successfully integrated, modify your
Export your library or plugin project and drop it into
/<your-project>/Assets/Plugins/Androidas 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/AndroidManifest.xmlto specify your
AppboyUnityPlayerActivitysubclass 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