Initial SDK Integration

Installing the Appboy SDK will provide you with basic analytics functionality as well as a working in-app slideup message with which you can engage your users.

Note: The Windows Universal SDK is also compatible with Xamarin Windows Apps. Note: Appboy has deprecated our Windows Phone 8 SDK. Please contact your Appboy representative if you have questions.

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 “Appboy SDK for Windows Store and Windows Phone 8.1+ Apps” Nuget Package and click Install

Note: The Windows Universal Library is meant for all Windows Store and Windows Phone 8.1+ 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

Implementation Example

See the AppboyConfiguration.xml file in our Windows Sample Application.

Step 3: Configuring Package.appxmanifest

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

  1. Within the “Application” tab, ensure that Toast Capable is set to YES. Toast_Capable

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

Note: These are required capabilities.

Implementation Example

See the Package.appxmanifest file in our Windows Sample Application.

Step 4: Add Appboy UI Libraries

The Appboy Windows SDKs can optionally be integrated without the following UI Libraries and Resource Dictionaries. However, In-App Messaging, the News Feed, and Feedback will be rendered inoperable. Please note that these UI elements are open source and fully customizable. We strongly recommend integration of these features.

Step 5: Editing your app.xaml.cs file

  • 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();

For more information, see the “App.xaml.cs” file within the Windows Sample Applications.

Part 1: Adding the Library to Your Project:

Appboy recommends maintaining a git submodule of the Windows Universal UI Library within your project. To add the submodule use the following command:

git submodule add "git@github.com:Appboy/appboy-windows-universal-ui.git" Externals/AppboyUI.Universal/.

Keeping a git submodule up-to-date requires running git submodule update --init when new versions are available.

Method 2: Directly Adding the Library

If you would prefer to avoid maintaining a git submodule; you may choose to download the code directly from the Windows Universal UI Github Repository.

Part 2: Referencing the Library in Your Project:

Next, you must reference the library within your project:

  • Right Click on your project.
  • Click Add Reference.
  • Select the Appboy Universal UI to add it as a reference in your project.
  • Add the following to the usings of your App.xaml.cs file:
using AppboyUI.Universal.Factories;
using AppboyUI.Universal.Assets.Localization;
using Windows.UI.Xaml.Resources;
  • Call the following within your App Initialization:
CustomXamlResourceLoader.Current = new TranslationResourceProvider();

Step 6: Adding Style Resource Dictionaries

Add a file named AppboyStyles.xaml to the root folder of your app. In it, define a resource dictionary that you can override styles in:

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <!--
    This is the Appboy styles override XAML.
    The default styles for all of the UI controls are defined in the AppboyUI.Universal project in the Assets/Styles/default.xaml file.
    To override a default style, copy over the style element and one or more of the properties.
  -->
  <!--Example: Changing the slideup border color to RED -->
  <!--
  <Style x:Key="Appboy.Slideup.Border" TargetType="Border">
    <Setter Property="BorderBrush" Value="#ff0000"/>
    <Setter Property="BorderThickness" Value="1"/>
  </Style>
  -->
</ResourceDictionary>

Implementation Example

See the AppboyStyles.xaml file in our Windows Sample Application.

Step 7 (Optional): Install Test Apps for Sample Integrations

Appboy provides Test Applications which you may clone, build and run at your convenience to test out our feature set. To install these apps:

  1. Clone the root repository to a local drive with git clone --recursive git@github.com:Appboy/appboy-windows-samples.git
  2. Make sure nuget package restore is enabled for the solution. If it isn’t, run nuget restore TestApp.Universal.csproj
  3. Build the solution and test on your local Windows 8 machine.

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.

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: Set up your Application in the Windows Universal Store

  1. Set up your application in the Windows Universal
  2. Be sure to include your SID and Client Secret in your app

Step 2: Configuring the Appboy Dashboard

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);

Implementation Example

See the following App.xaml.cs file in our Windows Sample Application

Note: Only add these event handlers once per app execution.

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.

Testing

If you’d like to test in-app and push notifications via the command-line, you can send a single notification through the terminal via cURL and the Messaging API. You will need to replace the following fields with the correct values for your test case:

curl -X POST -H "Content-Type: application/json" -d "{\"app_group_id\":\"YOUR_APP_GROUP_ID\",\"external_user_ids\":[\"YOUR_EXTERNAL_USER_ID\"],\"messages\":{\"windows_push\":{\"push_type\":\"toast_text_01\",\"toast_text1\":\"test_title\"}}}" https://api.appboy.com/messages/send

