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 comment écrire 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 indiquer 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. Autrement dit, vous devez 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 où dans votre extension, y compris votre service worker.
Configurer des identifiants pour l'API
La première étape consiste à obtenir un api_secret et un measurement_id. Reportez-vous à la documentation du protocole de mesure pour savoir comment les ajouter à votre compte Analytics.
Générer un client_id
La deuxième étape consiste à générer un identifiant unique pour un appareil ou un utilisateur spécifique, client_id. L'ID doit rester le même, 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 au client. Vous pouvez en générer une en appelant self.crypto.randomUUID(). Stockez client_id dans chrome.storage.local pour vous assurer qu'il reste le même 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 afficher vos événements dans le rapport "Temps réel" de Google Analytics, vous devez fournir deux paramètres supplémentaires: session_id et engagement_time_msec.
Utilisez 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 obligatoires pour que l'activité des utilisateurs s'affiche dans les rapports standards tels que "Temps réel".
Une session_id décrit une période pendant laquelle un utilisateur interagit continuellement avec votre extension. Par défaut, une session prend fin 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 normaux, il n'existe pas de notion claire de session utilisateur. Vous devez donc définir la signification d'une session utilisateur dans votre extension. Par exemple, chaque nouvelle interaction utilisateur peut correspondre à une nouvelle session. Dans ce cas, vous pouvez simplement générer un nouvel ID de session pour chaque événement (à l'aide d'un horodatage).
L'exemple suivant illustre une approche qui met fin à une nouvelle session 30 minutes sans qu'aucun événement n'ait été signalé (ce délai peut être personnalisé pour mieux correspondre au comportement des utilisateurs de votre extension). L'exemple utilise chrome.storage.session pour stocker la session active pendant l'exécution du navigateur. Avec la session, nous enregistrons la dernière fois qu'un événement a été déclenché. Ainsi, 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 d'événement de clic sur le bouton précédente. Pour engagement_time_msec, vous pouvez indiquer la valeur par défaut 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 fenêtres pop-up, le panneau latéral et les extensions
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 un 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
},
},
],
}),
});
});
Vous devez importer le script popup.js 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'affiche comme toute 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 d'effectuer le suivi des événements d'analyse chez les service workers des extensions. Par exemple, en écoutant unhandledrejection event dans votre service worker, vous pouvez consigner les exceptions non détectées dans votre service worker dans Google Analytics, ce qui peut être d'une grande aide pour résoudre les problèmes que vos utilisateurs peuvent 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 propose 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 toutes les erreurs dans vos définitions d'événements. - Le rapport "Temps réel" de Google Analytics, qui affiche les événements à mesure qu'ils sont intégrés.