Button is the mobile commerce platform that maximizes the value of every tap. Through higher-converting technology, Button embeds commerce inside publisher apps so that brands can grow their mobile business.
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 Events 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.
For a complete integration with Button, you will need the following:
btn_ref
for the session as an integration attribute.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 (login required). For more information on setting up a new mParticle connection, see the Platform Guide.
Setting Name | Data Type | Default Value | Description |
---|---|---|---|
Application ID | string |
A Button specified unique key for each of your device types. |
Button requires the reporting of eCommerce orders via mParticle’s eCommerce APIs. mParticle’s integration with the Button API has similar requirements as documented by Button.
Follow the mParticle integration guides for your platform to learn how to collect eCommerce events:
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:
The following are optional:
Individual Products: An array of line item details of your order, including:
Although the iOS and Android SDKs will automatically populate the button referrer token for you, on Web you will need to parse the referrer token from the URL and set it as an integration attribute, using mParticle’s setIntegrationAttribute()
method.
mParticle.setIntegrationAttribute(
"1022", // the mParticle module ID for Button
"srctok-XXX" // the Button referrer token
)
Using the same mParticle client or server APIs documented above, use the REFUND
product action to signify a cancellation.
The following parameters are required:
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:
btn_ref
within each Application State Transition message, specifically within the “launch referrer” property.In partnership with Button, mParticle also provides optional, add-on “kit” libraries for iOS and Android. The libraries serve two purposes:
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.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:
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.
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();
}
Was this page helpful?