In diesem Tutorial wird gezeigt, wie Sie die Nutzung Ihrer Erweiterung mit Google Analytics erfassen. Ein funktionierendes Google Analytics 4-Beispiel finden Sie auf GitHub. Der gesamte Google Analytics-bezogene Code ist in google-analytics.js enthalten.
Voraussetzungen
In dieser Anleitung wird davon ausgegangen, dass Sie mit dem Schreiben von Chrome-Erweiterungen vertraut sind. Wenn Sie Informationen zum Schreiben einer Erweiterung benötigen, lesen Sie bitte die Anleitung für den Einstieg.
Außerdem müssen Sie ein Google Analytics 4-Konto einrichten, um Ihre Erweiterung zu analysieren. Beim Einrichten des Kontos können Sie einen beliebigen Wert im Feld „Website-URL“ verwenden, da Ihre Erweiterung keine eigene URL hat.
Google Analytics Measurement Protocol verwenden
Seit Manifest V3 dürfen Chrome-Erweiterungen keinen remote gehosteten Code ausführen. Das bedeutet, dass Sie das Google Analytics Measurement Protocol verwenden müssen, um Erweiterungsereignisse zu erfassen. Mit dem Measurement Protocol können Sie Ereignisse über HTTP-Anfragen direkt an Google Analytics-Server senden. Ein Vorteil dieses Ansatzes ist, dass Sie Analyseereignisse von überall in Ihrer Erweiterung senden können, auch von Ihrem Service Worker.
API-Anmeldedaten einrichten
Im ersten Schritt müssen Sie ein api_secret und ein measurement_id abrufen. In der Measurement Protocol-Dokumentation finden Sie Informationen dazu, 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/einen bestimmten Nutzer generiert, die client_id. Die ID sollte gleich bleiben, solange die Erweiterung im Browser eines Nutzers installiert ist. Es kann ein beliebiger String sein, sollte aber für den Client eindeutig sein. Speichern Sie die client_id in chrome.storage.local, damit sie sich nicht ändert, solange die Erweiterung installiert ist.
Für die Verwendung von chrome.storage.local ist die Berechtigung storage in der Manifestdatei erforderlich:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Anschließend können Sie chrome.storage.local verwenden, um die client_id zu speichern:
function getRandomId() {
const digits = '123456789'.split('');
let result = '';
for (let i = 0; i < 10; i++) {
result += digits[Math.floor(Math.random() * 9)];
}
return result;
}
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. We use
// the <number>.<number> format since this is typical for GA client IDs.
const unixTimestampSeconds = Math.floor(new Date().getTime() / 1000);
clientId = `${this.getRandomId()}.${unixTimestampSeconds}`;
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 in Ihrem Google Analytics-Ereignisbericht 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.
Empfohlene Parameter session_id und engagement_time_msec verwenden
Sowohl session_id als auch engagement_time_msec sind empfohlene Parameter bei Verwendung des Google Analytics Measurement Protocol, da sie erforderlich sind, damit Nutzeraktivitäten in Standardberichten wie „Echtzeit“ angezeigt werden.
Eine session_id beschreibt einen Zeitraum, in dem ein Nutzer kontinuierlich mit Ihrer Erweiterung interagiert. Standardmäßig wird eine Sitzung nach 30 Minuten Inaktivität beendet. Es gibt keine Begrenzung für die Dauer einer Sitzung.
Im Gegensatz zu normalen Websites gibt es bei Chrome-Erweiterungen keine klare Vorstellung von einer Nutzersitzung. Daher müssen Sie definieren, was eine Nutzersitzung in Ihrer Erweiterung bedeutet. Jede neue Nutzerinteraktion kann beispielsweise eine neue Sitzung sein. In diesem Fall können Sie einfach mit jedem Ereignis eine neue Sitzungs-ID generieren (z.B. mit einem Zeitstempel).
Im folgenden Beispiel wird gezeigt, wie eine neue Sitzung nach 30 Minuten ohne gemeldete Ereignisse beendet wird. Diese Zeit kann angepasst werden, um dem Nutzerverhalten Ihrer Erweiterung besser gerecht zu werden. Im 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 den Zeitpunkt, zu dem zuletzt ein Ereignis 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 der vorherigen Anfrage für das Ereignis „Schaltflächenklick“ 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 so angezeigt:
Seitenaufrufe in Pop-up-, Seitenleisten- und Erweiterungsseiten erfassen
Das Google Analytics Measurement Protocol unterstützt ein spezielles page_view-Ereignis zum Erfassen von Seitenaufrufen. Damit können Sie Nutzer erfassen, die Ihre Pop-up-Seiten, die Seitenleiste oder eine Erweiterungsseite in einem neuen Tab besuchen. Für das Ereignis page_view sind auch die Parameter page_title und page_location erforderlich. Im folgenden Beispiel wird ein Seitenaufrufereignis beim load-Ereignis des Dokuments 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 popup.js-Script muss in die HTML-Datei Ihres Pop-ups importiert werden und sollte vor allen anderen Scripts ausgeführt werden:
<!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 jede andere Seitenaufrufe im Google Analytics-Echtzeitbericht angezeigt:
Analyseereignisse in Service Workern erfassen
Mit dem Google Analytics Measurement Protocol lassen sich Analyseereignisse in Service Workern für Erweiterungen erfassen. Wenn Sie beispielsweise auf das unhandledrejection event in Ihrem Service Worker achten, 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 Nutzer melden.
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 Analytics-Ereignissen in Ihrer Erweiterung:
- Ein spezieller Debugging-Endpunkt
https://www.google-analytics.com**/debug**/mp/collect, der alle Fehler in Ihren Ereignisdefinitionen meldet. - Der Google Analytics-Echtzeitbericht, in dem Ereignisse angezeigt werden, sobald sie eingehen.