Initial SDK Integration

The Appboy SDK will provide you with an API to report information to be used in analytics, segmentation, and engagement, as well as the ability to register users for push and receive notification.

Note: The Windows Universal SDK is also compatible with Xamarin Windows Apps.

Time Estimate: 20-30 Minutes

Step 1: Install the SDK via the Nuget Package Manager

The Windows Universal SDK is installed via the Nuget Package Manager. To install the Appboy Windows SDK via Nuget:

  1. Right click on the project file
  2. Click on “Manage Nuget Packages”
  3. Click “Online” in the dropdown menu on the left
  4. Search in “Nuget.org” for “Appboy”
  5. Click on the “AppboyPlatform.Universal.Release” Nuget Package and click Install

Note: The Windows Universal Library should be used for all Windows 8.1, Windows Phone 8.1, and UWP applications.

Step 2: Creation and Configuration of AppboyConfiguration.xml

Create a file called AppboyConfiguration.xml in the root directory of your project and add the following code snippet into that file:

    <?xml version="1.0" encoding="utf-8"?>
    <AppboyConfig>
        <ApiKey>YOUR_API_KEY_HERE</ApiKey>
    </AppboyConfig>

Note: Be sure to update YOUR_API_KEY_HERE with your API key which can found on the App Settings page within the Appboy Dashboard.

Once you’ve added that snippet, be sure to modify the following file properties for AppboyConfiguration.xml

  1. Set the Build Action to Content
  2. Set Copy to Output Directory to Copy Always

Step 3: Configuring Package.appxmanifest

Within the “Capabilities tab, ensure Internet (Client) is checked. Internet_Client

Step 4: Editing your App class

  • Add the following to the usings of your App.xaml.cs file:
using AppboyPlatform.PCL.Managers;
using AppboyPlatform.Universal;
using AppboyPlatform.Universal.Managers.PushArgs;
  • Call the following within your OnLaunched lifecycle method:
Appboy.SharedInstance.OpenSession();
  • Call the following within your OnSuspending lifecycle method:
Appboy.SharedInstance.CloseSession();

Basic SDK Integration Complete

Appboy should now be collecting data from your application. Please see the following sections on how to log attributes, events, and purchases to our SDK and how instrument push messaging.

NOTE: If you are using the Appboy Unity project in the same app, you may have to fully qualify calls to Appboy as “AppboyPlatform.Universal.Appboy”

Push Notifications

Integration

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.

Time Estimate: 7 Minutes

Step 1: Configure Your Application For PUsh

Ensure that in your Package.appxmanifest file, the following settings are configured as noted below:

Within the “Application” tab, ensure that Toast Capable is set to YES. ![Toast_Capable][19]

Step 2: Configure the Appboy Dashboard

  1. Find your SID and Client Secret
  2. Within the App Settings page of the Appboy dashboard, add the SID and Client Secret in your app settings.

Windows SID Dashboard

Step 3: Creating Event Handlers

To listen to events that are fired when the push is received and activated (clicked by user), create event handlers and add them to the PushManager events:

  • Appboy.SharedInstance.PushManager.PushReceivedEvent += YourPushReceivedEventHandler;
  • Appboy.SharedInstance.PushManager.ToastActivatedEvent += YourToastActivatedEventHandler;

Your event handlers should have the signatures:

  • void YourPushReceivedEventHandler(PushNotificationChannel sender, AppboyPushNotificationReceivedEventArgs args);
  • void YourToastActivatedEventHandler(ToastNotification sender, AppboyToastActivatedEventArgs args);

Step 4: Deep Linking From Push Into Your App

