Installing the Appboy SDK will provide you with the ability to collect analytics and engage users with push messages and native in-app messages.
Note: As of Appboy Unity SDK v1.5.0, Appboy’s Unity plugins require Unity 5. See the CHANGELOG for more information.
Time Estimate: 20-30 Minutes
Step 1: Importing the Appboy Unity Package
As of SDK v.1.8.0, the native Unity functionality and iOS libraries for Appboy’s Unity plugin are bundled as a Unity package.
- To import the provided Appboy Unity package into your project, download the package associated with the most recent SDK release. There are two options:
- This package bundles the Appboy Android and iOS SDKs as well as the SDWebImage dependency for the iOS SDK, which is required for proper functionality of Appboy’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 Appboy functionality, download and import this package.
- This package only bundles the Appboy Android and iOS SDKs and the accompanying C# interface, which provides native Unity functionality for Appboy’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, Appboy 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 Appboy Unity SDK Github project
bash git clone email@example.com:Appboy/appboy-unity-sdk.git
Copy the required Appboy 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 Appboy 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 Appboy Android SDK. If you add your own Activity class, you must follow Appboy’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 Appboy API key. Your API Key can be found in the App Settings page of the Appboy 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 Appboy 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 Appboy 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 Appboy’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 Appboy 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 Appboy’s
AppboyUnityPlayerNativeActivity to integrate your custom functionality with Appboy.
Note: Before beginning work on extending
AppboyUnityPlayerNativeActivity, follow our instructions for integrating Appboy into your Unity project.
Add the Appboy 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 Appboy’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 Appboy 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 Appboy and contains your custom
Prime 31 Compatibility
In order to use the Appboy 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 Appboy 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 Appboy Unity SDK version
1.5.0, in-app messages from Appboy’s servers are automatically displayed natively. To disable this functionality, set
false in your Unity project’s
Note: If you are integrating Appboy Unity sdk version
1.6.0 or below, you will also need to call
AppboyBinding.RequestInAppMessage() to request in-app messages from Appboy. 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
Appboy 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 Appboy, 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
Appboy 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 Appboy features.