Universal Analytics enhanced ecommerce for iOS

Enhanced ecommerce is a Google Analytics feature available in Universal Analytics properties that enables measurement of user interactions with products across the user's shopping experience. This can include product impressions, product clicks, views of product details, adding items to a shopping cart, initiating checkouts, transactions, and refunds.

The latest generations of both Google Tag Manager and Google Analytics for mobile apps work in conjunction with Firebase, Google’s mobile app platform. When measuring apps with the Firebase SDK, you’ll have access to a host of automatically generated mobile app reports, which can be further customized and supplemented by in-app code. These reports will automatically include data on in-app purchases processed by the App Store on iTunes and Google Play. Additional ecommerce-related reports can be generated by implementing suggested events for ecommerce apps. In depth reports on shopping behavior (i.e. enhanced ecommerce) are currently only available in Universal Analytics properties.

This document describes how to use Tag Manager for iOS apps in conjunction with the Firebase SDK to send enhanced ecommerce data to Universal Analytics properties. The same event and parameter syntax should be used to set the stage for additional ecommerce reports in the future.

First steps

Before getting started, set up the following prerequisites for your app:

  1. Install and configure Firebase and Google Tag Manager in your app. Ensure that you are using version 11 or higher of the Firebase SDK for iOS.
  2. Configure a user-defined variable in your Tag Manager container called "promotions", with the following settings:
    • Event Type: Custom Parameter
    • Event Parameter Key: promotions
    • Default Value: undefined

Implementation

The following sections demonstrate how to log events with the parameters necessary to measure enhanced ecommerce activities such as:

Product Impressions

Measure product impressions by logging an event with a kFIRParameterItemID parameter and one or more items (i.e. products) defined with the relevant fields.

// Define product with relevant parameters.
NSDictionary *product1 = @{
   kFIRParameterItemID : @"sku1234", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Jogger Sweatpants",
   kFIRParameterItemCategory : @"Apparel/Men/Pants",
   kFIRParameterItemVariant : @"Blue",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @39.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterIndex : @1          // Position of the item in the list.
};

NSDictionary *product2 = @{
   kFIRParameterItemID : @"sku5678", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Capri",
   kFIRParameterItemCategory : @"Apparel/Women/Pants",
   kFIRParameterItemVariant : @"Black",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @35.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterIndex : @2          // Position of the item in the list.
};

// Prepare ecommerce dictionary.
NSArray *items = @[product1, product2];

NSDictionary *ecommerce = @{
   @"items" : items,
   kFIRParameterItemList : @"Search Results" // List name.
};

