SDK Integration

Installing the Braze SDK will provide you with the ability to collect analytics and engage users with push notifications and native in-app messages.

Before you can start using Braze in your Unity scripts, you’ll need to import the plugin files to your Unity project.

As of Braze Unity SDK v1.5.0, Braze’s Unity plugins require Unity 5. See the CHANGELOG for more information.

Initial SDK Setup

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: Importing the Braze Unity Package

As of SDK v.1.8.0, the native Unity functionality, iOS libraries and Android libraries for Braze’s Unity plugin are bundled as a Unity package.

  1. To import the provided Braze Unity package into your project, download the package associated with the most recent SDK release. There are two options:
    • 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 News Feed features. 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 only bundles the Braze Android and iOS SDKs and the accompanying C# interface, which provides native Unity functionality for Braze’s iOS plugin.
  2. In the Unity Editor, import the package into your Unity project by navigating to Assets > Import Package > Custom Package.
  3. (Optional) Deselect any files you do not wish to import. Note that the Appboy and iOS subdirectories are required for this integration.
  4. Click “Import”.

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

Step 2: Setting Your API Key

As of SDK v.1.8.0, Braze provides a native Unity solution for automating the Unity iOS integration. This solution modifies the built Xcode project using Unity’s PostProcessBuildAttribute and subclasses the UnityAppController using the IMPL_APP_CONTROLLER_SUBCLASS macro.

  1. In the Unity Editor, open the Braze Configuration Settings by navigating to Braze > Braze Configuration.
  2. Check the “Automate Unity iOS Integration” box.
  3. In the “Braze API Key” field, input your application’s API key from the Braze Dashboard. Your Braze Configuration settings should look like this: Braze Config Editor

If your application is already using another UnityAppController subclass, you will need to merge your subclass implementation with AppboyAppDelegate.mm.

Step 3: SDK Integration Complete

Braze should now be collecting data from your application and your basic integration should be complete. Continue on to the following sections to integrate in-app messages, the News Feed, push notifications and the complete suite of Braze features.

In-App Message Integration

By default, Braze will handle and display in-app messages via the native iOS SDK. If you wish to pass in-app messages to Unity or customize in-app message display and handling, you must set an in-app message listener by doing the following:

  1. Please ensure that you have followed the Initial SDK Setup steps on setting your Braze API key through Unity.
  2. Set the name of your Game Object and In-App Message listener callback method under “Set In-App Message Listener.”
  3. If you set a listener, Braze will send the in-app message to Unity instead of displaying it, and your in-app message will not automatically appear in your app. If you check “Braze Displays In-App Messages”, Braze will both send the in-app message to your callback method and display it.

    In-App Message Listener

Implementation Example

For a sample implementation, take a look at the InAppMessageReceivedCallback in AppboyBindingTester.cs.

In-App Message Integration Complete

Your Unity application is now set up to receive in-app messages from Braze. See the In-App Message documentation for information on in-app message customization.

News Feed Integration

Braze’s News Feed allows you to insert permanent content directly into your app from our web dashboard. Braze does not provide a default UI for the News Feed in Unity. Instead, the Braze SDK passes along all News Feed cards to Unity. If you wish to integrate the News Feed into your application, you must do the following:

  1. Ensure that you have followed the Initial SDK Setup steps on setting your Braze API key through Unity.
  2. Set the name of your Game Object and News Feed listener callback method under “Set News Feed Listener.”

    Set News Feed Listener

Implementation Example

For a sample implementation, take a look at the FeedReceivedCallback in AppboyBindingTester.cs.

News Feed Integration Complete

Your Unity application is now set up to receive the News Feed data model from Braze. Next, see the News Feed documentation for information on requesting a News Feed data refresh and logging News Feed analytics.

Transitioning from Manual to Automated Integration

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

If the only modifications you have made to your app’s built Xcode project have been for the Braze integration, you can follow the instructions on replacing your Xcode project. Otherwise, follow the instructions for appending to your Xcode project.

Replace Xcode Project

  1. Follow the integration instructions on importing the Braze Unity package and setting your API key through Unity.
  2. Based on the features of your previous Braze integration, continue on to the instructions for integrating push notifications, setting in-app message listeners, and setting feed listeners.
  3. Export your project from Unity to the same destination and choose “Replace.”

Append to Xcode Project

  1. Remove all Braze-related code from your Xcode project’s UnityAppController.mm.
  2. Remove Braze’s iOS libraries from your Unity or Xcode project (i.e., BrazeKit and SDWebImage) and import the Braze Unity package into your Unity project.
  3. Follow the integration instructions on setting your API key through Unity.
  4. Based on the features of your previous Braze integration, continue on to the instructions for integrating push notifications, setting in-app message listeners, and setting feed listeners.
  5. Export your project from Unity to the same destination and choose “Append.”

Manual SDK Integration

Initial SDK Setup

Follow the instructions below to manually integrate Braze into your built Xcode project.

Step 1: Cloning the Unity SDK

Clone the Braze Unity SDK Github project

1
git clone git@github.com:Appboy/appboy-unity-sdk.git

Step 2: Copying Required Plugins

Are you using other plugins? What to Copy Where to Copy
NO the Plugins directory from the Unity SDK the Assets folder of your Unity Project
YES Plugins/Appboy/AppboyBinding.cs /<your-project>/Assets/Plugins
YES Plugins/iOS /<your-project>/Assets/Plugins/iOS

Step 3: Generating Xcode project & Adding Required Classes

