Tracking API

The Tracking API is exposed once the analytics library is initialized with configuration.

trackEvent

An event is something that happens in your application. For instance, it can happens when a user clicks on a button, opens a dropdown, etc. It usually conveys meaning to your marketing team to better understand what drives your users.

Most of the e-commerce related events are already implemented within Front-Commerce. But each website will have different behaviors, and it can be interesting to add your own events to see how your customers uses your application.

To do so, you will need to call the method trackEvent from web/core/analytics.

For instance, let's say that you are building a grocery store and that you have created Recipe pages that display a list of ingredients needed for the current recipe. Below this list, you have created a button that adds all the ingredients to the cart of the user, and you want to know if this button is useful and if users click on it.

To add your tracking, you would need to call the trackEvent method when the user clicks on the Button. Thus, your new component would look like this:

import React from "react";
import Button from "theme/components/atoms/Button";
import { trackEvent } from "web/core/analytics";

const AddIngredientsToCart = ({ addToCart, ingredients }) => {
  return (
    <Button
      onClick={() => {
        trackEvent("Added ingredients to cart", {
          ingredients: ingredients,
        });
        addToCart();
      }}
    >
      Add ingredients
    </Button>
  );
};

export default AddIngredientsToCart;

This trackEvent method is actually a shortcut that lets you call the analytics.track method from the analytics module. It uses the exact same API. See the official documentation for more detailed information.

Additionally, you may wonder what name and properties you should give to your events. It depends on the integrations you are using and if you want to create a new event or use Semantic ones (supported events within Segment.io). To learn more about this, please refer to the Semantic Events documentation.

withTrackOnMount

If you don't have an actual callback to put the trackEvent (like onClick), you can use the withTrackOnMount enhancer that will let you call the trackEvent using React lifecycle.

For instance, in Front-Commerce's core, we are using withTrackOnMount to track when a user sees their cart.

import withTrackOnMount from "theme/modules/Analytics/withTrackOnMount";

export default withTrackOnMount({
  event: "Cart Viewed",
  isResolvedFromProps: (props) => !props.loading && props.cart,
  shouldUpdateEvent: (prevProps, nextProps) =>
    prevProps.cart.id !== nextProps.cart.id,
  mapPropsToProperties: (props) => {
    return {
      cart_id: props.cart.id,
      products: props.cart.items.map((item, index) => ({
        sku: item.sku,
        name: item.name,
        quantity: item.qty,
        price: item.priceInfo.price.priceInclTax.value.amount,
        position: index + 1,
      })),
    };
  },
})(Cart);

note

Please refer to Analytics React Components to have a detailed explanation of the API of withTrackOnMount.

Note that if you prefer to use render props you can refer to TrackOnMount.

withTrackPage

In tracking scripts, there is often a distinction between the page and the event even though a page event is only a subset of the events.

To make this distinction clear, we provide an enhancer in the same spirit of withTrackOnMount but for page events: withTrackPage.

withTrackPage is an enhancer that lets you track a page each time a component is rendered and when the location has changed.

For instance, in Front-Commerce's core

import withTrackPage from "theme/modules/Analytics/withTrackPage";

withTrackPage("Home")(Cart);

note

Please refer to Analytics React Components to have a detailed explanation of the API of withTrackPage.

Note that if you prefer to use render props you can refer to TrackPage.

Moreover, we didn't talk about a trackPage method here. This is because a Page is tightly coupled to a React Component. This is why you shouldn't need to use trackPage directly.