SDK Integration

Integrating the Appboy Windows Universal Unity Plugin will provide you with analytics functionality, as well as push message and In-App message functionality. Furthermore, it will provide user with Xaml controls for our News Feed and Feedback controls for custom integrations.

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

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: Cloning the Unity SDK

Clone the Appboy Unity SDK Github project

$ 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/WindowsUniversalUnityAdapter.dll /<your-project>/Assets/Plugins
YES Plugins/Metro /<your-project>/Assets/Plugins/Metro

Step 3: Ensuring the plugin was built correctly and completing integration

  1. Build your Unity project for the Windows Store platform. Ensure that the DLLs from the Assets/Plugins/Metro folder and WindowsUniversalUnityAdapter.dll were copied to your project.
  2. Continue to do integration normally for a Windows Universal project. Note that we provide native unity APIs under the AppboyBinding namespace for User Data Collection methods in Unity, as well as native Unity methods for submitting feedback and requesting slideup refreshes. See AppboyBinding.cs for the full list of native methods.

SDK Integration Complete

Push Notifications

Windows Phone 8 push notifications for Unity apps have the same integration instructions as regular Windows Phone 8 apps. Instructions can be found here.

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