Appboy Destination

Segment makes it easy to send your data to Appboy (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Appboy in the format they understand. Learn more about how to use Appboy with Segment.

Our Appboy destination code is open-source on GitHub if you want to check it out: iOS, Android, Web, Server.

Getting Started

Once the Segment library is integrated, toggle Appboy on in your Segment destination catalog, and add your App Group Identifier which you can find in the Appboy Dashboard under App Settings > Developer Console.

You can integrate Appboy via a server side or mobile destination (ios or andriod). If you are interested in using Appboy’s push notifications product, we recommend the mobile destinations.

Appboy supports the identify, track, page, and group methods.

Identify

When you identify a user, we’ll pass that user’s information to Appboy with userId as Appboy’s External User ID. Segment’s special traits recognized as Appboy’s standard user profile fields (in parentheses) are:

firstName (first_name)
lastName (last_name)
birthday (dob)
avatar (image_url)
address.city (home_city)
address.country (country)
gender (gender)

All other traits (except their reserved keys) will be sent to Appboy as custom attributes. You can send arrays as trait values but not nested objects.

Track

When you track an event, we will send that event to Appboy as a custom event. Note that Appboy does not support arrays or nested objects for custom track event properties.

Note: We will remove the following custom properties as they are reserved by Appboy and the message will be rejected if you tried to send any of them:

time
product_id
quantity
event_name
price
currency

To send ecommerce data, you should follow the section below!

Order Completed

When you track an event with the name Order Completed using the e-commerce tracking API, we will send the products you’ve listed to Appboy as purchases.

Group

When you call group, we will send a custom attribute to Appboy with the name ab_segment_group_<groupId>, where <groupId> is the group’s ID in the method’s parameters. For example, if the group’s ID is 1234, then the custom attrubite name will be ab_segment_group_1234. The value of the custom attribute will be set to true.

Page

If you have enabled Track All Pages or Track Only Named Pages in your Integraion Settings, we’ll send page calls to Appboy as a custom event.

Android

Integrating

1) In your top-level project build.gradle put

maven { url "http://appboy.github.io/appboy-android-sdk/sdk" }

as a repository under allprojects -> repositories.

2) Add the Appboy Segment destination dependency to your app build.gradle:

compile 'com.appboy:appboy-segment-integration:+'

We recommend using the latest version on Maven since it will contain the most up to date features and bug fixes.

Note: Our group Id is com.appboy and not com.segment.analytics.android.integrations.

3) Next, declare Appboy’s destination in your Analytics instance:

Analytics analytics = new Analytics.Builder(context, "YOUR_WRITE_KEY_HERE")
  .use(AppboyIntegration.FACTORY)
  ...
  .build();

Integrating Push

Please follow Appboy’s push notification documentation here.

Note that if you don’t have Appboy automatically register for push (i.e. you pass the push token from an FCM or manual GCM registration) you need to ensure you call registerAppboyPushMessages after Appboy is initialized.

You can do this by checking if Appboy is initialized before trying to pass the push token, and waiting for initializing to set if not.

You can do this in an onIntegrationReady method:

String appboyPushToken; 
bool appboyInitialized = false;

…

// When you get the push token 
String receivedToken;

appboyPushToken = recievedToken; 
if (appboyInitialized) { 
  Appboy.getInstance(getContext()).registerAppboyPushMessages(appboyPushToken); 
}

….

Analytics.with(this).onIntegrationReady(Appboy, new Callback() { 
  @Override public void onIntegrationReady(Object integration) { 
    appboyInitialized = true; 
    if(appboyPushToken != null) { 
      Appboy.getInstance(getContext()).registerAppboyPushMessages(appboyPushToken); 
    } 
  } 
});

In-App Messages

No further action is required to integrate in-app messages, which are registered for and requested by default by our Appboy Segment destination.

Sample App

Appboy has created a sample Android application that integrates Appboy via Segment. Check it out at the Github repo.

Non-Segment Functionality

Appboy functionality that isn’t integrated with Segment is supported via the use of our standard Android SDK API. For more information, visit our documentation, Javadoc, and Github repo.

Note that you should gate Appboy functionality that is accessed directly via Appboy API methods based on whether the Segment Appboy destination is active and enabled. That way, when Appboy is turned off via Segment, all Appboy functionality is turned off.

For an example of gating Appboy functionality based on whether Appboy Segment is enabled, see our sample application class, which stores the enabled state, and sample activity class, which checks the enabled state before displaying the Appboy News Feed or the Appboy feedback fragment.

iOS

Integrating

1) Add the Appboy Segment Pod to your Podfile:

pod 'Segment-Appboy'

We recommend using the latest version on CocoaPods since it will contain the most up to date features and bug fixes.

2) Next, declare Appboy’s destination in your app delegate instance:

  SEGAnalyticsConfiguration *config = [SEGAnalyticsConfiguration configurationWithWriteKey:@"YOUR_WRITE_KEY_HERE"];
  [config use:[SEGAppboyIntegrationFactory instance]];
  [SEGAnalytics setupWithConfiguration:config];

