SDK Integration

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.

  1. To import the provided Appboy 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 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.
    • Appboy-nodeps.unitypackage
      • 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.
  2. In the Unity Editor, import the package into your Unity project by navigating to Assets > Import Package > Custom Package.
  3. Deselect any files you do not wish to import.
    • If you already have your own AndroidManifest.xml, please remember to uncheck the AndroidManifest.xml file 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 Appboy and Android subdirectories.
  4. 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.

  1. Clone the Appboy Unity SDK Github project

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

  2. Copy the required Appboy 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/AppboyBinding.cs /<your-project>/Assets/Plugins
    YES Assets/Plugins/Android /<your-project>/Assets/Plugins/Android

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

  1. Find your Bundle Identifier within Unity.
    • Click File -> Build Settings -> Player Settings -> Android Tab
    • The Player Settings pane looks like this in Unity 4: Unity Bundle Identifier
  2. Open AndroidManifest.xml and find/replace all instances of REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER with your Bundle Identifier.
    • Your Bundle Identifier is 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.
  3. In Plugins/Android/res/values/appboy.xml replace all instances of REPLACE_WITH_YOUR_APPBOY_API_KEY with your Appboy API key. Your API Key can be found in the App Settings page of the Appboy Dashboard

  4. 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_NUMBER to 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.

  5. If it is not present already, make sure AppboyOverlayActivity is declared in your AndroidManifest.xml. It is used for in-app message display on Unity as of Appboy Unity SDK starting with version 1.6.0:
<activity android:name="com.appboy.unity.AppboyOverlayActivity" android:theme="@style/Appboy.Theme.Transparent" />
  1. 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.

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

  2. Integrate our Unity .aar, which contains Appboy’s Unity-specific functionality, to your Android library project you are building for Unity. The .aar is available from our public repo. Once our Unity library is successfully integrated, modify your UnityPlayerNativeActivity to extend AppboyUnityPlayerNativeActivity.

  3. Export your library or plugin project and drop it into /<your-project>/Assets/Plugins/Android as 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.

  4. Edit your /<your-project>/Assets/Plugins/Android/AndroidManifest.xml to specify your AppboyUnityPlayerNativeActivity subclass 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 UnityPlayerNativeActivity functionality.

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 com.appboy.unity.AppboyUnityPlayerNativeActvity

to

com.appboy.unity.prime31compatible.AppboyUnityPlayerNativeActivity

Note: If you are integrating Appboy Unity sdk version 1.5.0 or below, you will also need to change com.appboy.unity.AppboyUnityGcmReceiver to com.appboy.unity.prime31compatible.AppboyUnityGcmReceiver. This step is unnecessary as of 1.6.0.

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 com_appboy_inapp_show_inapp_messages_automatically to false in your Unity project’s appboy.xml.

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

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.

Push Notifications

A push notification is an out-of-app alert that appears on the user’s screen when an important update occurs. Push notifications are a valuable way to provide your users with time-sensitive and relevant content or to re-engage them with your app.

Sample push notification:

Sample Push

Check out Appboy Academy for additional best practices.

Appboy sends push notifications to Android devices using Google Cloud Messaging (GCM).

Time Estimate: 7 Minutes

In order to integrate Appboy push notifications into your app, you need to:

  1. Enable GCM in your Google project
  2. Configure your Android Manifest
  3. Configure your appboy.xml
  4. Set your API key on the Appboy dashboard

Step 1: Enabling GCM

If you do not already have a Google API project with GCM messaging enabled, follow the instructions from the Google GCM Getting Started page. It will take you through the necessary steps to create a Google API project. In order to turn on push notifications in Appboy, you will need to take note of your:

  • Project Number
  • GCM API Key

Step 2: Configure your Android Manifest

