Installing the Braze SDK will provide you with the ability to collect analytics and engage users with push messages and native in-app messages.
Note: As of Braze Unity SDK v1.5.0, Braze’s Unity plugins require Unity 5. See the CHANGELOG for more information.
Step 1: Importing the Braze Unity Package
As of SDK v.1.8.0, the native Unity functionality and iOS libraries for Braze’s Unity plugin are bundled as a Unity package.
- To import the provided Braze Unity package into your project, download the package associated with the most recent SDK release. There are two options:
- 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 News Feed 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.
- This package only bundles the Braze Android and iOS SDKs and the accompanying C# interface, which provides native Unity functionality for Braze’s iOS plugin.
- In the Unity Editor, import the package into your Unity project by navigating to Assets > Import Package > Custom Package.
- Deselect any files you do not wish to import.
- If you already have your own
AndroidManifest.xml, please remember to uncheck the
AndroidManifest.xmlfile during package importing to avoid overwriting your existing file. Plase refer to this file as a template for needed permissions in here on our public GitHub repo.
- If you only wish to import the Android plugins, you only need to check the
- If you already have your own
- Click “Import”.
Alternatively, Braze also provides the option of customizing and exporting the Unity package.
Manually Copying Required Plugins
If you do not wish to import the Unity package, you may also manually copy the plugins into your Unity project.
Clone the Braze Unity SDK Github project
bash git clone email@example.com:Appboy/appboy-unity-sdk.git
Copy the required Braze plugins into your Unity project
Are you using other plugins? What to Copy Where to Copy NO the
Assets/Pluginsdirectory from the Unity SDK
Assetsfolder of your Unity Project
Note: If you are using a version of Unity <5.2, all assets from our SDK will need to be added to your project manually. All current assets are available in our public SDK repo.
Step 3: Adding Your Bundle Identifier
Part 1: Identifying Replacement Targets
To find all of the locations that must be modified to fully configure Braze for Android, run the following from the root directory of your Unity project:
grep -r REPLACE Assets/Plugins/
Example output with successful plugin transfer:
Android/AndroidManifest.xml: <package="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER" android:versionCode="1" android:versionName="0.0"> Android/AndroidManifest.xml: <permission android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.permission.C2D_MESSAGE" android:protectionLevel="signature" /> Android/AndroidManifest.xml: <uses-permission android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.permission.C2D_MESSAGE" /> Android/AndroidManifest.xml: <permission android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.permission.RECEIVE_ADM_MESSAGE" android:protectionLevel="signature" /> Android/AndroidManifest.xml: <uses-permission android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.permission.RECEIVE_ADM_MESSAGE" /> Android/AndroidManifest.xml: <category android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER" /> Android/AndroidManifest.xml: <category android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER" /> Android/AndroidManifest.xml: <action android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.intent.APPBOY_NOTIFICATION_OPENED" /> Android/res/values/appboy.xml: <string name="com_appboy_api_key">REPLACE_WITH_YOUR_APPBOY_API_KEY</string> Android/res/values/appboy.xml: <string name="com_appboy_push_gcm_sender_id">REPLACE_WITH_YOUR_GCM_SENDER_ID</string> <!-- Replace with your gcm sender ID. The sender ID is your Google API project number. -->
Part 2: Replacing the Placeholders with your Bundle Identifier
- Find your
Bundle Identifierwithin Unity.
- Click File -> Build Settings -> Player Settings -> Android Tab
- The Player Settings pane looks like this in Unity 4:
- Open AndroidManifest.xml and find/replace all instances of
Bundle Identifieris usually in the form
com.unity.appname. Note: 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 usual integration instructions to ensure that analytics are being collected.
Plugins/Android/res/values/appboy.xmlreplace all instances of
REPLACE_WITH_YOUR_APPBOY_API_KEYwith your Braze API key. Your API Key can be found in the App Settings page of the Braze Dashboard
To enable GCM push notifications, insert your GCM Sender ID from Google into the same appboy.xml configuration file. If you don’t have a GCM Sender ID yet, you’ll need to follow the GCM setup instructions from Google. Once you have the ID, change
REPLACE_WITH_YOUR_GOOGLE_API_PROJECT_NUMBERto your GCM ID. Since the GCM ID is a number, you shouldn’t surround the value with quotes. Your ID should look something like
134664038331. For more information on integrating GCM, please visit our GCM push integration instructions.
- If it is not present already, make sure
AppboyOverlayActivityis declared in your
AndroidManifest.xml. It is used for in-app message display on Unity as of Braze Unity SDK starting with version
<activity android:name="com.appboy.unity.AppboyOverlayActivity" android:theme="@style/Appboy.Theme.Transparent" />
- If the following lines are not present already, add the following lines to declare the Braze WebView and News Feed activities. These will allow you to handle web urls and deep links to the News Feed via push and in-app messages:
<activity android:name="com.appboy.ui.AppboyWebViewActivity" android:theme="@android:style/Theme" /> <activity android:name="com.appboy.ui.activities.AppboyFeedActivity" android:theme="@android:style/Theme" />
Advanced Android Integration Options
Extending Braze’s Native Unity Player
The default AndroidManifest.xml file provided has one Activity class registered,
com.appboy.unity.AppboyUnityPlayerNativeActivity. This class is integrated with the Braze SDK and extends
UnityPlayerNativeActivity with session handling, in-app message registration, push notification analytics logging, and more.
If you are creating your own custom
UnityPlayerNativeActivity in a library or plugin project, you will need to extend Braze’s
AppboyUnityPlayerNativeActivity to integrate your custom functionality with Braze.
Note: Before beginning work on extending
AppboyUnityPlayerNativeActivity, 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
.aaris 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
AppboyUnityPlayerNativeActivitysubclass 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
Prime 31 Compatibility
In order to use the Braze Unity plugin with Prime31 plugins, edit your project’s
AndroidManifest.xml to use the Prime31 compatible Activity classes and GCM receiver. Change all references of
Note: If you are integrating Braze Unity sdk version
1.5.0 or below, you will also need to change
com.appboy.unity.prime31compatible.AppboyUnityGcmReceiver. This step is unnecessary as of
Disabling Native In-App Message Display
As of Braze Unity SDK version
1.5.0, in-app messages from Braze’s servers are automatically displayed natively. To disable this functionality, set
false in your Unity project’s
Note: If you are integrating Braze Unity sdk version
1.6.0 or below, you will also need to call
AppboyBinding.RequestInAppMessage() to request in-app messages from Braze. This step is unnecessary as of
1.7.0 due to the introduction of triggered in-app messages. See our documentation about the key differences between original and triggered in-app messages, including reasons to use the latter.
Amazon ADM Push
Braze supports integrating Amazon ADM push into Unity apps. If you would like to integrate Amazon 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 Amazon ADM with Braze, please visit our ADM push integration instructions.
Registering Unity GameObject as Listeners
Unity GameObjects must be registered as listeners in in your Unity project’s
appboy.xml to be notified of incoming in-app messages.
In-App Message GameObject Listeners
The Unity GameObject to be notified when an in-app message is received.
Sample appboy.xml Snippet:
<!-- Sample --> <string name="com_appboy_inapp_listener_game_object_name"></string> <string name="com_appboy_inapp_listener_callback_method_name"></string>
SDK Integration Complete
Braze should now be collecting 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.