Here is a sample project which shows how to integrate the above.

Integrating Push

1) Follow the directions to register for push at: https://segment.com/docs/libraries/ios/

2) Add the following to your application:didFinishLaunchingWithOptions

[[SEGAppboyIntegrationFactory instance] saveLaunchOptions:launchOptions];

3) In your application’s application:didReceiveRemoteNotification: method, add the following:

[[SEGAnalytics sharedAnalytics] receivedRemoteNotification:userInfo];

4) If you integrated the application:didReceiveRemoteNotification:fetchCompletionHandler: in your app, add the following to that method:

if ([Appboy sharedInstance] == nil) {
  [[SEGAppboyIntegrationFactory instance] saveRemoteNotification:userInfo];
}

5) If you implemented handleActionWithIdentifier:forRemoteNotification:, add the following to that method:

 if ([Appboy sharedInstance] == nil) {
    [[SEGAppboyIntegrationFactory instance] saveRemoteNotification:userInfo];
  }

In-App Messages

No further action is required to integrate in-app messages, which are registered for and requested by default by our Appboy Segment destination.

Sample App

Appboy has created a sample iOS application that integrates Appboy via Segment. Check it out at the Github repo.

Non-Segment Functionality

Appboy functionality that isn’t integrated with Segment is supported via the use of our standard iOS SDK API. For more information, visit our documentation, Full Classes List, and Github repo.

Enable IDFA collection in Appboy

To enable IDFA collection in Appboy, please add following lines to your Podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      if target.name == "Appboy-iOS-SDK"
        target.build_configurations.each do |config|
          config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
          '$(inherited)', 'ABK_ENABLE_IDFA_COLLECTION']
          end
      end
    end
  end
end

Purchases

To ensure that ecommerce events populate in Appboy, you must be sure to provide the following required values:

A userId
A product_id
A price

These values can be passed into the products array like so:

      products: [
        {
          product_id: '1234',
          name: 'Bag',
          category: 'Accessories',
          price: 30.59,
          currency:
          quantity: 1
        }
      ]

Web

If you’d like to style your Push Notifications or In-App Messages, make sure you add the following inside the <head> section of your page:

<link rel="stylesheet" href="https://js.appboycdn.com/web-sdk/1.6/appboy.min.css" />

Push Notifications

1) To support push notifications on Chrome, you’ll need to enable FCM/GCM as well as configure your site. Check out steps one and two here, for detailed instructions on both.

2) Browser Registration. In order for a browser to receive push notifications, you must register it for push by calling:

analytics.ready(function() {
  window.appboy.registerAppboyPushMessages();
});

Note: We recommend placing this snippet outside of your Segment Snippet within your script tag.

Note: This will immediately request push permission from the user.

If you wish to show your own push-related UI to the user before requesting push permission (known as a soft push prompt), you can test to see if push is supported in the user’s browser by calling:

analytics.ready(function() {
  if (window.appboy.isPushSupported()) {
    // Add your push logic
  }
});

Appboy recommends checking to see if this returns true since not all browsers can recieve push notifications. See below for instuctions on setting up a soft push prompt using Appboy In-App Messages.

If you’d like to unsubscribe a user, you can do so by calling:

analytics.ready(function() {
  window.appboy.unregisterAppboyPushMessages();
});

3) Set your GCM/FCM server API key and SenderID on the Appboy dashboard. You can find more details for this here.

4) To support push notifications on Safari, add your Website Push ID into your Appboy Destination Settings and we’ll send it for you when we initialize the Appboy Web SDK. To get your Website Push ID, follow the first two bullet points in these instructions.

Soft Push Prompts

1) Follow step one to create a “Prime for Push” in-app messaging Campaign on the Appboy dashboard.

2) Disable your Automatically Send In-App Messages Destination setting. By default, it is enabled when you enable the Appboy destination.

3) Add the following snippet to your site:

analytics.ready(function() {
  window.appboy.subscribeToNewInAppMessages(function(inAppMessages) {
    var message = inAppMessages[0];
    if (message != null) {
      var shouldDisplay = true;

      if (message instanceof appboy.ab.inAppMessage) {
        // Read the key/value pair for msg-id
        var msgId = message.extras["msg-id"];

        // If this is our push primer message
        if (msgId == "push-primer") {
          // We don't want to display the soft push prompt to users on browsers that don't support push, or if the user
          // has already granted/blocked permission
          if (!appboy.isPushSupported() || appboy.isPushPermissionGranted() || appboy.isPushBlocked()) {
            shouldDisplay = false;
          }
          // Prompt the user when the first button is clicked
          message.buttons[0].subscribeToClickedEvent(function() {
            appboy.registerAppboyPushMessages();
          });
        }
      }

      // Display the message
      if (shouldDisplay) {
        appboy.display.showInAppMessage(message);
      }
    }

    // Remove this message from the array of IAMs and return whatever's left
    return inAppMessages.slice(1);
  });
});

