Analytics

React Storefront makes it easy to send user interaction and page views data to multiple analytics providers.

Configuration

In React Storefront, you send data to analytics providers by configuring one or more subclasses of CommerceAnalyticsTarget (each corresponds to a different vendor), and then calling event methods on the singleton exported by react-storefront/analytics.

These classes can be found in the commercial package react-storefront-extensions. Each defines a standard set of analytics events that you can fire to capture user data and send it to a provider.

To send data to a given provider, create an instance of a target and pass it to configureAnalytics. For example, to add Google Tag Manager:

// src/analytics.js

import { configureAnalytics } from 'react-storefront/analytics'
import GoogleTagManagerTarget from 'react-storefront-extensions/GoogleTagManagerTarget'

const target = new GoogleTagManagerTarget({ apiKey: 'your GTM API key here' })
  
  // send this data with all events
  .sendForAllEvents({ site: 'moov_pwa' })
  
  // If we're doing A/B testing, we can tell the target what cookie to send with each event to track the experiment.
  .configureExperiments({ cookieName: 'moov_experience' })
  
  // The system can automatically track when and where the user's click the back button
  .setTrackBackClick(true)
  
// configure the analytics system to send data to Google Tag Manager
configureAnalytics(target)

Page View Events

Once you've configured your analytics targets, you can begin sending events. To capture page views, simple add the TrackPageViews component from react-storefront-extensions to the root of your app.

// App.js
import TrackPageViews from 'react-storefront-extensions/TrackPageViews'
import React, { Component } from 'react'

export default class App extends Component {

  render() {
    <TrackPageViews>
      {/* Your app components here */}
    </TrackPageViews>
  }

}

TrackPageViews will automatically send a pageView event to all configured targets each time the URL changes.

Interaction Events

There are two ways to capture interaction events:

  • Call a method on the analytics object imported from react-storefront-analytics. The analytics object is a proxy that broadcasts any method you call on it to all configured analytics targets that implement that method. This allows you to send the same data to all providers with a single event.
import analytics from 'react-storefront/analytics'
import React, { Component } from 'react'

export default class MyComponent extends Component {

  render() {
    return (
      <button onClick={this.handleClick}>Click Me</button>
    )
  }

  handleClick = () => {
    analytics.buttonClicked({ someVar: 'some value' }) // This will call the "buttonClicked" event on all analytics targets that have it.
  }

}
  • Wrap any component in a <Track> element. Here's the same example as above, implemented using Track instead of calling a method on analytics directly:
import React, { Component } from 'react'
import analytics from 'react-storefront/analytics'
import Track from 'react-storefront/Track'

export default class MyComponent extends Component {

  render() {
    return (
      <Track event="buttonClick" someVar="some value">
        <button>Click Me</button>
      </Track>
    )
  }

}

Defining Custom Events

If you'd like to capture an event that isn't provided by React Storefront by default, simply extend the analytics target class corresponding to your vendor and add a method that calls sendEvent(data). For example:

class MyGTMTarget extends GoogleTagManagerTarget {

  /**
   * Here we define a custom event to send when a user zooms in on a product image.  This event can be fired using:
   * 
   *  analytics.productImageZoomed({ product }) 
   *    
   *  or 
   * 
   *  <Track event="productImageZoomed" product={product}>
   *    ...
   *  </Track>
   * 
   * @param {Object} data
   * @param {ProductModel} data.product
   */
  productImageZoomed({ product }) {
    this.sendEvent({
      event: 'product_image_zoomed',
      product: product.id
    }) 
  }

}

Sending Data to Unsupported Providers

React Storefront provides implementations for a number of providers. If yours in not supported, you can send data to them by implementing your own subclass of CommerceAnalyticsTarget. Simply implement a constructor that accepts any required configuration values for that vendor, and implement the send method. For example:

// src/analytics/MyCustomProviderTarget.js

import CommerceAnalyticsTarget from 'react-storefront/analytics/CommerceAnalyticsTarget'

export default class MyCustomProviderTarget extends CommerceAnalyticsTarget {

  /**
   * @param {String} apiKey The API key for the provider
   */
  constructor(apiKey) {
    // don't forget to call super()!
    super() 

    // add the vendors script tag to the HTML head
    this.injectScriptInHead(
      `//script.provider.com/${apiKey}.js`, // the URL for the script tag
      { async: 'async' } // any additional attributes for the script tag
    })
  }

  send(data) {
    // 3rd party analytics provider scripts generally define some window scoped variable that you use to send it data
    // here we assume the provide defines an object called window.myProvider
    window.myProvider.send(data)
  }

}

AMP

The react-storefront-extensions commercial library provides support for capturing analytics in AMP.

Enabling AMP Analytics Support

In order for your app to send analytics in AMP, analytics must be configured on both the client and the server. If you've created your app using create-react-storefront, this happens automatically because src/analytics.js is imported by src/App.js, which runs on both the client and the server. If your app is older, you may need to move your import of analytics.js from client.js to App.js.

Google Analytics in AMP

The GoogleAnalyticsTarget in react-storefront-extensions will automatically report all events to Google Analytics when running in AMP, simple add it to your analytics configuration add <TrackPageViews> to the root of your app, and wrap elements in <Track> to track click events.

// src/analytics.js