Once you have setup your Google API project, it is time to configure your Android Manifest with required permissions for GCM.

  1. Add the following permissions to your AndroidManifest.xml:

     ```
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.GET_ACCOUNTS" />
     <uses-permission android:name="android.permission.WAKE_LOCK" />
     <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
     ```
    
  2. An additional special permission is required in your your AndroidManifest.xml to ensure that push notifications are being sent to your app and that no other app can receive your push notifications.

     ```
     <permission android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.permission.C2D_MESSAGE" android:protectionLevel="signature"/>
     <uses-permission android:name="REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.permission.C2D_MESSAGE" />
     ```
    

Note: With the release of Android M, Android switched from an install-time to a runtime permissions model. To enable push on devices running Ice Cream Sandwich and below, the app must explicitly receive the GET_ACCOUNTS permission from the user (Appboy will not do this). Note that GET_ACCOUNTS is not required for devices running Jelly Bean and above. All other permissions listed above are normal permissions and are granted automatically if listed in the app manifest. For more information, visit Android’s permission documentation.

Implementation Example

A sample AndroidManifest.xml is available at our public repo.

Step 3: Configure your appboy.xml

In order for a device to receive push notifications, it must register with the Google GCM server. The Appboy SDK can handle the registration process for you.

  1. To tell Appboy to handle GCM registration, add the following configuration to your appboy.xml file:

     <!-- Whether or not Appboy should handle registering the device to receive push notifications. Default is false. -->
     <bool name="com_appboy_push_gcm_messaging_registration_enabled">true</bool>
    
  2. Add the following configuration element to your appboy.xml file and replace YOUR-GOOGLE-API-PROJECT-NUMBER with your Google API project number:

     <!-- Replace with your Google API project number -->
     <string name="com_appboy_push_gcm_sender_id">YOUR-GOOGLE-API-PROJECT-NUMBER</string>
    
  3. RECOMMENDED: To instruct Appboy to handle deep links from push automatically, add the following configuration to your appboy.xml file:

     <!-- Whether to open push deep links from Appboy automatically. -->
     <bool name="com_appboy_handle_push_deep_links_automatically">true</bool>
    
  4. RECOMMENDED: Specify the drawable resource that should be displayed in the push notification in your appboy.xml file.

     <!-- The drawable that should be displayed whenever a push notification is received. If no icon is given, the notification will use the application icon -->
     <drawable name="com_appboy_push_small_notification_icon">REPLACE_WITH_YOUR_ICON</drawable>
    
  5. OPTIONAL: Appboy will broadcast Intents whenever a push notification is received or opened. If you need to perform custom logic upon push notifications open or receipt, you may create and register a custom broadcast receiver to listen to and respond to these intents. The names of the actions are:

     REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.intent.APPBOY_PUSH_RECEIVED
     REPLACE_WITH_YOUR_BUNDLE_IDENTIFIER.intent.APPBOY_NOTIFICATION_OPENED
    
Implementation Example

A sample appboy.xml is available at our public repo.

Step 4: Set your Google Project API Key on the Appboy Dashboard

You need to input your Google Project API key into the Appboy dashboard. On the app settings page (where your API keys are located), select your Android app. Enter your Google Project API key in the field labeled GCM (Google Cloud Messaging) API Key under the Push Notifications section.

GCMKey

After completing the Google GCM Getting Started page ensure that you’re using the API key for server applications. If you’re not familiar with the location of that key follow these steps:

  1. Login to the Google Developers Console
  2. Select your GCM project
  3. Select Credentials under APIs & auth

GCMCredentials 4. Copy your API key for server applications

GCMKeyConsole

Confirm that your Android app targets version 2.3 (Gingerbread) or above in the “Player Settings” pane within the “Build Settings”.

Implementation Example

The sample project in the Appboy Unity SDK repository contains a full working sample app that includes GCM.

Common Issues

  1. I followed the integration instructions but I’m still not receiving any push notifications.
  2. Deep links aren’t opened when I click on a push message.
    • Be sure automatic deep link handling is enabled in your appboy.xml by setting com_appboy_handle_push_deep_links_automatically to true.

Deep Linking to In-App Resources

Although Appboy can handle standard deep links (such as website urls, Android uris, etc.) out of the box, creating custom deep links requires additional Manifest setup.

See Android’s documentation on “Deep Linking” to In-App Resources