For more details on this snippet, check out the Appboy’s docs here.

Note: We recommend placing this snippet outside of your Segment Snippet within your script tag.

4) When you’d like to display the Soft Push to a user, call:

analytics.ready(function() {
  window.appboy.logCustomEvent("prime-for-push")
});

In-App Messaging

Appboy offers three default In-App Message types: Slideup, Modal, and Full. You can find a detailed explaination of each here as well as instructions on how to set up In-App Messages within Appboy here

Appboy’s In-App Message product allows you to trigger in-app message display as a result of several different event types. By default, all In-App Messages that a user is eligible for are automatically delivered to the user upon a session start event. A new session automatically starts when a user loads your site. If you’d like to force a new session for a user, simply make an identify with the corresponding userId for that user.

If you don’t want your site to immediately display new In-App Messages when they’re received, you can disable automatic display and register your own display subscribers. To do this:

1) Disable your Automatically Send In-App Messages Destinations setting. By default, it is enabled when you enable the Appboy destination.

2) Create your subscriber by calling:

analytics.ready(function() {
  window.appboy.subscribeToNewInAppMessages(function(inAppMessages) {
    // Display the first in-app message. You could defer display here by pushing this message to code within in your own application.
    // If you don't want to use Appboy's built-in display capabilities, you could alternatively pass the in-app message to your own display code here.
    window.appboy.display.showInAppMessage(inAppMessages[0]);

    // Return an array with any remaining, unhandled messages to appboy's internal queue.
    // These will be part of the inAppMessages param the next time this subscriber is invoked.
    return inAppMessages.slice(1);
  });
});

The inAppMessages parameter will be an array of appboy.ab.InAppMessage subclass or appboy.ab.ControlMessage objects, each of which has various lifecycle event subscription methods.

FAQ

Why do you have to use .ready()?

You need to wrap the Appboy snippets in .ready() to ensure that Appboy’s Web SDK native objects are available and ready for use. For a more detailed explanation of .ready(), check out this community post.

Supported Sources and Connection Modes

	Web	Mobile	Server
📱 Device-based	✅	✅
☁️ Cloud-based	✅	✅	✅

To learn more about about Connection Modes and what dictates which we support, see here.

We offer an optional Cloud-based Connection Mode for Web data with Appboy. As a reminder, this removes the Appboy javascript library from your site, improving performance. However, there are a few disparities between the Cloud-based and Device-based connection modes to keep in mind brefore enabling it in the Segment app. When you enable the Cloud-based destination mode, here’s what happens:

You will no longer be able to use the following Appboy Web features: Push Notifications, Soft Push Prompts, and In-App Messaging.
You will no longer be able to use the following Appboy Mobile features: Push Notifications and In-App Messaging.

Segment offers an optional Device-based Connection Mode for Mobile data with Appboy. If you’d like to use those features that require client-based functionality, follow the steps above to ensure you have packaged the Appboy SDK with Segment’s.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

App Group Identifier

The App Group Identifier can be found in your Appboy dashboard under App Settings > Developer Console

Custom API Endpoint

If you’ve been assigned an API endpoint by the Appboy team specifically for use with their Mobile or Javascript SDKs, please input that here. It should look something like: sdk.api.appboy.eu. Otherwise, leave this blank.

Appboy Datacenter

Web and Server-Side:Choose your datacenter from either US (default) or EU. Mobile: To use the EU datacenter, enter sdk.api.appboy.eu into the ‘Custom API Endpoint’ setting

Custom REST API Endpoint

If you’ve been assigned an API endpoint by the Appboy team specifically for use with their REST API, please input that here. It should look something like: https://rest.api.custom.endpoint. Otherwise, leave this blank.

Track All Pages

This will send all page calls to Appboy as a Loaded/Viewed a Page event. This option is disabled by default since Appboy isn’t generally used for page view tracking.

Track Only Named Pages

This will send only page calls to Appboy that have a name associated with them. For example, page('Signup') would translate to Viewed Signup Page in Appboy.

Update Existing Users Only

Server Side only: A flag to determine whether to update existing users only, defaults to false

API Key

The API key found in your Appboy dashboard, used to identify your application.

Automatically Send In-App Messages

Web Only: When this is enabled, all In-App Messages that a user is eligible for are automatically delivered to the user. If you’d like to register your own display subscribers or send soft push notifications to your users, make sure to disable this option.

Enable HTML In-App Messages

Web only: Enabling this option will allow Appboy dashboard users to write HTML In-App messages. Check out Appboy’s Documentation for more information on this setting.

Safari Website Push ID

Web Only: To send push notifications on Safari, Appboy needs your Website Push Id. To get your Webite Push ID, check out the first two bullet points here.

If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!