Analytics

Most e-commerce website need advanced analytics to better understand their users and adapt their shops to their customers needs. But it can often be tedious to maintain when you have many trackings to manage.

In Front-Commerce, we use analytics.js. It is a library created by Segment.io that aims at decoupling the tracking settings from the event.

If we represent how it works, it would look like this:

Across your React application, you can track events using functions such as trackEvent or trackPage. Then, the event is dispatched to all the relevant integrations registered in your application.

This means that once you have correctly configured events in your React Components, adding new trackings can be really straightforward.

Track an event

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/utils/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 a 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.

The button would likely be a component that would look like this:

import React from "react";
import Button from "theme/components/atoms/Button";

const AddIngredientsToCart = ({addToCart}) => {
  return (
    <Button onClick={() => {
      addToCart();
    }}>
      Add ingredients
    </Button>
  );
}

export default AddIngredientsToCart;

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 of analytics.js. 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 refere to the Semantic Events documentation.

Track an event as a React Component

If you don’t have an actual callback where 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 like this 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)

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.

Track page

In trackings 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)

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.

Add an integration

An integration will listen each event and page tracking in your application and will send it to your tracking service. To configure which tracking service your application will use, you need to edit the config/analytics.js file:

module.exports = {
  analytics: {
    // Make sure that your analytics is enabled
    enable: true,
    // Enables the debug mode of the `analytics.js` library
    debug: true,
    defaultSettings: {},
    // The list of integrations is defined here
    integrations: [
      {
        // The name allows to know if the user allowed to use
        // this tracking service or not
        name: "google-analytics",
        // Usually we always need to set it to true since GDPR
        needConsent: true,
        // Some integrations may have a privacy mode allowing them
        // to be enabled by default. Use this configuration to always
        // enable it. It is irrelevant if `needConsent` is `false`.
        enabledByDefault: true,

        // Settings can be an object or a function that will be called
        // with the current consent authorization from the visitor.
        // Using a function can allow to have different settings depending
        // on the context
        settings: (authorization) => {
          // Settings needed by the integration
          // The fact that it the key "Google Analytics" is
          // defined by the integration itself
          return {
            "Google Analytics": {
              trackingId: "UA-123-1",
              anonymizeIp: !authorization,
            },
          };
        },

        // integration that will add itself to the `analytics.js` lib
        script: () =>
          import("@segment/analytics.js-integration-google-analytics"),
      }
      // You can add other integrations here. They are loaded asynchronously and
      // won't impact the user's performance too much (as long as there are not
      // too many).
    ]
  }
};

Here we have used the Google Analytics integration. You can find the list of existing integrations here.

However, please note that some integrations are not up to date. Even if you find one that matches your need, it might not work. However, looking into its code will let you know how to make it work, and you could eventually fork it to fix it.

GDPR consent

If your integrations need consent of the user before running, you need to setup the config/cookieServices.js file. This file will let you define which cookies and trackings services are used within your application and will let the user chose which tracking service to allow.

export default {
  default_en: [
    {
      // Category of cookies to allow the user to accept all the integrations at once in a specific category
      title: "Analytics",
      description:
        "These cookies allows us to measure the traffic on our contents and hence to improve them.",
      services: [
        {
          // The name should be the same as mentionned in the `config/analytics.js` file
          name: "google-analytics",
          title: "Google Analytics",
          // display all the cookies managed by Google Analytics
          cookies: [
            "_ga",
            "_gat",
            "_gid",
            "__utma",
            "__utmb",
            "__utmc",
            "__utmt",
            "__utmz"
          ],
          description:
            "Google Analytics cookies, from Google, are meant to gather statistics about visits.",
          link: "https://support.google.com/analytics/answer/6004245"
        }
      ]
    }
  ]
};

How to create a custom integration?

Currently, the integrations creation is not documented by Segment.io. We plan to add information here to help you to:

• define an integration that will add a specific pixel on a specific page
• understand which tracking scripts will make your life easier and which one will not in the context of an SPA
• find which callback will be called within your integration depending on the event

If you need these informations right away, please contact us. We will make sure to answer you in a timely manner.