Enhanced Ecommerce Tracking

This document provides an overview of how to measure in-app ecommerce related actions and impressions with the Google Analytics SDK v4 for Android.

Overview

Enhanced ecommerce enables the measurement of user interactions with products across the user's shopping experience, which include product impressions, product clicks, viewing product details, adding a product to a shopping cart, initiating the checkout process, transactions, and refunds.

Implementation

Enhanced ecommerce measurement requires you to use the HitBuilder class and its set of methods to send ecommerce data for products, impressions, and promotions. A set of Google Analytics ecommerce classes is also provided to construct ecommerce related information.

With enhanced ecommerce, you can:

• Measure Ecommerce Activities
• Measure Transactions
• Measure Refunds
• Measure the Checkout Process
• Measure Internal Promotions

Measuring Ecommerce Activities

A typical enhanced ecommerce implementation will measure product impressions, and any of the following actions:

• Selecting a product.
• Viewing product details.
• Impressions and selection of internal promotions.
• Adding / removing a product from a shopping cart.
• Initiating the checkout process for a product.
• Purchases and refunds.

Measuring Impressions

To measure a product impression build a Product object and send it with a hit by using the addImpression method. A Product must have a name or id value. All other values are optional and don't need to be set.

Product product = new Product()
    .setId("P12345")
    .setName("Android Warhol T-Shirt")
    .setCategory("Apparel/T-Shirts")
    .setBrand("Google")
    .setVariant("Black")
    .setPosition(1)
    .setCustomDimension(1, "Member");
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .addImpression(product, "Search Results");

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("searchResults");
t.send(builder.build());

See Advanced Configuration for details on the getTracker method.

Measuring Actions

Actions are measured by using the addProduct method with a Product object to add product details, and the setProductAction method with a ProductAction object to specify the action being performed.

For example, the following code measures the selection of a product displayed in a list of search results:

Product product =  new Product()
    .setId("P12345")
    .setName("Android Warhol T-Shirt")
    .setCategory("Apparel/T-Shirts")
    .setBrand("Google")
    .setVariant("Black")
    .setPosition(1)
    .setCustomDimension(1, "Member");
ProductAction productAction = new ProductAction(ProductAction.ACTION_CLICK)
    .setProductActionList("Search Results");
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .addProduct(product)
    .setProductAction(productAction);

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("searchResults");
t.send(builder.build());

Combining Impressions and Actions

In cases where you have both product impressions and an action, it is possible to combine and measure this in a single hit.

The example below shows how to measure a product detail view with a related products section:

// The product from a related products section.
Product relatedProduct =  new Product()
    .setId("P12346")
    .setName("Android Warhol T-Shirt")
    .setCategory("Apparel/T-Shirts")
    .setBrand("Google")
    .setVariant("White")
    .setPosition(1);

// The product being viewed.
Product viewedProduct =  new Product()
    .setId("P12345")
    .setName("Android Warhol T-Shirt")
    .setCategory("Apparel/T-Shirts")
    .setBrand("Google")
    .setVariant("Black")
    .setPosition(1);

ProductAction productAction = new ProductAction(ProductAction.ACTION_DETAIL);
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .addImpression(relatedProduct, "Related Products")
    .addProduct(viewedProduct)
    .setProductAction(productAction);

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("product");
t.send(builder.build());

Measuring Transactions

Measure a transaction by using the addProduct method with a Product object to add product details and the setProductAction method with a ProductAction object to specify a purchase action. Transaction level details like total revenue, tax, and shipping are provided in the ProductAction object.

Product product =  new Product()
    .setId("P12345")
    .setName("Android Warhol T-Shirt")
    .setCategory("Apparel/T-Shirts")
    .setBrand("Google")
    .setVariant("black")
    .setPrice(29.20)
    .setCouponCode("APPARELSALE")
    .setQuantity(1);
ProductAction productAction = new ProductAction(ProductAction.ACTION_PURCHASE)
    .setTransactionId("T12345")
    .setTransactionAffiliation("Google Store - Online")
    .setTransactionRevenue(37.39)
    .setTransactionTax(2.85)
    .setTransactionShipping(5.34)
    .setTransactionCouponCode("SUMMER2013");
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .addProduct(product)
    .setProductAction(productAction);

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("transaction");
t.send(builder.build());

Specifying Currency

By default, you can configure a common, global, currency for all transactions and items through the Google Analytics management web interface.

The local currency must be specified in the ISO 4217 standard. Read the Currency Codes Reference document for a complete list of supported conversion currencies.

Local currencies are specified using the currencyCode tracker property. For example, this tracker will send currency values as Euros:

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("transaction");
t.set("&cu", "EUR");  // Set tracker currency to Euros.
t.send(builder.build());