Analytics

Customer Feedback

The Appboy feedback form allows users to submit feedback about your app that is immediately sent to your company’s dashboard.

Time Estimate: 10 Minutes

To use our UI Library implementation of a Feedback form, simply add the following in the root tag of your page:

xmlns:appboy="clr-namespace:AppboyUI.Phone.Controls;assembly=AppboyUI.Phone"

In the page xaml put:

<appboy:Feedback OnCancel="Feedback_OnCancel" AfterSubmit="Feedback_AfterSubmit"/>\

Manual Feedback Collection

The following method will allow you to pass Feedback to Appboy from a form or field within your app. This is perfect for passing feedback from an existing UI element to Appboy. The method will return a boolean which indicates whether or not the feedback was queued for delivery.

  • replyToEmail: The user email address feedback replies will be directed towards.
  • message: The message input by the user. Must be non-null and non-empty.
  • isReportingABug: Flag which indicates whether or not the feedback describes a bug, or is merely a suggestion / question.
Appboy.SharedInstance.SubmitFeedback(replyToEmail, message, isReportingABug);

Note: The result can be determined by examining the IResult. Note: This must be called after the application has been initialized and is able to make network requests. Feedback will appear under the “Feedback” section of the Appboy dashboard.

Third Party Provider Integrations

Appboy has easy integrations with both Desk.com and Zendesk. So long as you are collecting feedback through our ready-made UI or manually using the submitFeedback method, you can pass that feedback through to either third party provider. This will afford you the benefit of having the entire user profile card available to the CSR handling the case, and allow you to segment based upon the number of feedback requests a user has submitted.

To take advantage of these integrations, please visit the “feedback” section within the “app settings” page

Implementation Example

See the following FeedBackPage.xaml file in our Windows Sample Application

Theming the Appboy Feedback UI

You can customize the user interface to fit your app by overriding the default styles in AppboyStyles.xaml within the root directory of your project. The default styles for all of the UI controls are defined in the AppboyUI.Store project in the /Styles/Default.xaml file. To override a default style, copy over the style element and one or more of the properties to your AppboyStyles.xaml file in the root directory of your app.

Example Change {feedback-example}

Changing the Slideup Border Color to RED

<Style x:Key="Appboy.Slideup.Border" TargetType="Border">
  <Setter Property="BorderBrush" Value="#ff0000"/>
  <Setter Property="BorderThickness" Value="1"/>
</Style>

Implementation Example

See the following AppboyStyles.xaml file in our Windows Sample Application

Session Tracking

The Appboy SDK reports session data that is used by the Appboy dashboard to calculate user engagement, retention, 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.

Implementation Example

See the following MiscPage.xaml.cs file in our Windows Sample Application

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.

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

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)
bool LogFeedbackDisplayed()
bool LogFeedDisplayed()
bool LogFeedCardImpression(string cardId)
bool LogFeedCardClick(string cardId)
bool LogSlideupShown()
bool LogSlideupClicked()

Implementation Example

See the following MiscPage.xaml.cs file in our Windows Sample Application

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);

Implementation Example

See the following ProfilePage.xaml.cs file in our Windows Sample Application

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)

Implementation Example

See the following MiscPage.xaml.cs file in our Windows Sample Application

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

Sample Apps

Appboy’s SDKs each come with a sample application within the repository for your convenience. Each of these apps is fully buildable so you can test Appboy features alongside implementing them within your own applications. Testing behavior within your own application versus expected behavior and codepaths within the sample applications is an excellent way to debug any problems you may run into.

Building the Windows Sample Applications

Appboy’s Windows test applications within are within the Appboy Windows Samples Repository. Follow the instructions below to build a fully functional copy of it alongside your project.

  1. Create a new “App Group” and note the production API key.
  2. Clone the root repository to a local drive with git clone --recursive git@github.com:Appboy/appboy-windows-samples.git.
  3. Make sure nuget package restore is enabled for the solution. If it isn’t, run nuget restore TestApp.Phone.csproj.
  4. Replace the API key within the AppboyConfiguration.xml file with the prduction API key from the new App Group you created.
  5. Build the solution and test on a Windows VM.

Note: Push notifications for the Windows test application requires additional configuration. See the Windows Push Documentation for details.