In-App Messaging

In-App Message Types

There are four types of in-app messages: slideup, modal, full, and custom HTML. All in-app messages implement Appboy.Models.IInAppMessage.cs, and modal and full in-app messages additionally implement Appboy.Models.IInAppMessageImmersive.cs. These interfaces provide ways in which you can interact with or customize Appboy’s in-app messages.

For more information, see Appboy.Models.InAppMessageBase and Appboy.Models.InAppMessageImmersiveBase.

Customization

Custom in-app messages can be handled in Unity via Appboy’s InAppMessage models.

Logging Clicks and Impressions

In-App Message Body

Clicks and impressions must be manually logged for in-app messages handled in Unity. You can use the LogClicked() and LogImpression() methods defined in Appboy.Models.IInAppMessage.

In-App Message Buttons

Button clicks can be logged by calling the LogButtonClicked(buttonID(int)) method in Appboy.Models.IInAppMessageImmersive. The ButtonID can be retrieved from Appboy.Models.InAppMessageButton.

For more information, refer to Appboy.Models.InAppMessageImmersiveBase.

Customizing Display Behavior

Dismissal Behavior

You can customize in-app message dismissal behavior by setting the in-app message’s InAppDismissType property to either DismissType.AUTO_DISMISS or DismissType.SWIPE.

For more information, see Appboy.Models.InAppMessage.IInAppMessage and Appboy.Models.DismissType.

Slideup Behavior

For slideup in-app messages, you can set in-app messages to slide from the top or bottom by setting the in-app message’s SlideupAnchor property to SlideFrom.TOP or SlideFrom.BOTTOM.

For more information, see Appboy.Models.InAppMessage.InAppMessageSlideup and Appboy.Models.SlideFrom.

Customizing Click Behavior

In-App Messages

To set the in-app click action, you can call SetInAppClickAction() and pass in ClickAction.NEWS_FEED or ClickAction.NONE, which will redirect to the News Feed or do nothing, respectively.

Alternatively, you can set the click action to redirect to a URI by calling

SetInAppClickAction(ClickAction.URI, "https://www.appboy.com");

For more information, see Appboy.Models.InAppMessage.IInAppMessage and Appboy.Models.ClickAction.

In-App Message Buttons

You can also set the click action on an in-app message button via the SetButtonClickAction() methods on Appboy.Models.InAppMessageButton:

SetButtonClickAction(ClickAction.NEWS_FEED);

SetButtonClickAction(ClickAction.URI, "https://www.appboy.com");

Customizing Appearance

While the iOS SDK supports NUI theming for in-app messages, it is not recommended to use NUI theming with Unity. Instead, custom in-app messages should be handled in Unity, using Appboy’s in-app message models.

Sample Code

For sample implementation code, refer to the InAppMessageReceivedCallback() method in AppboyBindingTester.cs.

News Feed

Overview of the News Feed Models

  • The News Feed is represented as a Feed object, which has a list of Card objects
  • Various card models extend the base Card object
  • Cards can additionally be grouped by CardCategory

Retrieving the News Feed

To retrieve the News Feed from Appboy, call either of the following methods:

Both methods will notify your News Feed listener and pass the News Feed along to your callback method.

Logging News Feed Analytics

If you wish to log News Feed analytics, you can do so using the following methods.

Logging Feed Displayed

To log a Feed Displayed event whenever a user views the News Feed, use AppboyBinding.LogFeedDisplayed().

Logging Card Impressions

To log a News Feed Card impression and mark the card as viewed, call the LogImpression() method on the associated Card object.

Logging Card Clicks

To log a News Feed Card click, call the LogClick() method on the associated Card object.

Implementation Example

Check out the FeedReceivedCallback implementation in AppboyBindingTester.cs for an implementation example.

Analytics

Setting User IDs

A user ID should be set for each of your users. These should be unchanging and accessible when a user opens the app. Something like a username, or a unique identifier from your database is usually a good reference to use. We strongly recommend providing this identifier. It will allow you to:

  • Track your users across devices and platforms, improving the quality of your behaviorial and demographic data.
  • Import data about your users using our User API from any source.
  • Target specific users with our Messaging API for both general and transactional messages.

