mParticle Integration Guide on
iOS

mParticle Integration Guide

mParticle clients can get access to much of Button’s product functionality through this simple integration guide. Once completed, you will be enabled to receive users from the Button Marketplace.

Features

  • User level tracking for app installs and purchases
  • Post-install deeplinking
  • Supports traffic coming from the mobile web and apps

For access to the full set of Button functionality, see the direct integration path.

Requirements

  • An mParticle SDK integration
  • A Button account
  • An app that supports Universal Links or App Links

Enable the Button/mParticle integration

  1. Fetch your Button Application ID from the Button dashboard.
  2. Follow the mParticle integration steps to configure the Button/mParticle SDK integration.
  3. Add the Button mParticle Kit to your mParticle SDK (steps).

Information Button collects: 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.

Configure Your App For Web Links

Configuring Button Web Links allows you to receive users from the web with Button attribution. After installing, the user will be deep linked to the right content.

  1. Set up your App for Web Links in Button App Setup (no need to complete the SDK integration, just step 1). Note: Under the hood, we've made a Universal Links domain YOUR-DOMAIN.bttn.io. We will send users to your app via this domain.
  2. Configure your app to open Button Web Links by associating this new domain with your app (steps how to do).

Track purchases

  1. Extract the Button tracking token from the mParticle SDK.
  2. Report this token to your server when creating an order or checking out.
  3. POST to Button this token and details of the order.

Call the Button API with the tracking token and order details.

curl https://api.usebutton.com/v1/order \
   -X POST \
   -u button_api_key: \
   -d total=12340 \
   -d currency=USD \
   -d order_id=your_order_id \
   -d btn_ref=the_extracted_tracking_token

After a Button order is created it can be updated or deleted to mimic the status of the order on your side. To update or delete an order you will only need your_order_id and the updated order details. Seven days after the order is created it will be finalized so that it cannot be altered. This duration can be configured and should follow your company's return/cancellation policy. More details can be found on our API docs.

Test it out

Test out your integration to ensure everything is properly configured.

  1. Download the Button Partner App.
  2. Log in with you Button credentials.
  3. See what your Button will look like in other apps.
  4. Click the Button and make a purchase in your app.
  5. Confirm the order details are correct using the test app or on the Button dashboard.
  6. And you're done!

Details for individual steps referenced earlier can be found below.

Steps for mParticle

  1. Follow mParticle's documentation to get the mParticle Core SDK and the Button Kit.
source 'https://github.com/CocoaPods/Specs.git'

use_frameworks!

target '<Your Target>' do
    pod 'mParticle-Apple-SDK', '~> 6.2'
    pod 'mParticle-Button', '~> 6.2'
end
  1. Follow mParticle's documentation to initialize mParticle and the Button Kit.
  2. Import the Button kit header #import "MPKitButton.h" and in your-application:didFinishLaunchingWithOptions: you’ll need to observe the mParticleKitDidBecomeActiveNotification before initializing the mParticle SDK.
#import <mParticle-Apple-SDK/mParticle.h>

- (BOOL)application:(UIApplication *)application
       didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [[NSNotificationCenter defaultCenter] addObserver:self
                                        selector:@selector(handleKitDidBecomeActive:)
                                            name:mParticleKitDidBecomeActiveNotification
                                          object:nil];

   [[MParticle sharedInstance] startWithKey:@"<<<App Key Here>>>"
                                     secret:@"<<<App Secret Here>>>"];

   return YES;
}
  1. In the notification handler, verify the active kit is the Button kit then check for a post-install deeplink. Internally, the Button Kit will make sure this only happens for a fresh install and not for existing users.
- (void)handleKitDidBecomeActive:(NSNotification *)notification {

    NSNumber *kitNumber = notification.userInfo[mParticleKitInstanceKey];
    if ([kitNumber isEqualToNumber:@(MPKitInstanceButton)]) {

        [[MParticle sharedInstance] checkForDeferredDeepLinkWithCompletionHandler:^(NSDictionary<NSString *,NSString *> * _Nullable linkInfo, NSError * _Nullable error) {
            NSString *deferredDeepLink = linkInfo[BTNDeferredDeepLinkURLKey];
            // Handle the deferredDeepLink, if present, and open the relevant content.
            // E.g. [self handleDeepLink:deferredDeepLink];
        }];
    }
}
  1. When reporting a new order to your backend it's important that you provide the Button tracking token so the order can be correctly attributed to the app that sent it. It's also important that you make sure the kit is active before you can access the Button Kit Instance. By the time you’re reporting an order, it should be, but if you need it earlier in the lifecycle of your app you can observe the notification as outlined in steps 3 & 4.

Get the Button tracking token as follows:

// Get the kit instance
MPIButton *button = [[MParticle sharedInstance] kitInstance:@(MPKitInstanceButton)];

// You can now access the tracking token
button.referrerToken

Steps for Button Links

To support Universal Links for the Button domain (to stop any Safari redirecting) you need to add the Button subdomain (yourdomain.bttn.io) 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 applinks:yourapp.bttn.io.

Now, when you run your app and tap a Button Link, it should open in your app.