Measuring Refunds

To refund an entire transaction, use the setProductAction method with a ProductAction object to specify the transaction ID and a refund action type:

// Refund an entire transaction.
ProductAction productAction = new ProductAction(ProductAction.ACTION_REFUND)
    .setTransactionId("T12345");  // Transaction ID is only required field for a full refund.
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .setProductAction(productAction);

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("refund");
t.send(builder.build());

If a matching transaction is not found, the refund will not be processed.

To measure a partial refund, use the setProductAction method with a ProductAction object to specify the transaction ID, product ID(s), and product quantities to be refunded:

// Refund a single product.
Product product =  new Product()
    .setId("P12345")  // Product ID is required for partial refund.
    .setQuantity(1);  // Quanity is required for partial refund.
ProductAction productAction = new ProductAction(ProductAction.ACTION_REFUND)
    .setTransactionId("T12345");  // Transaction ID is required for partial refund.
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .addProduct(product)
    .setProductAction(productAction);

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("refundProduct");
t.send(builder.build());

Using Non-Interaction Events for Refunds

If you need to send refund data using an event and the event is not part of normally measured user behavior (i.e. not user initiated), then it’s recommended that you send a non-interaction event. This will prevent certain metrics from being affected by the event. For example:

// Refund an entire transaction.
ProductAction productAction = new ProductAction(ProductAction.ACTION_REFUND)
    .setTransactionId("T12345");
HitBuilders.EventBuilder builder = new HitBuilders.EventBuilder()
    .setProductAction(productAction)
    .setNonInteraction(true)
    .setCategory("Ecommerce")
    .setAction("Refund");

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.send(builder.build());

Measuring the Checkout Process

To measure each step in a checkout process:

1. Add tracking code to measure each step of the checkout process.
2. If applicable, add tracking code to measure checkout options.
3. Optionally set user-friendly step names for the checkout funnel report by configuring Ecommerce Settings in the admin section of the web interface.

1. Measuring Checkout Steps

For each step in your checkout process, you’ll need to implement the corresponding tracking code to send data to Google Analytics.

Step Field

For each checkout step that you measure you should include a step value. This value is used to map your checkout actions to the labels you configured for each step in Ecommerce Settings.

Option Field

If you have additional information about the given checkout step at the time the step is measured, you can set the option field with a checkout action to capture this information. For example, the default payment type for the user (e.g. 'Visa').

Measuring a Checkout Step

To measure a checkout step, use the addProduct method with a Product object to add product details and the setProductAction method with a ProductAction object to indicate a checkout action. If applicable you can also set a step and option with the checkout.

The following example shows how to measure the first step of a checkout process, with a single product, and some additional information about the payment type:

Product product =  new Product()
    .setId("P12345")
    .setName("Android Warhol T-Shirt")
    .setCategory("Apparel/T-Shirts")
    .setBrand("Google")
    .setVariant("black")
    .setPrice(29.20)
    .setQuantity(1);
// Add the step number and additional info about the checkout to the action.
ProductAction productAction = new ProductAction(ProductAction.ACTION_CHECKOUT)
    .setCheckoutStep(1)
    .setCheckoutOptions("Visa");
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .addProduct(product)
    .setProductAction(productAction);

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("checkoutStep1");
t.send(builder.build());

2. Measuring Checkout Options

Checkout options allow you to measure additional information about the state of the checkout. This is useful in cases where you've measured a checkout step but additional information about the same checkout step is available after a user selected option has been set. For example, the user selects a shipping method.

To measure a checkout option use the setAction to indicate a checkout option and include the step number, and the option description.

You'll likely want to measure this action once the user has performed some action to move on to the next step in the checkout process. For example:

// (On "Next" button click.)
ProductAction productAction = new ProductAction(ProductAction.ACTION_CHECKOUT_OPTIONS)
    .setCheckoutStep(1)
    .setCheckoutOptions("FedEx");
HitBuilders.EventBuilder builder = new HitBuilders.EventBuilder()
    .setProductAction(productAction)
    .setCategory("Checkout")
    .setAction("Option");

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.send(builder.build());

// Advance to next page.

3. Checkout Funnel Configuration

Each step in your checkout process can be given a descriptive name that will be used in reports. To configure these names, visit the Admin section of the Google Analytics Web Interface, select the view (profile) and click on Ecommerce Settings. Follow the Ecommerce set-up instructions to label each checkout step you intend to track.

Measuring Internal Promotions

Enhanced ecommerce includes support for measuring impressions and clicks of internal promotions, such as banners displayed to promote a sale.