// Log select_content event with ecommerce dictionary.
[FIRAnalytics logEventWithName:kFIREventViewSearchResults
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Screen View
  • Fields to Set: (Field Name) screenName (value, e.g.) Search Results Screen
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals view_search_results

Product clicks/selections

Measure product clicks by logging a kFIREventSelectContent event with an item (i.e. product) defined with the relevant fields:

// Define product with relevant parameters.
NSDictionary *product1 = @{
   kFIRParameterItemID : @"sku1234", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Jogger Sweatpants",
   kFIRParameterItemCategory : @"Apparel/Men/Pants",
   kFIRParameterItemVariant : @"Blue",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @39.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterIndex : @1          // Position of the item in the list.
};

// Prepare ecommerce dictionary.
NSArray *items = @[product1];

NSDictionary *ecommerce = @{
   @"items" : items,
   kFIRParameterItemList : @"Search Results" // List name.
};

// Log select_content event with ecommerce dictionary.
[FIRAnalytics logEventWithName:kFIREventSelectContent
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Event
  • Event Category, e.g.: Ecommerce
  • Event Action, e.g. : Product Click
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals select_content AND {{promotions}} equals undefined

Product detail views

Measure product detail views by logging a kFIREventViewItem event with an item (i.e. product) defined with the relevant fields:

// Define product with relevant parameters.
NSDictionary *product1 = @{
   kFIRParameterItemID : @"sku1234", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Jogger Sweatpants",
   kFIRParameterItemCategory : @"Apparel/Men/Pants",
   kFIRParameterItemVariant : @"Blue",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @39.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
};

// Prepare ecommerce dictionary.
NSArray *items = @[product1];

NSDictionary *ecommerce = @{
   @"items" : items,
   kFIRParameterItemList : @"Search Results" // List name.
};

// Log view_item event with ecommerce dictionary.
[FIRAnalytics logEventWithName:kFIREventViewItem
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Screen View
  • Fields to Set: (Field Name) screenName (value, e.g.) Product Details Screen
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals view_item AND
  • {{promotions}} equals undefined

Additions to cart

Measure a product being added to a shopping cart by logging a kFIREventAddToCart event with an item (i.e. product) defined with the relevant fields:

/// Define product with relevant parameters.
NSDictionary *product1 = @{
   kFIRParameterItemID : @"sku1234", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Jogger Sweatpants",
   kFIRParameterItemCategory : @"Apparel/Men/Pants",
   kFIRParameterItemVariant : @"Blue",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @39.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterQuantity : @1
};

// Prepare ecommerce dictionary.
NSArray *items = @[product1];

NSDictionary *ecommerce = @{
   @"items" : items
};

// Log add_to_cart event with ecommerce dictionary.
[FIRAnalytics logEventWithName:kFIREventAddToCart
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Event
  • Event Category, e.g.: Ecommerce
  • Event Action, e.g. : Add to Cart
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals add_to_cart

Removals from cart

Measure a product being removed from a shopping cart by logging a kFIREventRemoveFromCart event with an item (i.e. product) defined with the relevant fields:

// Define product with relevant parameters.
NSDictionary *product1 = @{
   kFIRParameterItemID : @"sku1234", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Jogger Sweatpants",
   kFIRParameterItemCategory : @"Apparel/Men/Pants",
   kFIRParameterItemVariant : @"Blue",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @39.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterQuantity : @1
};

// Prepare ecommerce dictionary.
NSArray *items = @[product1];

NSDictionary *ecommerce = @{
   @"items" : items
};

// Log remove_from_cart event with ecommerce dictionary.
[FIRAnalytics logEventWithName:kFIREventRemoveFromCart
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Event
  • Event Category, e.g.: Ecommerce
  • Event Action, e.g. : Remove from Cart
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals remove_from_cart

Promotion impressions

Measure promotion impressions by logging a kFIREventViewItem event with a promotion item defined with the relevant fields:

/// Define promotion with relevant parameters.
NSDictionary *promotion = @{
   kFIRParameterItemID : @"PROMO_1234", // promotion ID; either ITEM_ID or ITEM_NAME is.
   kFIRParameterItemName : @"Summer Sale", // promotion name.
   kFIRParameterCreativeName : @"summer_banner2",
   kFIRParameterCreativeSlot : @"banner_slot1"
};

// Prepare ecommerce dictionary.
NSArray *promotions = @[promotion];
NSDictionary *ecommerce = @{
   @"promotions" : promotions
};

// Log view_item, view_item_list, or view_search_results
// event with ecommerce bundle.
[FIRAnalytics logEventWithName:kFIREventViewItem
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Event
  • Event Category, e.g.: Internal Promotion
  • Event Action, e.g.: Impression
  • Non-Interaction Hit: True
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals view_item AND
  • {{promotions}} does not equal undefined

Promotion clicks/selections

Measure promotion clicks by logging a kFIREventSelectContent event with a promotion defined with the relevant fields:

// Define promotion with relevant parameters.
NSDictionary *promotion = @{
   kFIRParameterItemID : @"PROMO_1234", // promotion ID; either ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Summer Sale", // promotion name.
   kFIRParameterCreativeName : @"summer_banner2",
   kFIRParameterCreativeSlot : @"banner_slot1"
};

// Prepare ecommerce dictionary.
NSArray *promotions = @[promotion];

// Set properties for the event to be shown in the Google Analytics (Firebase) reports.
// These properties will not impact the Universal Analytics reporting.
NSDictionary *ecommerce = @{
   kFIRParameterItemID : @"PROMO_1234",
   kFIRParameterContentType : @"Internal Promotions",
   @"promotions" : promotions
};

// Log select_content, view_item_list, or view_search_results event with ecommerce bundle.
[FIRAnalytics logEventWithName:kFIREventSelectContent
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Event
  • Event Category, e.g.: Internal Promotion
  • Event Action, e.g. : Click
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals select_content AND {{promotions}} does not equal undefined

Checkout process

Begin checkout

Measure the first step in a checkout process by logging a kFIREventBeginCheckout event with one or more items (i.e. products) defined with the relevant fields:

// Define products with relevant parameters.
NSDictionary *product1 = @{
   kFIRParameterItemID : @"sku1234", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Jogger Sweatpants",
   kFIRParameterItemCategory : @"Apparel/Men/Pants",
   kFIRParameterItemVariant : @"Blue",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @39.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterQuantity : @1
};

// Prepare ecommerce dictionary.
NSArray *items = @[product1];

// Set checkout step and optional checkout option.
NSDictionary *ecommerce = @{
   @"items" : items,
   kFIRParameterCheckoutStep : @1, // Optional for first step.
   kFIRParameterCheckoutOption : @"Visa" // Optional.
};

// Log BEGIN_CHECKOUT event with ecommerce dictionary.
[FIRAnalytics logEventWithName:kFIREventBeginCheckout
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Screen View
  • Fields to Set: (Field Name) screenName (value, e.g.) Cart Screen
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals begin_checkout

Checkout options

Checkout options allow you to measure additional information about the state of the checkout process. You can either measure checkout options either as part of a checkout step event (as shown above) or upon a user selecting an option after the event for a given checkout step has already been logged.

Measure checkout options after a checkout step by logging a kFIREventCheckoutProgress event with the corresponding kFIRParameterCheckoutStep and kFIRParameterCheckoutOption parameters:

// Define products with relevant parameters.
NSDictionary *product1 = @{
   kFIRParameterItemID : @"sku1234", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Jogger Sweatpants",
   kFIRParameterItemCategory : @"Apparel/Men/Pants",
   kFIRParameterItemVariant : @"Blue",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @39.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterQuantity : @1
};

// Prepare ecommerce dictionary.
NSArray *items = @[product1];

// Set checkout step and optional checkout option.
NSDictionary *ecommerce = @{
   @"items" : items,
   kFIRParameterCheckoutStep : @2, // Optional for first step.
   kFIRParameterCheckoutOption : @"Visa" // Optional.
};

// Log CHECKOUT_PROGRESS event with ecommerce dictionary.
[FIRAnalytics logEventWithName:kFIREventCheckoutProgress
                   parameters:ecommerce];

See the tag configuration for this example:

  • g Type: Universal Analytics
  • ack Type: Event
  • ent Category, e.g.: Ecommerce
  • ent Action, e.g. : Set Checkout Option
  • able Enhanced Ecommerce Features: True
  • ad data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals set_checkout_option

Purchases

Measure purchases by logging an kFIREventEcommercePurchase event with one or more items (i.e. products) defined with the relevant fields:

// Define products with relevant parameters.
NSDictionary *product1 = @{
   kFIRParameterItemID : @"sku1234", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Jogger Sweatpants",
   kFIRParameterItemCategory : @"Apparel/Men/Pants",
   kFIRParameterItemVariant : @"Blue",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @39.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterQuantity : @1
};

NSDictionary *product2 = @{
   kFIRParameterItemID : @"sku5678", // ITEM_ID or ITEM_NAME is required.
   kFIRParameterItemName : @"Android Capri",
   kFIRParameterItemCategory : @"Apparel/Women/Pants",
   kFIRParameterItemVariant : @"Black",
   kFIRParameterItemBrand : @"Google",
   kFIRParameterPrice : @35.99,
   kFIRParameterCurrency : @"USD",  // Item-level currency unused today.
   kFIRParameterQuantity : @1
};

// Prepare ecommerce dictionary.
NSArray *items = @[product1, product2];

NSDictionary *ecommerce = @{
   @"items" : items,
   kFIRParameterItemList : @"Search Results", // List name.
   kFIRParameterTransactionID : @"T12345",
   kFIRParameterAffiliation : @"Google Store - Online",
   kFIRParameterValue : @75.98, // Revenue.
   kFIRParameterTax : @3.80,
   kFIRParameterShipping : @5.34,
   kFIRParameterCurrency : @"USD",
   kFIRParameterCoupon : @"SUMMER2017"
};

// Log ecommerce_purchase event with ecommerce dictionary.
[FIRAnalytics logEventWithName:kFIREventEcommercePurchase
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Screen View
  • Fields to Set: (Field Name) screenName (value, e.g.) Thank You Screen
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals ecommerce_purchase

Refunds

Measure refunds by logging a kFIREventPurchaseRefund event with the relevant transaction ID specified, and optionally (for partial refunds) one or more items (i.e. products) defined with item IDs and quantities:

// (OPTIONAL) For partial refunds, define the item IDs and
// quantities of products being refunded.
NSDictionary *refundedProduct = @{
   kFIRParameterItemID : @"sku1234", // Required for partial refund.
   kFIRParameterQuantity : @1
};

// Prepare ecommerce bundle with transaction ID to be refunded.
NSDictionary *ecommerce = @{
   @"items" : @[ refundedProduct ],
   kFIRParameterTransactionID : @"T12345", // Required.
   kFIRParameterValue : @75.98 // Optional in Universal Analytics.
};

// Log purchase_refund event with ecommerce.
[FIRAnalytics logEventWithName:kFIREventPurchaseRefund
                    parameters:ecommerce];

See the tag configuration for this example:

  • Tag Type: Universal Analytics
  • Track Type: Event
  • Event Category, e.g.: Ecommerce
  • Event Action, e.g. : Refund
  • Enable Enhanced Ecommerce Features: True
  • Read data from: Firebase Event
  • Trigger, e.g.: (Custom > Some Events) Event Name equals purchase_refund