import { configureAnalytics } from 'react-storefront/analytics'

configureAnalytics(
  new GoogleAnalyticsTarget({
    trackingID: 'UA-XXXXXXXX-XX' // your tracking ID here
  })
)

Adding AMP Support for Other Providers

You can add AMP support for other providers by extending CommerceAnalyticsTarget and implementing the following method:

  • getAmpAnalyticsType():string - Returns the value to assign to the type attribute on the generated <amp-analytics> tag.

Standard Events

Here are the standard events that React Storefront can send:

pageview

Sent whenever the user navigates to a new page.

FieldTypeDescription
current_pageStringThe URI path for the new page
previous_pageStringThe URI path for the previous page
page_typeString"home", "category", "subcategory", "product", "cart", "checkout", or "search". This value will be blank for uncategorized page types
categoryObject[]When page_type = "category", an array containing objects with the following properties...
category.idStringThe id of the category
category.brandStringThe brand associated with the category
category_idString[]Same as category.id, but in flattened array format
category_brandString[]Same as category.brand, but in flattened array format
subcategoryObject[]When page_type = "subcategory", an array containing objects with the following properties...
subcategory.idStringThe id of the subcategory
subcategory.brandStringThe brand associated with the subcategory
subcategory_idString[]Same as subcategory.id, but in flattened array format
subcategory_brandString[]Same as subcategory.brand, but in flattened array format
productObject[]When page_type = "product", "cart", or "checkout", an array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array
keywordsStringWhen page_type = "search", the keywords entered by the user

homepage_slot_clicked

Sent when the user clicks on a CMS slot in the homepage.

FieldTypeDescription
slotStringThe slot id
titleStringThe slot title

search_submitted

Sent when user searches for something

FieldTypeDescription
termStringThe search term

product_clicked

Sent when a user clicks on a product

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array
positionIntegerThe position of the product in the list

subcategory_clicked

Sent when a user clicks on a subcategory

FieldTypeDescription
subcategoryStringThe id of the subcategory
positionIntegerThe position of the subcategory in the list

added_to_cart

Sent when user adds an item to the cart

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array

removed_from_cart

Sent when user removes an item from the cart

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array

account_created

Sent when a user signs up for an account

FieldTypeDescription
emailStringThe SHA1 hash of the user's email

signed_out

Sent when a user signs out.

FieldTypeDescription
emailStringThe SHA1 hash of the user's email

identify_user

Sent when the user lands on the site with an existing session.

FieldTypeDescription
emailStringThe SHA1 hash of the user's email

cart_clicked

Sent when the user clicks on the cart icon in the header.

top_nav_clicked

Sent when the user clicks on a link in the top nav.

FieldTypeDescription
nav_itemStringThe text in the nav item

logo_clicked

Sent when the user clicks the logo in the header.

product_options_changed

Sent when the user changes selected options on a product. For example, size or color.

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array

quantity_changed

Sent when the user changes the quantity field on a PDP.

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array

promo_code_added

Sent when the user adds a promo code.

FieldTypeDescription
promo_codeStringThe promo code

promo_banner_clicked

Sent when the user clicks on a promo banner.

FieldTypeDescription
promo_bannerStringThe name of the promo banner
promo_banner_imageStringThe image url used for the promo banner

list_filtered

Sent when the user filters a search result or subcategory.

FieldTypeDescription
filter_parametersString[]An array of the filters applied

list_sorted

Sent when the user sorts a search result or subcategory.

FieldTypeDescription
sort_parametersString[]An array of the properties by which the list is sorted

back_clicked

Sent when the user clicks the back button in the browser

cross_sell_product_clicked

Sent when a user clicks on a 'similar' (People also browsed, Also in this collection, etc.) product.

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array

image_switched

Sent when a user changes the viewable image (via carousel or image click).

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array
img_urlStringThe URL of the image the user switched to

color_changed

Sent when a user changes the color on a product.

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array

review_submitted

Sent when a user submits a review.

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array

breadcrumb_clicked

Sent when a user clicks on a breadcrumb.

FieldTypeDescription
breadcrumb_textThe text in the breadcrumb
breadcrumb_urlThe URL that the breadcrumb links to

layout_switched

Fires when the user switches the page layout

FieldTypeDescription
layoutString"single" or "double"

addtional_info_clicked

Sent when a user clicks to see additional info (overview, shipping info, etc) on a product.

FieldTypeDescription
productObject[]An array containing objects with the following properties...
product.idStringThe id of the product
product.sizeStringThe selected size
product.colorStringThe selected color
product.brandStringThe associated brand
product.quantityIntegerThe selected quantity
product_idString[]The id of the product as flattened array
product_sizeString[]The selected size as flattened array
product_colorString[]The selected color as flattened array
product_brandString[]The associated brand as flattened array
product_quantityInteger[]The selected quantity as flattened array

submit_error

Sent when an error occurs while submitting data to the server.

FieldTypeDescription
error_messageStringThe error message that was displayed

footer_nav_clicked

Sent when a user clicks on a footer link

FieldTypeDescription
footer_nav_textStringThe link's text
footer_nav_urlStringThe link's URL

social_link_clicked

Sent when a user clicks on a social media link.

FieldTypeDescription
social_networkStringThe name of the social network