Promotion Impressions

Internal promotion impressions are generally measured with the initial screen view using the addPromotion method with a Promotion object to specify the details of the promotion. For example:

Promotion promotion = new Promotion()
    .setId("PROMO_1234")
    .setName("Summer Sale")
    .setCreative("summer_banner2")
    .setPosition("banner_slot1");
HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
    .addPromotion(promotion);

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.setScreenName("promotions");
t.send(builder.build());

Promotion Clicks

Clicks on internal promotions can be measured by using the addPromotion method with a Promotion object and the setPromotionAction method set to either Promotion.ACTION_CLICK or Promotion.ACTION_VIEW to indicate a promotion click or view respectively. For example:

Promotion promotion = new Promotion()
    .setId("PROMO_1234")
    .setName("Summer Sale")
    .setCreative("summer_banner2")
    .setPosition("banner_slot1");
HitBuilders.EventBuilder builder = new HitBuilders.EventBuilder()
    .addPromotion(promotion)
    .setPromotionAction(Promotion.ACTION_CLICK)
    .setCategory("Internal Promotions")
    .setAction("click")
    .setLabel("Summer Sale");

Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
    TrackerName.APP_TRACKER);
t.send(builder.build());

package com.google.android.apps.mobileplayground;

import android.os.Bundle;
import android.support.v4.app.Fragment;
import android.view.LayoutInflater;
import android.view.View;
import android.view.ViewGroup;
import android.widget.Button;
import com.google.android.apps.mobileplayground.AnalyticsSampleApp.TrackerName;
import com.google.android.gms.analytics.HitBuilders;
import com.google.android.gms.analytics.Tracker;
import com.google.android.gms.analytics.ecommerce.Product;
import com.google.android.gms.analytics.ecommerce.ProductAction;
import com.google.android.gms.analytics.ecommerce.Promotion;

/**
 * Class to exercise Enhanced Ecommerce hits.
 */
public class EnhancedEcommerceFragment extends Fragment {

