In dieser Anleitung erfahren Sie, wie Sie die Nutzung Ihrer Erweiterung mit Google Analytics erfassen. Ein funktionierendes Google Analytics 4-Beispiel auf GitHub enthält google-analytics.js
den gesamten Google Analytics-bezogenen Code.
Voraussetzungen
In dieser Anleitung wird davon ausgegangen, dass Sie mit dem Schreiben von Chrome-Erweiterungen vertraut sind. Informationen zum Schreiben einer Erweiterung finden Sie in der Anleitung für die ersten Schritte.
Außerdem müssen Sie ein Google Analytics 4-Konto einrichten, um die Erweiterung zu erfassen. Beachten Sie, dass Sie bei der Einrichtung des Kontos einen beliebigen Wert im Feld „Website-URL“ verwenden können, da Ihre Erweiterung keine eigene URL hat.
Measurement Protocol von Google Analytics verwenden
Seit Manifest V3 dürfen Chrome-Erweiterungen keinen Remote-gehosteten Code ausführen. Das bedeutet, dass Sie das Google Analytics Measurement Protocol zum Erfassen von Erweiterungsereignissen verwenden müssen. Mit dem Measurement Protocol können Sie Ereignisse über HTTP-Anfragen direkt an Google Analytics-Server senden. Ein Vorteil dieses Ansatzes besteht darin, dass Sie Analyseereignisse von überall in Ihrer Erweiterung senden können, auch von Ihrem Service Worker.
API-Anmeldedaten einrichten
Der erste Schritt besteht darin, api_secret
und measurement_id
abzurufen. In der Measurement Protocol-Dokumentation erfahren Sie, wie Sie diese für Ihr Analytics-Konto abrufen.
client_id
generieren
Im zweiten Schritt wird eine eindeutige Kennung für ein bestimmtes Gerät oder einen bestimmten Nutzer (client_id
) generiert. Die ID sollte immer gleich bleiben, solange die Erweiterung im Browser des Nutzers installiert ist. Der String kann ein beliebiger String sein, darf aber für den Client nur einmal vorkommen. Sie können sie generieren, indem Sie self.crypto.randomUUID()
aufrufen. Speichern Sie die client_id
in chrome.storage.local
, damit sie unverändert bleibt, solange die Erweiterung installiert ist.
Für die Verwendung von chrome.storage.local
ist die Berechtigung storage
in deiner Manifestdatei erforderlich:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Anschließend können Sie chrome.storage.local
verwenden, um client_id
zu speichern:
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;
}
Analyseereignis senden
Mit den API-Anmeldedaten und dem client_id
können Sie ein Ereignis über eine fetch
-Anfrage an Google Analytics senden:
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',
},
},
],
}),
}
);
Dadurch wird ein button_clicked
-Ereignis gesendet, das im Google Analytics-Bericht zu Ereignissen angezeigt wird. Wenn Sie Ihre Ereignisse im Google Analytics-Echtzeitbericht sehen möchten, müssen Sie zwei zusätzliche Parameter angeben: session_id
und engagement_time_msec
.
Die empfohlenen Parameter session_id
und engagement_time_msec
verwenden
Sowohl session_id
als auch engagement_time_msec
sind empfohlene Parameter für die Verwendung des Measurement Protocol von Google Analytics, da sie erforderlich sind, damit Nutzeraktivitäten in Standardberichten wie dem Echtzeitbericht angezeigt werden.
Eine session_id
ist ein Zeitraum, in dem ein Nutzer kontinuierlich mit Ihrer Erweiterung interagiert. Standardmäßig endet eine Sitzung nach 30 Minuten Inaktivität. Es gibt keine Begrenzung für die Dauer einer Sitzung.
Bei Chrome-Erweiterungen gibt es im Gegensatz zu normalen Websites keine klare Vorstellung von einer Nutzersitzung. Daher müssen Sie in Ihrer Erweiterung definieren, was eine Nutzersitzung bedeutet. Beispielsweise kann jede neue Nutzerinteraktion eine neue Sitzung sein. In diesem Fall können Sie einfach mit jedem Ereignis (d.h. mit einem Zeitstempel) eine neue Sitzungs-ID generieren.
Im folgenden Beispiel sehen Sie einen Ansatz, bei dem nach 30 Minuten, bei dem keine Ereignisse gemeldet wurden, eine neue Sitzung beendet wird. Diese Zeit kann besser an das Nutzerverhalten der Erweiterung angepasst werden. In diesem Beispiel wird chrome.storage.session
verwendet, um die aktive Sitzung zu speichern, während der Browser ausgeführt wird. Zusammen mit der Sitzung speichern wir, wann ein Ereignis zuletzt ausgelöst wurde. So können wir feststellen, ob die aktive Sitzung abgelaufen ist:
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;
}
Im folgenden Beispiel werden session_id
und engagement_time_msec
zur vorherigen Anfrage für Schaltflächenklicks hinzugefügt. Für engagement_time_msec
können Sie den Standardwert 100 ms
angeben.
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",
},
},
],
}),
}
);
Das Ereignis wird im Google Analytics-Echtzeitbericht wie unten dargestellt angezeigt.
Seitenaufrufe in Pop-up-, Seitenleiste und Erweiterungsseiten erfassen
Das Measurement Protocol von Google Analytics unterstützt ein spezielles page_view
-Ereignis zum Erfassen von Seitenaufrufen. Hiermit können Sie erfassen, wie Nutzer Ihre Pop-up-Seiten, die Seitenleiste oder eine Erweiterungsseite in einem neuen Tab aufrufen. Für das page_view
-Ereignis sind außerdem die Parameter page_title
und page_location
erforderlich. Im folgenden Beispiel wird beim Ereignis load
des Dokuments ein Seitenaufrufereignis für ein Erweiterungs-Pop-up ausgelöst:
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
},
},
],
}),
});
});
Das Skript popup.js
muss in die HTML-Datei des Pop-ups importiert werden und sollte ausgeführt werden, bevor ein anderes Skript ausgeführt wird:
<!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>
Die Pop-up-Ansicht wird wie jeder andere Seitenaufruf im Google Analytics-Echtzeitbericht angezeigt:
Tracking von Analyseereignissen in Service Workern
Mit dem Measurement Protocol von Google Analytics können Analyseereignisse in Extension Service Workern erfasst werden. Wenn Sie beispielsweise den unhandledrejection event
in Ihrem Service Worker überwachen, können Sie alle nicht abgefangenen Ausnahmen in Ihrem Service Worker in Google Analytics protokollieren. Das kann sehr hilfreich sein, um Probleme zu beheben, die von Nutzern gemeldet werden.
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,
},
},
],
}),
}
});
Das Fehlerereignis wird jetzt in Ihren Google Analytics-Berichten angezeigt:
Debugging
Google Analytics bietet zwei hilfreiche Funktionen zum Debuggen von Analyseereignissen in Ihrer Erweiterung:
- Einen speziellen Fehlerbehebungsendpunkt
https://www.google-analytics.com**/debug**/mp/collect
, der alle Fehler in Ihren Ereignisdefinitionen meldet. - Den Google Analytics-Echtzeitbericht, in dem Ereignisse angezeigt werden, sobald sie eingehen