eCommerce

The following sections provide an overview for how you can measure commerce-related activity in your apps. mParticle Integrations have varying levels of support for commerce data, some providing no commerce-specific support, while others support very granular measurement of user-product, promotion, and impression interactions. The mParticle platform is designed to be flexible - use the APIs described below to measure the datapoints that you need and mParticle will make sure your data is represented faithfully across all of the integrations that you enable.

Basic

It’s sufficient for many apps to only track a purchase, rather than all of the granular steps before and after. Use a product-based Commerce Event or the Commerce helper-apis to track a simple purchase transaction.

Measuring Transactions

Create the Product(s)

The Product class should be used to represent a physical or virtual good or service. At minimum all products are required to have a name, an ID (or SKU), and a price.

Product product = new Product.Builder("Foo name", "Foo sku", 100.00)
        .quantity(4)
        .build();
var product = Product.Builder("Foo name", "Foo sku", 100.00)
        .quantity(4)
        .build();

Summarize the Transaction

All purchase events are required to specify at least a transaction ID. Create a TransactionAttributes object to specify the ID and other transaction-level properties such as tax and shipping.

//transaction ID required for PURCHASE and REFUND events
TransactionAttributes attributes = new TransactionAttributes("foo-transaction-id")
    .setRevenue(450.00)
    .setTax(30.00)
    .setShipping(20.00);
//transaction ID required for PURCHASE and REFUND events
var attributes = TransactionAttributes("foo-transaction-id")
    .setRevenue(450.00)
    .setTax(30.00)
    .setShipping(20.00);

Log the Transaction

Tracking purchases and transactions is similar to other product events with the exception that an addition TransactionAttributes object is required in order to provide the SDK several key dimensions of the transaction. Just as with the actions described above, you can use the Commerce helper APIs, or manually construct a CommerceEvent.

CommerceEvent event = new CommerceEvent.Builder(Product.PURCHASE, product)
  .transactionAttributes(attributes)
  .build();
MParticle.getInstance().logEvent(event);
CommerceEvent.Builder(Product.PURCHASE, product).run {
    transactionAttributes(attributes)
    build()
}.also {
    MParticle.getInstance().logEvent(it)
}

Advanced

The mParticle platform lets you measure every granular step and interaction users can have with eCommerce products and services.

Class Overview

Commerce Event

The CommerceEvent class is central to mParticle’s eCommerce measurement. Commerce Events can contain many data points but it’s important to understand that there are 3 core variations:

  • Product-based: Used to measure measured datapoints associated with one or more products
  • Promotion-base: Used to measure datapoints associated with internal promotions or campaigns
  • Impression-based: Used to measure interactions with impressions of products and product-listings

Shopping Cart

Several of mParticle integration partners support the notion of a shopping cart and require that a shopping cart state be maintained. To make your life easier, the mParticle SDKs automatically maintain a shopping cart for you against the current user. The shopping cart will maintain its state across application launches, products can be manually added and removed from it, and you can even use it to log CommerceEvents.

MParticleUser user = MParticle.getInstance().Identity().getCurrentUser();
Cart cart = user.getCart();
var user = MParticle.getInstance().Identity().currentUser
var cart = user?.cart

Commerce Helper APIs

The mParticle SDK provides a Commerce API class that interacts with the cart and also provides methods dedicated to certain product actions. This class is aware of how to generate and log simple Commerce Events so you can reduce the boilerplate code in your apps. The methods supported by this class, such as checkout() and purchase() will automatically include the products objects currently contained in the Cart.

Product Events

Product-based Commerce Events can be used to measure all of the steps and actions that a user might perform on their way to making a purchase within an eCommerce-enabled app, such as:

  • tapping and viewing products
  • adding and removing products from a cart or wishlist
  • multistep checkout
  • purchases and refunds

Create the Product(s)

The Product class should be used to represent a physical or virtual good or service. A single Commerce Event can be associated with multiple products. At minimum all products are required to have a name, an ID (or SKU), and a price.

Product product = new Product.Builder("Foo name", "Foo sku", 100.00)
        .quantity(4)
        .build();
var product = Product.Builder("Foo name", "Foo sku", 100.00)
        .quantity(4)
        .build();

Add to Cart Events

