Get started by learning how to track analytics events across your entire application.

Front-Commerce uses analytics under the hood. If we represent how it works, it would look like this:

Across your React application, you can track events using functions such as trackEvent, trackPage or useTrackPage, useTrackOnMount. Then, the event is dispatched to all the relevant plugins registered in your application, learn more in the Tracking API docs.

This means that once you have correctly configured events in your React Components, adding new tracking services is less risky: it has no impact on what is being tracked.

Analytics Overview

Front-Commerce uses analytics to track events across your React application. Events are dispatched to configured plugins, making it easier to add new tracking services without changing your tracking code.

Key Features

• Track events with trackEvent
• Track page views with trackPage and useTrackPage
• Track component mounts with useTrackOnMount
• GDPR-compliant consent management
• Pluggable architecture for multiple analytics services

Configure analytics

info

If you would like to directly jump into the code, you look at the plugins often used within a Front-Commerce app.

First you will need to configure your analytics by updating the configuration file:

app/config/analytics.ts

import { type AnalyticsConfig } from "@front-commerce/core/react";

export default {
  analytics: {
    // Make sure that your analytics is enabled
    enable: true,
    // Enables the debug mode of the `analytics` library
    debug: true,
    // Pass any default settings to your plugins
    defaultSettings: {},
    // The list of plugins is defined here
    plugins: [
      {
        // The name allows to know if the user allowed to use
        // this tracking service or not, it should not be confused
        // with the name in the plugin script.
        name: "google-analytics",
        // Usually we always need to set it to true since GDPR
        needConsent: true,
        // Some plugins 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, it also
        // receive a 2nd parameter with codes of the other consents given.
        // Using a function can allow to have different settings depending
        // on the context
        settings: (authorization, otherAuthorizations) => {
          return {
            measurementIds: ["G-abc123"],
            gtagConfig: {
              anonymize_ip: !authorization,
            },
          };
        },
        // It should either return a promise function or a dynamic import to
        // the plugin script which will be added at to  the `analytics` library
        // see listed plugins: https://getanalytics.io/plugins/#supported-analytic-tools
        script: () => import("@analytics/google-analytics"),
      },
    ],
  } satisfies AnalyticsConfig,
};

Retrieve authorized cookie services in analytics

In Front-Commerce, authorized cookie services must also be defined in app/config/analytics.ts in order for them to be injected in the settings(authorization, otherAuthorizations) callback (as its second parameter).

This can be done by declaring "dummy" modules in config/analytics.ts such as:

app/config/analytics.ts

       // ...
+      {
+        name: "my-service",
+        needConsent: true,
+        script: () => () => {
+          return {
+            name: "my-service",
+          };
+        },
+      },
     ],
   },
 };

The GDPR consent

If your plugins need consent of the user before running, you need to setup the cookiesServices.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.

Configuration

app/config/cookiesServices.js

export default {
  default_en: [
    {
      // Category of cookies to allow the user to accept all the plugins 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 mentioned 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",
          ],
          // Display a more granular consent control per service
          consentOptions: [
            {
              name: "ad_storage",
              title: "Ads Storage",
              description:
                "Enables storage of advertising-related data like conversion measurement and remarketing",
            },
            {
              name: "ad_user_data",
              title: "Ads User Data",
              description:
                "Allows collection and processing of user data for advertising purposes",
            },
            {
              name: "ad_personalization",
              title: "Ads Personalization",
              description:
                "Enables personalized advertising based on user behavior and interests",
            },
            {
              name: "analytics_storage",
              title: "Analytics Storage",
              description:
                "Enables storage of analytics data to measure site usage and performance",
            },
          ],
          description:
            "Google Analytics cookies, from Google, are meant to gather statistics about visits.",
          link: "https://support.google.com/analytics/answer/6004245",
        },
      ],
    },
  ],
};

The consent is stored in 3 separate cookies:

1. hasConsent - If the user provided a consent answer (authorized or denied) for all services.
2. authorizations - a JSON string of all consents given in the following format

     {
       [service_name]: true | false,
     }
3. consentAuthorizations - a JSON string of all consents given for a specific service in the following format

   {
     [service_name]: {
       [consent_name]: true | false,
     }
   }

Important

The expiration for these three cookies' should be configured in app/config/website.js.

app/config/website.js

export default {
  default_image_url: "https://placehold.it/150x220",
  available_page_sizes: [18, 36],
  ....
  rewrittenToRoot: ["/home"],
  useUserTitles: false,
  cookieMaxAgeInMonths: 12,
};

Granular Consent Updates

When using custom consent options defined in your cookiesServices.js file, you can implement granular consent updates by adding an updateConsent method to your analytics plugin. This method allows you to handle consent changes for specific tracking features.

The updateConsent method is already included in the built-in google-analytics and google-tag-manager plugins, but you'll need to implement it yourself for custom plugins.

Here's how to add consent updates to your plugin:

app/config/analytics.ts

import { type AnalyticsConfig } from "@front-commerce/core/react";

export default {
  analytics: {
    // ...
    plugins: [
      // ...
      {
        name: "my-service",
        // ...
        script: () => () => {
          return {
            name: "my-service",
            initialize: () => {...},
            track: () => {...},
            page: () => {...},
            methods: {
              updateConsent: (consent: Record<string, boolean>) => {
                // handle consent update for your service
                // eg: {ad_storage:true, ad_user_data:false, ad_personalization:true, analytics_storage:true}
              },
            },
          };
        }
      },
    ],
  } satisfies AnalyticsConfig,
};