  @Override
  public View onCreateView(LayoutInflater inflater, ViewGroup container,
      Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    View view = inflater.inflate(R.layout.enhanced_ecommerce, container, false);

    Button button = (Button) view.findViewById(R.id.enhancedEcommerceImpression);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureImpression();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommerceAction);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureAction();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommerceImpressionAndAction);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureImpressionAndAction();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommerceTransaction);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureTransaction();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommerceRefundTransaction);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureRefundTransaction();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommerceRefundProduct);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureRefundProduct();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommerceRefundNonInteraction);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureRefundNonInteraction();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommerceCheckoutStep);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureCheckoutStep();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommerceCheckoutOption);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measureCheckoutOption();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommercePromotionImpression);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measurePromotionImpression();
      }
    });

    button = (Button) view.findViewById(R.id.enhancedEcommercePromotionClick);
    button.setOnClickListener(new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        measurePromotionClick();
      }
    });

    return view;
  }

  private void measureImpression() {
    Product product = new Product()
        .setId("P12345")
        .setName("Android Warhol T-Shirt")
        .setCategory("Apparel/T-Shirts")
        .setBrand("Google")
        .setVariant("Black")
        .setPosition(1)
        .setCustomDimension(1, "Member");
    HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
        .addImpression(product, "Search Results");

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.setScreenName("searchResults");
    t.send(builder.build());
  }

  private void measureAction() {
    Product product =  new Product()
        .setId("P12345")
        .setName("Android Warhol T-Shirt")
        .setCategory("Apparel/T-Shirts")
        .setBrand("Google")
        .setVariant("Black")
        .setPosition(1)
        .setCustomDimension(1, "Member");
    ProductAction productAction = new ProductAction(ProductAction.ACTION_CLICK)
        .setProductActionList("Search Results");
    HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
        .addProduct(product)
        .setProductAction(productAction);

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.setScreenName("searchResults");
    t.send(builder.build());
  }

  private void measureImpressionAndAction() {
    // The product from a related products section.
    Product relatedProduct =  new Product()
        .setId("P12346")
        .setName("Android Warhol T-Shirt")
        .setCategory("Apparel/T-Shirts")
        .setBrand("Google")
        .setVariant("White")
        .setPosition(1);

    // The product being viewed.
    Product viewedProduct =  new Product()
        .setId("P12345")
        .setName("Android Warhol T-Shirt")
        .setCategory("Apparel/T-Shirts")
        .setBrand("Google")
        .setVariant("Black")
        .setPosition(1);

    ProductAction productAction = new ProductAction(ProductAction.ACTION_DETAIL);
    HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
        .addImpression(relatedProduct, "Related Products")
        .addProduct(viewedProduct)
        .setProductAction(productAction);

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.setScreenName("product");
    t.send(builder.build());
  }

  private void measureTransaction() {
    Product product =  new Product()
        .setId("P12345")
        .setName("Android Warhol T-Shirt")
        .setCategory("Apparel/T-Shirts")
        .setBrand("Google")
        .setVariant("black")
        .setPrice(29.20)
        .setCouponCode("APPARELSALE")
        .setQuantity(1);
    ProductAction productAction = new ProductAction(ProductAction.ACTION_PURCHASE)
        .setTransactionId("T12345")
        .setTransactionAffiliation("Google Store - Online")
        .setTransactionRevenue(37.39)
        .setTransactionTax(2.85)
        .setTransactionShipping(5.34)
        .setTransactionCouponCode("SUMMER2013");
    HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
        .addProduct(product)
        .setProductAction(productAction);

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.setScreenName("transaction");
    t.send(builder.build());
  }

  private void measureRefundTransaction() {
    // Refund an entire transaction.
    ProductAction productAction = new ProductAction(ProductAction.ACTION_REFUND)
        .setTransactionId("T12345");  // Transaction ID is only required field for a full refund.
    HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
        .setProductAction(productAction);

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.setScreenName("refund");
    t.send(builder.build());
  }

  private void measureRefundProduct() {
    // Refund a single product.
    Product product =  new Product()
        .setId("P12345")  // Product ID is required for partial refund.
        .setQuantity(1);  // Quanity is required for partial refund.
    ProductAction productAction = new ProductAction(ProductAction.ACTION_REFUND)
        .setTransactionId("T12345");  // Transaction ID is required for partial refund.
    HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
        .addProduct(product)
        .setProductAction(productAction);

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.setScreenName("refundProduct");
    t.send(builder.build());
  }

  private void measureRefundNonInteraction() {
    // Refund an entire transaction.
    ProductAction productAction = new ProductAction(ProductAction.ACTION_REFUND)
        .setTransactionId("T12345");
    HitBuilders.EventBuilder builder = new HitBuilders.EventBuilder()
        .setProductAction(productAction)
        .setNonInteraction(true)
        .setCategory("Ecommerce")
        .setAction("Refund");

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.send(builder.build());
  }

  private void measureCheckoutStep() {
    Product product =  new Product()
        .setId("P12345")
        .setName("Android Warhol T-Shirt")
        .setCategory("Apparel/T-Shirts")
        .setBrand("Google")
        .setVariant("black")
        .setPrice(29.20)
        .setQuantity(1);
    // Add the step number and additional info about the checkout to the action.
    ProductAction productAction = new ProductAction(ProductAction.ACTION_CHECKOUT)
        .setCheckoutStep(1)
        .setCheckoutOptions("Visa");
    HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
        .addProduct(product)
        .setProductAction(productAction);

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.setScreenName("checkoutStep1");
    t.send(builder.build());
  }

  private void measureCheckoutOption() {
    // (On "Next" button click.)
    ProductAction productAction = new ProductAction(ProductAction.ACTION_CHECKOUT_OPTIONS)
        .setCheckoutStep(1)
        .setCheckoutOptions("FedEx");
    HitBuilders.EventBuilder builder = new HitBuilders.EventBuilder()
        .setProductAction(productAction)
        .setCategory("Checkout")
        .setAction("Option");

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.send(builder.build());

    // Advance to next page.
  }

  private void measurePromotionImpression() {
    Promotion promotion = new Promotion()
        .setId("PROMO_1234")
        .setName("Summer Sale")
        .setCreative("summer_banner2")
        .setPosition("banner_slot1");
    HitBuilders.ScreenViewBuilder builder = new HitBuilders.ScreenViewBuilder()
        .addPromotion(promotion);

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.setScreenName("promotions");
    t.send(builder.build());
  }

  private void measurePromotionClick() {
    Promotion promotion = new Promotion()
        .setId("PROMO_1234")
        .setName("Summer Sale")
        .setCreative("summer_banner2")
        .setPosition("banner_slot1");
    HitBuilders.EventBuilder builder = new HitBuilders.EventBuilder()
        .addPromotion(promotion)
        .setPromotionAction(Promotion.ACTION_CLICK)
        .setCategory("Internal Promotions")
        .setAction("click")
        .setLabel("Summer Sale");

    Tracker t = ((AnalyticsSampleApp) getActivity().getApplication()).getTracker(
        TrackerName.APP_TRACKER);
    t.send(builder.build());
  }

}

Related resource

• Enhanced Ecommerce on Analytics Help