Deep links are used to navigate users from outside your application directly to a certain screen or page in your application. Typically this is done by registering a url scheme (e.g. myapp://mypage) with an operating system and registering your application to handle that scheme; when the OS is asked to open a url of that format it transfers control to your application.

WNS deep link support differs from this as it launches your application with data about where to send the user. When WNS push is created it can include a launch string that is passed through to your application’s OnLaunched when the push is clicked and your appplication is opened. We already use this launch string to do campaign tracking, and we give users the ability append their own data that can be parsed and used to navigate the user when the app is launched.

If you specify an extra launch string in the Dashboard or the REST API, it will be added to the end of the launch string that we create, after the key “abextras=”. So, an example launch string might look like ab_cn_id=_trackingid_abextras=page=settings, in which you specified page=settings in the extra launch string parameter so you can parse it and navigate the user to the settings page.

Part 2: Deep Linking Through the Dashboard

Specify the string to be appended to the launch string in the “Additional Launch String Configuration” field in push notification settings.

Deep_Link_Dash_Example

Part 3: Deep Linking through the REST API

Appboy also allows sending deep links through the REST API. Windows Universal Push objects accept an optional extra_launch_string parameter. See the Windows Universal Push Object Example.

Analytics

Session Tracking

The Appboy SDK reports session data that is used by the Appboy dashboard to calculate user engagement and other analytics integral to understanding your users. Based on the below session semantics, our SDK generates “start session” and “close session” data points that account for session length and session counts viewable within the Appboy Dashboard.

Session Lifecycle

Our Windows integration logs session opens when the app is launched and logs session closes when the application is closed.

Note: If you need to force a new session, you can do so by changing users.

Testing Session Tracking

To detect sessions via your user, find your user on the dashboard and navigate to “App Usage” on the user profile. You can confirm that session tracking is working by checking that the “Sessions” metric increases when you would expect it to.

test_session

Setting User IDs

User IDs should be set for each of your users. These should be unchanging and accessible when a user opens the app. A database ID or a hashed email address/username is usually a good reference to use. We strongly recommend providing this identifier as 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 Data API.
  • 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. You should avoid setting User IDs for users for whom you lack a unique identifier that is tied to them as an individual. Passing a device identifier offers no benefit versus the automatic anonymous user tracking Appboy offers by default.

Note: These User IDs should be private and not easily obtained (e.g. not a plain email address or username).

Time Estimate: 3 Minutes

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

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

User ID Integration Best Practices & Notes

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.

Time Estimate: 5 Minutes

All events are be logged by using the EventLogger, which is a property exposed in IAppboy. To obtain a reference to the EventLogger, call Appboy.SharedInstance.EventLogger. You can use the following methods to track important user actions and custom events:

bool LogCustomEvent(string YOUR_EVENT_NAME)

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

User attributes can be assigned to the current IAppboyUser. To obtain a reference to the current IAppboyUser, call Appboy.SharedInstance.AppboyUser

The following attributes should be defined as properties of the IAppboyUser:

  • FirstName
  • LastName
  • Email
  • Bio
  • Gender
  • DateOfBirth
  • Country
  • HomeCity
  • PhoneNumber
  • FacebookData
  • TwitterData

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.

Example Implementation

Appboy.SharedInstance.AppboyUser.FirstName = "User's First Name"

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

bool SetCustomAttribute(STRING_KEY, BOOL_VALUE);

Custom Attribute with an Integer Value

bool SetCustomAttribute(STRING_KEY, INT_VALUE);

Custom Attribute with a Double Value

bool SetCustomAttribute(STRING_KEY, DOUBLE_VALUE);

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

Custom Attribute with a String Value

bool SetCustomAttribute(STRING_KEY, "STRING_VALUE");

Custom Attribute with a Long Value

bool SetCustomAttribute(STRING_KEY, LONG_VALUE);

Custom Attribute with a Date Value

bool SetCustomAttribute(STRING_KEY, "DATE_VALUE");

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

Setting a Custom Attribute with an Array Value

// Setting a custom attribute with an array value
Appboy.SharedInstance.EventLogger.SetCustomAttributeArray("custom_attribute_array_test", testSetArray);
// Adding to a custom attribute with an array value
Appboy.SharedInstance.EventLogger.AddToCustomAttributeArray("custom_attribute_array_test", testAddString);
// Removing a value from an array type custom attribute
Appboy.SharedInstance.EventLogger.RemoveFromCustomAttributeArray("custom_attribute_array_test", testRemString);

Incrementing/Decrementing Custom Attributes

This code is an example of an incrementing custom attribute. You may increment the value of a custom attribute by any positive or negative integer value.

bool IncrementCustomAttribute(STRING_KEY, INCREMENT_INTEGER_VALUE);

Unsetting a Custom Attribute

Custom Attributes can also be unset using the following method:

bool UnsetCustomAttribute(STRING_KEY);

Setting a Custom Atttribute 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.

Managing Notification Subscription Statuses

To set up a subscription for your users (either email or push), you can set the subscription statuses below as properties of the IAppboyUser. Subscription statuses in Appboy have three different states for both Email and Push:

Subscription Status Definition
OptedIn Subscribed, and explicitly opted in
Subscribed Subscribed, but not explicitly opted in
UnSubscribed Unsubscribed and/or explicitly opted out
  • 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 OptedIn upon reciept 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 OptedIn upon reciept of explicit consent from your user. See Appboy Academy for details.

Note: These types fall under AppboyPlatform.PCL.Models.NotificationSubscriptionType

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:

Purchases are logged by using the EventLogger, which is a property exposed in IAppboy. To obtain a reference to the EventLogger, call Appboy.SharedInstance.EventLogger.

bool LogPurchase(string productId, string currencyCode, decimal price)

REST API

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

Social Data Tracking

Unlike the Appboy iOS SDK, the Appboy Windows SDK does not automatically collect Facebook and Twitter data. However, it’s possible to add social media data to an Appboy user’s profile from the Windows SDK as well:

  • Obtain social media data within your application via the Facebook SDK and Twitter APIs.
  • Initialize Facebook and Twitter User objects with social media data and pass them to Appboy.

Social Network Data Constructors

FacebookUser(
  string Id,
  string FirstName,
  string LastName,
  string Email,
  // mm/dd/yyyy format.
  string Birthday,
  string Bio,
  FacebookLocation LocationObject,
  // "m" or "f".
  string Gender,
  List<FacebookLike> Likes,
  int NumFriends
)

FacebookLocation(
  string CityName
)

FacebookLike(
  // The name of a page the user likes.
  string Like
)

TwitterUser(
  string Description,
  int FollowersCount,
  int FriendsCount,
  int StatusesCount,
  // Twitter's unique id for the user.
  int Id,
  string Name,
  string ProfileImageURL,
  // The user's handle.
  string ScreenName
)

To pass data retrieved from social networks to Appboy, you’ll create a new FacebookUser or TwitterUser and then pass them to the method Appboy.SharedInstance.AppboyUser.SetFacebookData()/Appboy.SharedInstance.AppboyUser.SetTwitterData(). For example:

Twitter

var twitterUser = new TwitterUser {
  Description = "description",
  FollowersCount = 10,
  FriendsCount = 20,
  StatusesCount = 150,
  Id = 1000000,
  Name = "Name",
  ProfileImageURL = "https://si0.twimg.com/profile_images/00000/00000.jpeg",
  ScreenName = "handle"
};

Appboy.SharedInstance.AppboyUser.SetTwitterData(twitterUser);

Facebook

// Build a list of pages the user likes.
List likes = new List();
var like = new FacebookLike {
  Like = "Page Name"
};
likes.Add(like);

// Specify the user's city in a FacebookLocation object.
var location = new FacebookLocation {
  CityName = "City"
};

// Populate the FacebookUser object.
var facebookUser = new FacebookUser {
  Id = "100000",
  FirstName = "FirstName",
  LastName = "LastName",
  Email = "email@email.com",
  Birthday = "04/13/1990",
  Bio = "bio",
  LocationObject = location,
  Gender = "m",
  Likes = likes,
  NumFriends = 500
};

Appboy.SharedInstance.AppboyUser.SetFacebookData(facebookUser);

Location Tracking

  1. Ensure that within your Package.appxmanifest file the following option is checked:
    • Location
  2. If you want to turn off automatic location tracking, set <DisableLocationCollection>false</DisableLocationCollection> to true in your AppboyConfiguration.xml