Getting Started
Since version 2.19
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 or trackPage. 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
If you would like to directly jump into the code, you look at the common plugins often used within a Front-Commerce app.
First you will need to configure your analytics by updating the configuration file:
module.exports = {
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"),
},
],
},
};
Retrieve authorized cookie services in analytics
In Front-Commerce, to allow authorized cookie services to be injected in
analytics services settings(authorization, otherAuthorizations) callback (as
its 2nd parameter), those services also need to be defined in
config/analytics.js.
This can be done by declaring "dummy" modules in config/analytics.js such as:
// ...
+ {
+ 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
module.exports = {
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:
hasConsent- If the user provided a consent answer (authorizedordenied) for all services.authorizations- a JSON string of all consents given in the following format{
[service_name]: true | false,
}consentAuthorizations- a JSON string of all consents given for a specific service in the following format{
[service_name]: {
[consent_name]: true | false,
}
}
The expiration for these three cookies' should be configured in
src/config/website.js.
module.exports = {
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:
module.exports = {
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}
},
},
};
}
},
],
}
};