Event Integration

Button connects your app to leading commerce brands, earns you money, and generates user loyalty. mParticle’s Button integration allows merchants to attribute Button campaigns to app installs, website traffic, and eCommerce events.

mParticle automatically sends all app and website install events, eCommerce events, as well as device and user ids to the Button API via a server-side integration. This allows any data to be sent to Button regardless of whether it originated from mParticle’s client-side SDKs or server API. It’s common for mParticle customers to use mParticle’s client SDKs as well as server-api where it makes sense for their infrastructure.

However, the mParticle client SDKs will automatically collect the btn_ref associated with a particular user session. This ID will be sent to Button alongside persistent user cookies and credentials, such that the Button platform can accurately attribute app and site actions to campaigns. For this reason, the Button integration requires the inclusion of the mParticle client SDKs in your apps.

Button Integration Requirements

For a complete integration with Button, you will need the following:

  • Inclusion of the mParticle iOS, Android, and/or Web client SDKs. (required).
  • Inclusion of the mParticle-Button kits for iOS and Android (only required for deep-linking support).
  • Collection of eCommerce purchase events via mParticle (required).
  • Collection of eCommerce cancellations and refunds via mParticle or directly to Button (required).
  • Collection of customer ID via mParticle (optional).
  • Collection of customer email address via mParticle (optional).

Enable the Button Integration

  1. Add the mParticle SDKs to your iOS, Android, and/or Web apps. See the docs for your platform here.

  2. Connect your iOS, Android, and/or web workspaces to Button. You will need to input your Button Application ID, which you can access from your organization’s Button dashboard. For more information on setting up a new mParticle connection, see the Platform Guide.

    Configuration Settings

    Setting Name Data Type Default Value Description
    Application ID string A Button specified unique key for each of your device types (iOS, Android).

Event collection

Button requires the reporting of eCommerce orders via mParticle’s eCommerce APIs. mParticle’s integration with the Button API has similar requirements as documented here by Button.

Follow the mParticle integration guides for your platform to learn how to collect eCommerce events:

  1. iOS SDK
  2. Android SDK
  3. Web SDK
  4. Server API

eCommerce Order Requirements

mParticle will automatically forward all Commerce Event “product action” types to Button, but you should use the PURCHASE product action to signify an order.

The following parameters are required:

  • Total Revenue: Total attributable order value.
  • Currency: Three-letter ISO currency code as specified in ISO 4217
  • Order/Transaction ID: Partner-specified unique order id, treated as an ASCII string. 255 character maximum.
  • btn_ref: mParticle’s client SDKs will automatically collect this value for you based on incoming app links. Work with the Button and mParticle team during your testing process to ensure that your data is being properly attributed to this ID, especially if sending eCommerce orders via mParticle’s server API.

The following are optional:

  • Apple IDFA and Google Advertising ID: These are collected automatically via the mParticle client SDKs, but should be included if known when sending eCommerce data to mParticle via our server API.
  • Customer ID: Set this via mParticle’s user identity APIs or user identity server schema.
  • Customer Email: Set this via mParticle’s user identity APIs or user identity server schema.
  • Individual Products: An array of line item details of your order, including:

    • Product SKU/ID
    • Product revenue
    • Quantity
    • Description
    • Custom attributes

eCommerce Refund Requirements

Using the same mParticle client or server APIs documented above, use the REFUND product action to signify a cancellation.

The following parameters are required:

  • Order/Transaction ID: Partner-specified unique order id, treated as an ASCII string. 255 character maximum.

Test the Integration

You can test the integration by performing the following actions in development mode, and following along in the mParticle live stream. You should see the following as both inbound and outbound data to Button, for each mParticle workspace connection:

  • Application Install
  • Application open from deep link. You can verify that the mParticle SDK automatically collects the btn_ref within each Application State Transition message, specifically within the “launch referrer” property.
  • eCommerce Purchases and Refunds

Button Kit Integration (optional)

In partnership with Button, mParticle also provides optional, add-on “kit” libraries for iOS and Android. The libraries serve two purposes:

  • Surfacing deferred deep linking parameters such that you can deep link or customize the user experience based on campaigns.
  • Surfacing the btn_ref of the current session. Querying for this should generally not be required, as mParticle will automatically send the current btn_ref to the Button API for all events.

Add the kit to your app

mParticle publishes the Button kit as separate iOS and Android libraries which have a transitive dependency on the mParticle core libraries. You can add them to your app by via Cocoapods and Gradle:

# Sample Podfile

source 'https://github.com/CocoaPods/Specs.git'

use_frameworks!

target '<Your Target>' do
    pod 'mParticle-Apple-SDK', '~> 6.15.4'
    pod 'mParticle-Button', '~> 6.15.4'
end
// Sample build.gradle

dependencies {
    // Ensure the Kit version matches that of the mParticle Core SDK that you're using
    compile 'com.mparticle:android-button-kit:4.16.2' 
}

For reference, the source code for the kits is available on Github:

Deferred Deep Linking

The mParticle Android SDK provides a deep link API that you can use to query Button and customize your app experience based on the parameters of deep links. Refer to the deep linking section of the Android and iOS SDKs to learn how to use these APIs. Rather than making direct API calls to the Button SDK, this API let you write integration-agnostic apps that are easier to maintain.

eCommerce and Referrer Token

In some cases, it may be necessary to collect the btn_ref of the current session if present. See the code samples below for how to extract the token, which you can then forward along to your back-end and to Button’s API.

//at the time of a purchase
MPIButton *button = [[MParticle sharedInstance] kitInstance:MPKitInstanceButton];
if (button) {
    //access the token
    button.referrerToken
}
final ButtonKit button = (ButtonKit) MParticle.getInstance().getKitInstance(MParticle.ServiceProviders.BUTTON);
if (button != null) {
    //access the token
    button.getReferrerToken();
}

Read More

See here for Button’s documentation covering app setup, mParticle’s integration, and interacting with the Button API.