Note:If such an identifier is not available, Appboy will assign a unique identifier to your users, but you will lack the capabilities above.

Time Estimate: 3 Minutes

Assigning a User ID

You should make the following call as soon as the user is identified (generally after logging in) in order to set the user id:

AppboyBinding.ChangeUser("YOUR_USER_ID_STRING");

Note: Do not call ChangeUser() when a user logs out. ChangeUser() should only be called when the user logs into the application. Setting ChangeUser() to a static default value will associate ALL user activity with that default “user” until the user logs in again.

Additionally, we recommend against changing the user ID when a user logs out, as it makes you unable to target the previously logged-in user with reengagement campaigns. If you anticipate multiple users on the same device, but only want to target one of them when your app is in a logged out state, we recommend separately keeping track of the user ID you want to target while logged out and switching back to that user ID as part of your app’s logout process.

Automatic Preservation of Anonymous User History

Identification Context Preservation Behavior
User has not been previously identified Anonymous history is merged with user profile upon identification
User has been previously identified in-app or via API Anonymous history is not merged with user profile upon identification

Additional Notes and Best Practices

Please note the following:

  • If your app is used by multiple people, you can assign each user a unique identifier to track them.
  • Once a user ID has been set, you cannot revert that user to an anonymous profile
  • Do Not change the user ID upon a user “log out”.
    • Doing so separates the device from the user profile. You will be unable to target the previously logged out user with re-engagement messages. If you anticipate multiple users on the same device, but only want to target one of them when your app is in a logged out state, we recommend separately keeping track of the user ID you want to target while logged out and switching back to that user ID as part of your app’s logout process. By default, only the last user that was logged in will receive push notifications from your app.
  • Switching from one identified user to another is a relatively costly operation.
    • When you request the user switch, the current session for the previous user is automatically closed and a new session is started. Furthermore, Appboy will automatically make a data refresh request for the news feed, slideup and other Appboy resources for the new user.
  • Note: If you opt to use a hash of a unique identifier as your userID take care to ensure that you’re normalizing the input to your hashing function.
    • e.g. If you’re going to use a hash of an email address, ensure that you’re stripping leading and trailing whitespace from the input, and taking localization problems into account.

Logging Custom Events

You can record custom events in Appboy to learn more about your app’s usage patterns and to segment your users by their actions on the dashboard.

Before implementation, be sure to review examples of the segmentation options afforded by Custom Events vs. Custom Attributes vs Purchase Events in our Best Practices section.

Time Estimate: 5 Minutes

AppboyBinding.LogCustomEvent("event name");

Appboy also supports adding metadata about custom events by passing a Dictionary of event properties:

AppboyBinding.LogCustomEvent("event name", properties(Dictionary<string, object>));

Note: In versions of the SDK prior to 1.8.0, the properties Dictionary only supports string values.

REST API

You can also use our REST API to record events. Refer to the user API documentation for details.

Setting Custom Attributes

Appboy provides methods for assigning attributes to users. You’ll be able to filter and segment your users according to these attributes on the dashboard.

Before implementation, be sure to review examples of the segmentation options afforded by Custom Events vs. Custom Attributes vs Purchase Events in our Best Practices section.

Time Estimate: 5 Minutes

Assigning Standard User Attributes

To assign user attributes, you need to call the appropriate method on the AppboyBinding object. The following is a list of built-in attributes that can be called using this method.

First Name

AppboyBinding.SetUserFirstName("first name");

Last Name

AppboyBinding.SetUserLastName("last name");

User Email

AppboyBinding.SetUserEmail("email@email.com");

Note: It’s still valuable to set email addresses even if you’re not sending emails through Appboy. Email makes it easier to search for individual user profiles and troubleshoot issues as they arise.

User Bio

Note: AppboyBinding.SetUserBio() has been deprecated.

Gender

AppboyBinding.SetUserGender(Appboy.Models.Gender.Male or Appboy.Models.Gender.Female);

