SDK Integration

Installing the Braze SDK will provide you with the ability to collect analytics and engage users with push messages and native in-app messages. Unity requires the same support library version as the base Android SDK.

Step 1: Choosing A Braze Unity Package

The Braze .unitypackage bundles native bindings for the Android and iOS platforms, along with a Unity 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 and are not using androidX dependencies, 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.
  • Appboy-jetified.unitypackage
    • This package is similar to Appboy.unitypackage except for the Braze Android artifacts being transformed via jetifier to support androidX. This package is particularly useful if using the latest firebase messaging unity versions. The SDWebImage framework is used for downloading and displaying images, including GIFs. If you intend on utilizing full Braze functionality and are using androidX dependencies, download and import this package.
  • Appboy-jetified-nodeps.unitypackage
    • This package is similar to Appboy.unitypackage except for the Braze Android artifacts being transformed via jetifier to support androidX and the SDWebImage] framework not being present. This package is particularly useful if using the latest firebase messaging unity versions and you do not want the SDWebImage framework present in your iOS app.

To see if you require the SDWebImage dependency for your iOS project, please visit the iOS In-App Message Documentation.

Step 2: Importing a Braze Unity 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.

Braze also provides the option of customizing and exporting the Unity package.

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 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
  • The Player Settings pane looks like this in Unity 2019: 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: 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 gradleOut directory.

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

Advanced Android Integration Options

Extending Braze’s Unity Player

The default 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 first three steps of our Android Studio 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 (or appboy-unity-jetified.aar if using androidX dependencies) 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.

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. Change all references of com.appboy.unity.AppboyUnityPlayerActivity to com.appboy.unity.prime31compatible.AppboyUnityPlayerActivity

Disabling Native In-App Message Display

In-app messages from Braze’s servers are automatically displayed natively. To disable this functionality, set com_appboy_inapp_show_inapp_messages_automatically to false in your Unity project’s appboy.xml.

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.

Receiving In-App Message Data in Unity

Unity Game Objects may be registered in your Unity project’s appboy.xml to be notified of incoming in-app messages.

Sample appboy.xml Snippet:

1
2
<string name="com_appboy_inapp_listener_game_object_name"></string>
<string name="com_appboy_inapp_listener_callback_method_name"></string>

The method InAppMessageReceivedCallback in our sample callback code shows an example of parsing incoming in-app message data.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
void InAppMessageReceivedCallback(string message) {
  Debug.Log("InAppMessageReceivedCallback message: " + message);
  IInAppMessage inApp = InAppMessageFactory.BuildInAppMessage(message);
  Debug.Log("In-app message received: " + inApp);
  // Here we are testing the Unity SDK by manually logging the in-app message's click and impression.
  // We should only log the click and impression when the in-app message isn't displayed by Appboy but in Unity.
  //inApp.LogClicked();
  //inApp.LogImpression();
  if (inApp is IInAppMessageImmersive) {
    IInAppMessageImmersive inAppImmersive = inApp as IInAppMessageImmersive;
    if (inAppImmersive.Buttons != null && inAppImmersive.Buttons.Count > 0) {
      // Here we are testing the Unity SDK by manually logging the in-app message's first button's click.
      // We should only log the button click when the in-app message isn't displayed by Appboy but in Unity.
      //inAppImmersive.LogButtonClicked(inAppImmersive.Buttons[0].ButtonID);
    }
  }
}

Receiving Content Card Data in Unity

Unity Game Objects may be registered in your Unity project’s appboy.xml to be notified of incoming Content Cards.

Sample appboy.xml Snippet:

1
2
<string name="com_appboy_content_cards_updated_listener_game_object_name"></string>
<string name="com_appboy_content_cards_updated_listener_callback_method_name"></string>

The method ContentCardsReceivedCallback in our sample callback code shows an example of parsing incoming Content Card data into our convenience wrapper class for Content Cards, ContentCard.cs. ContentCard.cs also supports logging analytics through its LogImpression() and LogClick() methods.

Sample code for parsing incoming Content Card data:

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
void ExampleCallback(string message) {
  // Example of logging a Content Card displayed event
  AppboyBinding.LogContentCardsDisplayed();
  try {
    JSONClass json = (JSONClass)JSON.Parse(message);

    // Content Card data is contained in the `mContentCards` field of the top level object.
    if (json["mContentCards"] != null) {
      JSONArray jsonArray = (JSONArray)JSON.Parse(json["mContentCards"].ToString());
      Debug.Log(String.Format("Parsed content cards array with {0} cards", jsonArray.Count));

      // Iterate over the card array to parse individual cards.
      for (int i = 0; i < jsonArray.Count; i++) {
        JSONClass cardJson = jsonArray[i].AsObject;
        try {
          ContentCard card = new ContentCard(cardJson);
          Debug.Log(String.Format("Created card object for card: {0}", card));

          // Example of logging Content Card analytics on the ContentCard object 
          card.LogImpression();
          card.LogClick();
        } catch {
          Debug.Log(String.Format("Unable to create and log analytics for card {0}", cardJson));
        }
      }
    }
  } catch {
    throw new ArgumentException("Could not parse content card JSON message.");
  }
}

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.

  1. Clone the Braze Unity SDK Github project