Tracking when a user adds a product to their virtual cart can be very valuable - for example to target and message users if they abandon their cart without purchasing. You can use the Cart API to log these events, or manually create a CommerceEvent with the add-to-cart action.

Option 1: Use the Cart API

MParticleUser user = MParticle.getInstance().Identity().getCurrentUser();
Cart cart = user.getCart();
cart.add(product, true);
MParticle.getInstance().Identity().currentUser?.cart?.apply { 
    add(product, true)
}

Option 2: Manually log a CommerceEvent

MParticle mp = MParticle.getInstance();
mp.logEvent(
    new CommerceEvent.Builder(Product.ADD_TO_CART, product).build();
);
var mp = MParticle.getInstance();
mp.logEvent(
    CommerceEvent.Builder(Product.ADD_TO_CART, product).build()
)

Checkout Events

The mParticle SDK provides several APIs to measure the steps of the checkout process. Some integration partners such as Google Analytics allow you to configure the steps of your checkout process for in-depth analysis.

Option 1: Use the Commerce API

//this will log a CommerceEvent with all of the products currently in the cart
mp.Commerce().checkout(1, "Mastercard");

Option 2: Manually log a CommerceEvent

CommerceEvent event = new CommerceEvent.Builder(Product.CHECKOUT, product)
                        .checkoutStep(1)
                        .checkoutOptions("Mastercard")
                        .build();
MParticle.getInstance().logEvent(event);
CommerceEvent.Builder(Product.CHECKOUT, product).run {
    checkoutStep(1)
    checkoutOptions("Mastercard")
    build()
}.also {
    MParticle.getInstance().logEvent(it)
}

Purchase Events

Tracking purchases and transactions is similar to other product events with the exception that an addition TransactionAttributes object is required in order to provide the SDK several key dimensions of the transaction. Just as with the actions described above, you can use the Commerce helper APIs, or manually construct a CommerceEvent.

Create the TransactionAttributes object

//transaction ID required for PURCHASE and REFUND events
TransactionAttributes attributes = new TransactionAttributes("foo-transaction-id")
    .setRevenue(450.00)
    .setTax(30.00)
    .setShipping(20.00);
//transaction ID required for PURCHASE and REFUND events
var attributes = TransactionAttributes("foo-transaction-id")
    .setRevenue(450.00)
    .setTax(30.00)
    .setShipping(20.00);

Option 1: Use the Commerce API

//this will log a CommerceEvent with all of the products currently in the cart
mp.Commerce().purchase(attributes);

Option 2: Manually log a CommerceEvent

CommerceEvent event = new CommerceEvent.Builder(Product.PURCHASE, product)
  .transactionAttributes(attributes)
  .build();
MParticle.getInstance().logEvent(event);
CommerceEvent.Builder(Product.PURCHASE, product).run {
        transactionAttributes(attributes)
        build()
}.also {
    MParticle.getInstance().logEvent(it)
}

Promotion Events

The Promotion class should be used to represent internal offers - such as sales that might be displayed in a banner advertisement. Promotion events are created by specifying a promotion action string, and one or more promotions. When constructing a promotion it’s recommended to specify at least an ID or a name.

Promotion promo = new Promotion()
  .setId("my_promo_1")
  .setCreative("sale_banner_1")
  .setName("App-wide 50% off sale")
  .setPosition("dashboard_bottom");
MParticle.getInstance().logEvent(
  new CommerceEvent.Builder(Promotion.VIEW, promo).build()
);
Promotion().apply {
    id = "my_promo_1"
    creative = "sale_banner_1"
    name = "App-wide 50% off sale"
    position ="dashboard_bottom"
}.let {
    CommerceEvent.Builder(Promotion.VIEW, it).build()
}.let {
    MParticle.getInstance().logEvent(it)
}

Impression Events

Use impressions to represent any time one or more products are displayed on the screen, and optionally specify a name for the location or list in which the products appeared.

Impression impression = new Impression("suggested products list", product);
MParticle.getInstance().logEvent(
  new CommerceEvent.Builder(impression).build()
);
Impression("suggested products list", product).let {
    CommerceEvent.Builder(it).build()
}.let {
    MParticle.getInstance().logEvent(it)
}

API Reference

For a deep dive into all of the specific members, variations, and usage of these APIs, reference the Javadocs included with the SDK or here