Skip to main content
Version: 3.x

Getting Started

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.

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,
};

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",
+          };
+        },
+      },
     ],
   },
 };

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.

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",
          ],
          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 2 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, ... }
Important

The expiration for these two 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,
};