1
  git clone git@github.com:Appboy/appboy-unity-sdk.git
  1. Copy the required Braze plugins into your Unity project
Are you using other plugins? What to Copy Where to Copy
NO the Assets/Plugins directory from the Unity SDK the Assets folder of your Unity Project
YES Assets/Plugins/Appboy /<your-project>/Assets/Plugins/Appboy
YES Assets/Plugins/Android /<your-project>/Assets/Plugins/Android

Configure the SDK in XML

A static configuration file called appboy.xml can be used to configure the Braze Android SDK. This file should exist under Assets/Plugins/Android/res/values/appboy.xml.

Part 1: Adding The XML File

If your app does not have an appboy.xml, you can use the following as a template. Otherwise, if you already have an appboy.xml, ensure that any missing sections below are added to your existing appboy.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
<?xml version="1.0" encoding="utf-8"?>
<resources>
  <!-- General configuration -->
  <string name="com_appboy_api_key">REPLACE_WITH_YOUR_BRAZE_API_KEY</string>

  <!-- FCM Push Notification configuration (optional) -->
  <bool translatable="false" name="com_appboy_firebase_cloud_messaging_registration_enabled">true</bool>
  <string translatable="false" name="com_appboy_firebase_cloud_messaging_sender_id">REPLACE_WITH_YOUR_FCM_SENDER_ID</string>

  <!-- Push deep link configuration (optional) -->
  <bool name="com_appboy_handle_push_deep_links_automatically">true</bool> <!-- Whether to open push deep links from Braze automatically. -->

  <!-- In-app message configuration (optional) -->
  <bool name="com_appboy_inapp_show_inapp_messages_automatically">true</bool> <!-- Whether to display in-app messages from Braze using the Braze native UI. -->

  <!-- A custom endpoint, IF applicable. Please ask your Customer Success Manager if this applies to your integration -->
  <!-- <string translatable="false" name="com_appboy_custom_endpoint"></string> -->

  <!-- Optional -->
  <!-- <string name="com_appboy_inapp_listener_game_object_name"></string> --> <!-- The Unity game object to receive inapp messages. -->
  <!-- <string name="com_appboy_inapp_listener_callback_method_name"></string> --> <!-- The callback method to be called when an inapp message is received. -->
  <!-- <string name="com_appboy_feed_listener_game_object_name"></string> --> <!-- The Unity game object to receive the news feed. -->
  <!-- <string name="com_appboy_feed_listener_callback_method_name"></string> --> <!-- The callback method to be called when the news feed is received. -->
  <!-- <string name="com_appboy_content_cards_updated_listener_game_object_name"></string> --> <!-- The Unity game object to receive Content Cards. -->
  <!-- <string name="com_appboy_content_cards_updated_listener_callback_method_name"></string> --> <!-- The callback method to be called when Content Cards are received. -->
  <!-- <string name="com_appboy_push_received_game_object_name"></string> --> <!-- The Unity game object to receive push received messages. -->
  <!-- <string name="com_appboy_push_received_callback_method_name"></string> --> <!-- The callback method to be called when a push received message is received. -->
  <!-- <string name="com_appboy_push_opened_game_object_name"></string> --> <!-- The Unity game object to receive push opened messages. -->
  <!-- <string name="com_appboy_push_opened_callback_method_name"></string> --> <!-- The callback method to be called when a push opened message is received. -->
  <!-- <string name="com_appboy_push_deleted_game_object_name"></string> --> <!-- The Unity game object to receive push deleted messages. -->
  <!-- <string name="com_appboy_push_deleted_callback_method_name"></string> --> <!-- The callback method to be called when a push deleted message is received. -->

  <!--- Internal Braze Usage -->
  <string name="com_appboy_sdk_flavor">UNITY</string>
</resources>

Part 2: Make Replacements in appboy.xml

  • Replace REPLACE_WITH_YOUR_BRAZE_API_KEY with your Braze API Key.
  • Replace REPLACE_WITH_YOUR_FCM_SENDER_ID with your Firebase Messaging Sender ID. Please see Registering for Push for more information.

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.

Part 3: Configure ADM in appboy.xml (optional)

If using ADM, please add the following to your appboy.xml:

1
2
<bool name="com_appboy_push_adm_messaging_registration_enabled">true</bool> <!-- Whether or not Braze should handle registering the device to receive ADM push notifications. Default is false. -->
<bool translatable="false" name="com_appboy_firebase_cloud_messaging_registration_enabled">false</bool>

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.

WAS THIS PAGE HELPFUL?
New Stuff!