Now that you’ve copied over the requisite plugins, the following steps will help you generate your Xcode project and add the required classes for the Braze SDK to function:

  1. Generate your Xcode project in Unity by clicking on File > Build Settings…
  2. Select iOS as the platform and click “Build”.
  3. Select /your-project/your-iOS-project/ as the build location.
  4. Confirm that Unity has copied the files AppboyBinding.m, AppboyUnityManager.h, and AppboyUnityManager.mm to your generated project under the “Libraries” directory.
    • If these three files were not automatically integrated into your project or linked correctly by Unity, you will need to manually copy them into the “Classes” directory of your generated project (without checking “Copy items if needed” in the Options). Then, in the Compile Sources step of your target’s Build Phases tab, make sure to delete any incorrect paths.

Step 4: Integrating the Braze iOS SDK

You must now integrate the standard Braze iOS SDK into your project.

  1. Add the AppboyKit SDK and SDWebImage.framework to your project.
    1. In Xcode, from the project navigator, select the destination project or group for Braze
    2. Navigate to File > Add Files to “Project_Name”
    3. Add the AppboyKit folder and SDWebImage.framework to your project as a group from the Unity SDK Libraries Folder.
      • If you are integrating for the first time, make sure to expand “Options” and check “Copy items if needed”
      • Check “Create groups” option for the “Added folders” Add libraries
  2. Add Required iOS Libraries
    1. Click on the target for your project (using the left-side navigation), and select the “Build Phases” tab
    2. Click the + button under “Link Binary With Libraries”
    3. In the menu, select SystemConfiguration.framework and press the Add button. Add SystemConfiguration.framework
    4. Mark this library as “Required” using the pull-down menu next to SystemConfiguration.framework Mark SystemConfiguration.framework as Required
    5. Repeat Steps 3 and 4 to add each of the following required frameworks to your project, marking each as “Required”
      • QuartzCore.framework
      • CoreImage.framework
      • libz.tbd Rinse and Repeat
    6. Add the following frameworks and mark them as “Optional”:
      • CoreTelephony.framework
      • ImageIO.framework
      • Accounts.framework
      • AdSupport.framework
      • StoreKit.framework
      • CoreLocation.framework
        • You must authorize location for your users using CLLocationManager in your app
  3. Configure the Braze Library and Framework
    1. In the “Build Phases” panel, expand the “Link Binary With Libraries” section and the “Copy Bundle Resources” section
    2. Your “Build Phases” panel should look like the following screenshot:
      • Please ensure that libAppboyKitLibrary.a is within the “Link Binary With Libraries” section, and Appboy.bundle is within the “Copy Bundle Resources” section. Link iOS Binary and Library

Step 5: Updating the Project Build Settings

  1. Click on the target for your project (using the left-side navigation), and select the “Build Settings” tab
  2. Find “Other Linker Flags” and add -ObjC to the row Adding `-ObjC` in "Other Linker Flags"
  3. Find “Framework Search Paths” and add the relative path of the SDWebImage.framework. In the sample here, the relative path is ./../../../Libraries Adding the Path to SDWebImage.framework to "Framework Search Paths"

Step 5: Modifying UnityAppController.mm

You now must make modifications to your generated Classes/UnityAppController.mm:

  1. At the top of UnityAppController.mm add the following import statements:
1
2
	#import "AppboyKit.h"
	#import "AppboyUnityManager.h"
  1. In the method applicationDidFinishLaunchingWithOptions, add the following code snippet above the return statement. Be sure to replace "YOUR-API-KEY" with the Braze API key from the Braze dashboard.
1
2
3
	[Appboy startWithApiKey:@"YOUR-API-KEY"
    	    inApplication:application
        	withLaunchOptions:launchOptions];

Step 6: Updating Your App From Unity

Finally, if you need to update your app from Unity, ensure that you choose the same location to generate the Xcode project each time and choose “Append” the existing folder when prompted by Unity to ensure that you don’t have to redo any of your Braze setup in the future. (Note that Unity may overwrite the Framework Search Paths even when appending to the Xcode project.)

Step 7: SDK Integration Complete

Braze should now be collecting data from your application and your basic integration should be complete. Continue on to the following sections to integrate in-app messages, the News Feed, push notifications and the complete suite of Braze features.

In-App Message Integration

You can set an in-app message listener by manually modifying your built Xcode project. In order to pass in-app messages from Braze to Unity, you must add the following code to your applicationDidFinishLaunchingWithOptions method within your UnityAppController.mm file:

1
2
3
[Appboy sharedInstance].inAppMessageController.delegate = [AppboyUnityManager sharedInstance];

[[AppboyUnityManager sharedInstance] addInAppMessageListenerWithObjectName:@"Your Unity Game Object Name" callbackMethodName:@"Your Unity Call Back Method Name"];
  • @"Your Unity Game Object Name" must be replaced with the Unity object name you want to listen to the in-app message.
  • @"Your Unity Call Back Method Name" is the call back method name that handles the in-app message.
  • The call back method must be contained within the Unity object you passed in as the first parameter.

If you have added an in-app message listener, Braze will send the message to Unity instead of displaying it by default, meaning your in-app message will not automatically appear in your app. To have Braze handle displaying in-app messages, change the (BOOL) onInAppMessageReceived:(ABKInAppMessage *)inAppMessage method in AppboyUnityManager.mm and make it return NO.

News Feed Integration

You can set a feed listener by manually modifying your built Xcode project. In order to pass the News Feed from Braze to Unity, you must add the following code to your applicationDidFinishLaunchingWithOptions method within your UnityAppController.mm file:

1
[[AppboyUnityManager sharedInstance] addFeedListenerWithObjectName:@"Your Unity Game Object Name" callbackMethodName:@"Your Unity Call Back Method Name"];
  • @"Your Unity Game Object Name" must be replaced with the Unity object name you want to receive the News Feed.
  • @"Your Unity Call Back Method Name" is the call back method name that handles the News Feed model.
  • The call back method must be contained within the Unity object you passed in as the first parameter.
WAS THIS PAGE HELPFUL?