Birth Date

AppboyBinding.SetUserDateOfBirth("year(int)", "month(int)", "day(int)");

User Country

AppboyBinding.SetUserCountry("country name");

User Home City

AppboyBinding.SetUserHomeCity("city name");

User Email Subscription

AppboyBinding.SetUserEmailNotificationSubscriptionType(AppboyNotificationSubscriptionType.OPTED_IN or AppboyNotificationSubscriptionType.SUBSCRIBED or AppboyNotificationSubscriptionType.UNSUBSCRIBED);

Note: AppboyBinding.SetUserIsSubscribedToEmails() has been deprecated. Please use AppboyBinding.SetUserEmailNotificationSubscriptionType() instead.

User Push Subscription

AppboyBinding.SetUserPushNotificationSubscriptionType(AppboyNotificationSubscriptionType.OPTED_IN or AppboyNotificationSubscriptionType.SUBSCRIBED or AppboyNotificationSubscriptionType.UNSUBSCRIBED);

User Phone Number

AppboyBinding.SetUserPhoneNumber("phone number without hyphens");

User Avatar Image URL

AppboyBinding.SetUserAvatarImageURL("URL");

Assigning Custom User Attributes

Beyond the attributes above, Appboy also allows you to define Custom Attributes using a number of different data types: For more information regarding the segmentation options each of these attributes will afford you see our “Best Practices” documentation within this section.

Custom Attribute with a Boolean Value

AppboyBinding.SetCustomUserAttribute("custom boolean attribute key", 'boolean value');

Custom Attribute with an Integer Value

// Set Integer Attribute
AppboyBinding.SetCustomUserAttribute("custom int attribute key", 'integer value');
// Increment Integer Attribute
AppboyBinding.IncrementCustomUserAttribute("key", increment(int))

Custom Attribute with a Double Value

AppboyBinding.SetCustomUserAttribute("custom float attribute key", 'float value');

Note: Appboy treats FLOAT and DOUBLE values exactly the same within our database.

Custom Attribute with a String Value

AppboyBinding.SetCustomUserAttribute("custom string attribute key", "string custom attribute");

Custom Attribute with a Date Value

AppboyBinding.SetCustomUserAttributeToNow("custom date attribute key");
AppboyBinding.SetCustomUserAttributeToSecondsFromEpoch("custom date attribute key", 'integer value');

Custom Attribute with an Array Value

// Setting An Array
AppboyBinding.SetCustomUserAttributeArray("key", array(List), sizeOfTheArray(int))
// Adding to an Array
AppboyBinding.AddToCustomUserAttributeArray("key", "Attribute")
// Removing an item from an Array
AppboyBinding.RemoveFromCustomUserAttributeArray("key", "Attribute")

Note: Dates passed to Appboy must either be in the ISO 8601 format, e.g 2013-07-16T19:20:30+01:00 or in the yyyy-MM-dd'T'HH:mm:ss.SSSZ format e.g 2016-12-14T13:32:31.601-0800

Unsetting a Custom Attribute

Custom Attributes can also be unset using the following method:

AppboyBinding.UnsetCustomUserAttribute("custom attribute key");

Setting a Custom Attribute via the REST API

You can also use our REST API to set user attributes. To do so refer to the user API documentation.

Custom Attribute Value Limits

Custom attribute values have a maximum length of 255 characters; longer values will be truncated.

Setting Up User Subscriptions

To set up a subscription for your users (either email or push), call the functions
AppboyBinding.SetUserEmailNotificationSubscriptionType() or AppboyBinding.SetPushNotificationSubscriptionType(), respectively. Both of these functions take the parameters Appboy.Models.AppboyNotificationSubscriptionType as arguments. This type has three different states:

Subscription Status Definition
OPTED_IN Subscribed, and explicitly opted in
SUBSCRIBED Subscribed, but not explicitly opted in
UNSUBSCRIBED Unsubscribed and/or explicitly opted out

