mParticle Integration Guide on

mParticle Integration Guide

mParticle users can integrate Button using our mParticle ButtonKit. Once completed, you will be enabled to receive users from the Button Marketplace. In this guide, we will:

  1. Add the ButtonKit
  2. Hook Up mParticle
  3. Report Orders to Button via mParticle
  4. Report Adjustments and Cancellations to Button
  5. Other Configurations
  6. Test Your Integration

What is a Button integration via mParticle?

For merchants that already work with mParticle, the mParticle SDK provides an option to send orders to Button through your existing partnership with minimal integration work.

If you're unsure if this is the correct integration path for your company, please talk to your Button Partner Success Manager.

The ButtonKit

The ButtonKit provides features on top of the standard mParticle SDK. These features are required to enable Button's linking and affiliation products. They are

  • Post-install deeplinking
  • Automatic user attribution collection

Including the ButtonKit will also include the base mParticle SDK.


Before we begin, you should have the following:

Add the ButtonKit

Import the ButtonKit dependency in your Podfile. You must use a version greater than or equal to 7.4.2 and we recommend using the latest version: ButtonKit SDK Version

source ''


target '<Your Target>' do
    pod 'mParticle-Button', '>= 7.4.2' # Use the latest version from the badge above

Please note that you do not need to import the core mParticle SDK as it is a transitive dependency within the ButtonKit

Initialize the mParticle SDK by following these instructions and set the property onAttributionComplete on MParticleOptions. A copy of your block will be invoked to provide the respective information:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    MParticleOptions *options = [MParticleOptions optionsWithKey:@"<<Your app key>>" secret:@"<<Your app secret>>"];
    options.onAttributionComplete = ^void (MPAttributionResult *_Nullable attributionResult, NSError * _Nullable error) {
        if (error) {
            NSLog(@"Attribution fetching for kitCode=%@ failed with error=%@", error.userInfo[mParticleKitInstanceKey], error);

        NSLog(@"Attribution fetching for kitCode=%@ completed with linkInfo: %@", attributionResult.kitCode, attributionResult.linkInfo);

    [[MParticle sharedInstance] startWithOptions:options];

    return YES;

Our mParticle integration is configured to require your customer IDs, advertising IDs (IDFA, Google AID, Android ID), IP, and user location. We use these in our dashboard and do not share them with anyone. Read more about data Button collects.

Traffic from the App Store can result in users opening your app without any deeplink path or parameters. Button's Deferred Deeplink product closes this gap by recovering the link the user was originally following based on device fingerprinting.

After a fresh install, the user may both have an attributed source, and a destination deep link which needs to be retrieved from the Button API.

Hook Up mParticle

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.

Reporting Orders

To report orders with a mParticle integration, you must use the mParticle SDK to report eCommerce Events

mParticle provides thorough documentation of these methods in their SDK documentation. A merchant can construct MPCommerceEvents in the mParticle SDK via the checkout API or manually. Which method a merchant chooses is not relevant to Button as long as the required fields are included.

Button requires the reporting of a subset of the eCommerce event fields. The taxonomy of fields Button expects is as follows.

A merchant must report a MPCommerceEvent containing

transactionAttributes is an instance of MPTransactionAttributes and must include

products is an array of MPProduct and each element must include

Report Adjustments and Cancellations to Button

Button requires all mParticle integrated merchants to report returns, adjustments, and cancellations via a batch file upload. Please reach out for your Button contact for documentation around this process

Other Configurations

The following subsections - along with the section completed above implementing post-install deeplinking - will enable you for Button's mobile web Publishers.

Configure Button Links

In the Button Dashboard, navigate to "Merchant" > "Apps" & click on the App you want to configure a Button Links domain for. Once on the App details page, click on the "Add a Button Links Domain" button in the "Button Links Domains" section. Simply fill out the details in the popup modal to complete the configuration.

Configure Universal Links

To support Universal Links for the Button domain (to stop any Safari redirecting) add the Button subdomain ( to the Associated Domains Capability. Switch Associated Domains on if it's not already and add your domain to the list of domains registered in the format

Web Links

Test Your Integration

You can test the mParticle side of 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

To test the full Button integration, download our Partner test app from the App Store. This app allows you to mimic a Publisher so you may test the Button flow. Login with your Button Dashboard credentials and you will see any Buttons you have associated with your account. After completing a purchase through the Button flow, you can verify it went through Button here in the Dashboard.

Note: If you do not see any Buttons after logging into the Partner test app, reach out to your Button point of contact and they will populate this for you.