Ce tutoriel explique comment suivre l'utilisation de votre extension à l'aide de Google Analytics. Vous trouverez un exemple Google Analytics 4 fonctionnel sur GitHub, où google-analytics.js inclut tout le code associé à Google Analytics.
Conditions requises
Dans ce tutoriel, nous partons du principe que vous savez créer des extensions Chrome. Pour savoir comment écrire une extension, consultez le tutoriel de mise en route.
Vous devez également configurer un compte Google Analytics 4 pour suivre votre extension. Notez que lorsque vous configurez le compte, vous pouvez utiliser n'importe quelle valeur dans le champ "URL du site Web", car votre extension n'aura pas sa propre URL.
Utiliser le protocole de mesure Google Analytics
Depuis Manifest V3, les extensions Chrome ne sont pas autorisées à exécuter du code hébergé à distance. Vous devez donc utiliser le protocole de mesure Google Analytics pour suivre les événements d'extension. Le protocole de mesure vous permet d'envoyer des événements directement aux serveurs Google Analytics via des requêtes HTTP. L'un des avantages de cette approche est qu'elle vous permet d'envoyer des événements d'analyse depuis n'importe quel emplacement de votre extension, y compris votre service worker.
Configurer les identifiants de l'API
La première étape consiste à obtenir un api_secret et un measurement_id. Pour savoir comment obtenir ces informations pour votre compte Analytics, consultez la documentation sur le protocole de mesure.
Générer un client_id
La deuxième étape consiste à générer un identifiant unique pour un appareil/utilisateur spécifique, le client_id. L'ID ne doit pas changer tant que l'extension est installée dans le navigateur de l'utilisateur. Il peut s'agir d'une chaîne arbitraire, mais elle doit être unique pour le client. Vous pouvez en générer un en appelant self.crypto.randomUUID(). Stockez client_id dans chrome.storage.local pour vous assurer qu'il ne change pas tant que l'extension est installée.
L'utilisation de chrome.storage.local nécessite l'autorisation storage dans votre fichier manifeste:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Vous pouvez ensuite utiliser chrome.storage.local pour stocker client_id:
async function getOrCreateClientId() {
const result = await chrome.storage.local.get('clientId');
let clientId = result.clientId;
if (!clientId) {
// Generate a unique client ID, the actual value is not relevant
clientId = self.crypto.randomUUID();
await chrome.storage.local.set({clientId});
}
return clientId;
}
Envoyer un événement d'analyse
Avec les identifiants de l'API et le client_id, vous pouvez envoyer un événement à Google Analytics via une requête fetch:
const GA_ENDPOINT = 'https://www.google-analytics.com/mp/collect';
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;
fetch(
`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
{
method: 'POST',
body: JSON.stringify({
client_id: await getOrCreateClientId(),
events: [
{
name: 'button_clicked',
params: {
id: 'my-button',
},
},
],
}),
}
);
Un événement button_clicked est alors envoyé qui apparaîtra dans votre rapport sur les événements Google Analytics. Si vous souhaitez voir vos événements dans le rapport "Temps réel" Google Analytics, vous devez fournir deux paramètres supplémentaires: session_id et engagement_time_msec.
Utiliser les paramètres recommandés session_id et engagement_time_msec
session_id et engagement_time_msec sont des paramètres recommandés lorsque vous utilisez le protocole de mesure Google Analytics, car ils sont nécessaires pour que l'activité des utilisateurs s'affiche dans les rapports standards comme "Temps réel".
Une session_id décrit une période de temps pendant laquelle un utilisateur interagit en continu avec votre extension. Par défaut, une session se termine après 30 minutes d'inactivité de l'utilisateur. Il n'y a aucune limite quant à la durée des sessions.
Dans les extensions Chrome, contrairement aux sites Web classiques, la notion de session utilisateur n'est pas claire. Vous devez donc définir la signification d'une session utilisateur dans votre extension. Par exemple, chaque nouvelle interaction d'un utilisateur peut correspondre à une nouvelle session. Dans ce cas, il vous suffit de générer un nouvel identifiant de session pour chaque événement (c'est-à-dire à l'aide d'un code temporel).
L'exemple suivant illustre une approche qui met en veille une nouvelle session après 30 minutes sans aucun événement enregistré (ce délai peut être personnalisé afin de mieux correspondre au comportement de l'utilisateur de votre extension). L'exemple utilise chrome.storage.session pour stocker la session active lorsque le navigateur est en cours d'exécution. Avec la session, nous enregistrons la dernière fois qu'un événement a été déclenché. De cette façon, nous pouvons savoir si la session active a expiré:
const SESSION_EXPIRATION_IN_MIN = 30;
async function getOrCreateSessionId() {
// Store session in memory storage
let {sessionData} = await chrome.storage.session.get('sessionData');
// Check if session exists and is still valid
const currentTimeInMs = Date.now();
if (sessionData && sessionData.timestamp) {
// Calculate how long ago the session was last updated
const durationInMin = (currentTimeInMs - sessionData.timestamp) / 60000;
// Check if last update lays past the session expiration threshold
if (durationInMin > SESSION_EXPIRATION_IN_MIN) {
// Delete old session id to start a new session
sessionData = null;
} else {
// Update timestamp to keep session alive
sessionData.timestamp = currentTimeInMs;
await chrome.storage.session.set({sessionData});
}
}
if (!sessionData) {
// Create and store a new session
sessionData = {
session_id: currentTimeInMs.toString(),
timestamp: currentTimeInMs.toString(),
};
await chrome.storage.session.set({sessionData});
}
return sessionData.session_id;
}
L'exemple suivant ajoute session_id et engagement_time_msec à la requête précédente d'événement de clic sur le bouton. Pour engagement_time_msec, vous pouvez fournir une valeur par défaut de 100 ms.
const GA_ENDPOINT = "https://www.google-analytics.com/mp/collect";
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;
const DEFAULT_ENGAGEMENT_TIME_IN_MSEC = 100;
fetch(
`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
{
method: "POST",
body: JSON.stringify({
client_id: await getOrCreateClientId(),
events: [
{
name: "button_clicked",
params: {
session_id: await this.getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
id: "my-button",
},
},
],
}),
}
);
L'événement s'affichera comme suit dans le rapport "Temps réel" de Google Analytics.
Suivi des pages vues dans les pop-up, le panneau latéral et les pages d'extension
Le protocole de mesure Google Analytics accepte un événement page_view spécial pour le suivi des pages vues. Utilisez cette option pour suivre les utilisateurs qui consultent vos pages pop-up, votre panneau latéral ou une page d'extension dans un nouvel onglet. L'événement page_view nécessite également les paramètres page_title et page_location. L'exemple suivant déclenche un événement "Page vue" au niveau de l'événement load du document pour une fenêtre pop-up d'extension :
popup.js:
window.addEventListener("load", async () => {
fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
{
method: "POST",
body: JSON.stringify({
client_id: await getOrCreateClientId(),
events: [
{
name: "page_view",
params: {
session_id: await getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
page_title: document.title,
page_location: document.location.href
},
},
],
}),
});
});
Le script popup.js doit être importé dans le fichier HTML de votre pop-up et s'exécuter avant tout autre script:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Analytics Demo Popup</title>
<script src="./popup.js" type="module"></script>
</head>
<body>
<h1>Analytics Demo</h1>
</body>
</html>
La vue pop-up s'affichera comme n'importe quelle autre page vue dans le rapport "Temps réel" de Google Analytics:
Suivre les événements d'analyse dans les service workers
Le protocole de mesure Google Analytics permet de suivre les événements d'analyse au niveau des service workers d'extensions. Par exemple, en écoutant unhandledrejection event dans votre service worker, vous pouvez consigner toutes les exceptions non détectées dans votre service worker dans Google Analytics, ce qui peut s'avérer très utile pour déboguer les problèmes que vos utilisateurs pourraient signaler.
service-worker.js:
addEventListener("unhandledrejection", async (event) => {
`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
{
method: "POST",
body: JSON.stringify({
client_id: getOrCreateClientId(),
events: [
{
// Note: 'error' is a reserved event name and cannot be used
// see https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#reserved_names
name: "extension_error",
params: {
session_id: await this.getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
message: error.message,
stack: error.stack,
},
},
],
}),
}
});
Vous pouvez désormais voir l'événement d'erreur dans vos rapports Google Analytics:
Débogage
Google Analytics fournit deux fonctionnalités utiles pour déboguer les événements d'analyse dans votre extension:
- Un point de terminaison de débogage spécial
https://www.google-analytics.com**/debug**/mp/collectqui signalera toute erreur dans vos définitions d'événement. - Le rapport "Temps réel" de Google Analytics, qui affiche les événements à mesure qu'ils surviennent.