Note: No explicit opt-in is required by Windows to send users push notifications. When a user is registered for push, they are set to SUBSCRIBED rather than OPTED_IN by default. For more information on implementing subscriptions and explicit opt-ins, visit the topic on Appboy Academy.

  • EmailNotificationSubscriptionType
    • Users will be set to SUBSCRIBED automatically upon receipt of a valid email address. However, we suggest that you establish an explicit opt-in process and set this value to OPTED_IN upon receipt of explicit consent from your user. See Appboy Academy for details.
  • PushNotificationSubscriptionType
    • Users will be set to SUBSCRIBED automatically upon valid push registration. However, we suggest that you establish an explicit opt-in process and set this value to OPTED_IN upon receipt of explicit consent from your user. See Appboy Academy for details.

Note: These types fall under Appboy.Models.AppboyNotificationSubscriptionType.

Sample Code

Email Subscription:

AppboyBinding.SetUserEmailNotificationSubscriptionType(AppboyNotificationSubscriptionType.OPTED_IN);

Push Notification Subscription:

AppboyBinding.SetUserPushNotificationSubscriptionType(AppboyNotificationSubscriptionType.OPTED_IN);

Logging Purchases

Record in-app purchases so that you can track your revenue over time and across revenue sources, as well as segment your users by their lifetime value.

Appboy supports purchases in multiple currencies. Purchases that you report in a currency other than USD will be shown in the dashboard in USD based on the exchange rate at the date they were reported.

Before implementation, be sure to review examples of the segmentation options afforded by Custom Events vs. Custom Attributes vs Purchase Events in our Best Practices section.

Time Estimate: 3-5 Minutes

To use this feature, add this method call after a successful purchase in your app:

AppboyBinding.LogPurchase("productId", "currencyCode", price(decimal));

The above method logs a purchase with a quantity of 1. If you would like to pass in a different quantity, you can call this method:

AppboyBinding.LogPurchase("productId", "currencyCode", price(decimal), quantity(int));

Quantity must be less than or equal to 100. Appboy also supports adding metadata about purchases by passing a Dictionary of purchase properties:

AppboyBinding.LogPurchase("productId", "currencyCode", price(decimal), quantity(int), properties(Dictionary<string, object>));

Note: In versions of the SDK prior to 1.8.0, the properties Dictionary only supports string values.

Currency Codes

Supported currency symbols are listed below. Any other provided currency symbol will result in a logged warning and no other action taken by the SDK.

  • USD, AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MTL, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XCD, XDR, XOF, XPD, XPF, XPT, YER, ZAR, ZMK, ZMW and ZWL.

Sample Code

AppboyBinding.LogPurchase("product ID", "USD", 12.5m);

REST API

You can also use our REST API to record purchases. Refer to the user API documentation for details.

Advanced Use Cases

Customizing the Unity Package

You can choose to customize and export the Appboy Unity package using the provided scripts.

  1. Clone the Appboy Unity SDK Github project:

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

  2. From the root appboy-unity-sdk directory, run ./scripts/generate_package.sh to export the Unity package.
    • Adding the --nodeps command line option will bundle the Unity package without the SDWebImage iOS SDK dependency. Please note that SDWebImage is required for proper functionality of Appboy’s In-App Messaging and News Feed features on iOS.
    • Note: Unity CANNOT be open while running generate_package.sh, or the script will fail.
  3. The package will be exported to unity-package/Appboy.unitypackage.
    • If you generated the package with the --nodeps option, it will be named Appboy-nodeps.unitypackage.
  4. In the Unity Editor, import the package into your Unity project by navigating to Assets > Import Package > Custom Package.
  5. (Optional) Deselect any files you do not wish to import.

You can customize the exported Unity package by editing both generate_package.sh and the export script located at Assets/Editor/Build.cs.

Troubleshooting

File Could Not Be Read Errors

Errors resembling the following may be safely ignored. Apple software uses a proprietary PNG extension called CgBI, which Unity does not recognize. These errors will affect neither your iOS build nor proper display of the associated images in the Appboy bundle.

Could not create texture from Assets/Plugins/iOS/AppboyKit/Appboy.bundle/...png: File could not be read