In dieser Anleitung wird gezeigt, wie Sie die Nutzung Ihrer Erweiterung mit Google Analytics erfassen. Ein funktionierendes Google Analytics-Beispiel finden Sie auf GitHub. google-analytics.js enthält den gesamten Google Analytics-bezogenen Code.
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 das Tutorial für die ersten Schritte.
Außerdem müssen Sie ein Google Analytics-Konto einrichten, um Ihre Erweiterung zu analysieren. Beachten Sie, dass Sie beim Einrichten des Kontos einen beliebigen Wert im Feld „Website-URL“ verwenden können, 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 mit 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
Wenn Sie Ereignisse an Google Analytics senden möchten, benötigen Sie eine api_secret und eine measurement_id. Weitere Informationen zu den allgemeinen Spezifikationen des Measurement Protocol finden Sie in der Dokumentation zum Measurement Protocol.
Schritt 1: Web-Datenstream erstellen
Da Chrome-Erweiterungen als Webumgebungen erfasst werden, müssen Sie in Ihrer Google Analytics-Property einen Web-Datenstream einrichten:
- Rufen Sie die Google Analytics-Verwaltungsseite auf.
- Klicken Sie in der Spalte Property auf Datenerhebung und ‑änderung und wählen Sie dann Datenstreams aus.
- Klicken Sie auf Stream hinzufügen und dann auf Web.
- Geben Sie im Feld Website-URL eine beliebige Platzhalter-URL ein, z. B.
https://extensionoder die Chrome Web Store-URL Ihrer Erweiterung. - Geben Sie einen Stream-Namen ein, z. B.
My Chrome Extension. - Klicken Sie auf Stream erstellen.
Nachdem Sie den Datenstream erstellt haben, wird Ihre Mess-ID (z. B. G-XXXXXXXXXX) oben auf der Seite „Streamdetails“ angezeigt.
Schritt 2: Measurement Protocol – API-Secret generieren
So generieren Sie die api_secret, die für das Measurement Protocol erforderlich ist, navigieren Sie zu den Einstellungen für den Web-Datenstream, den Sie gerade erstellt haben:
- Klicken Sie auf Verwaltung > Datenerhebung und ‑änderung > Datenstreams und wählen Sie Ihren Web-Datenstream aus.
Klicken Sie im Bereich Ereignisse auf Measurement Protocol – API-Secrets.
Lesen und akzeptieren Sie die Nutzungsbedingungen für das Measurement Protocol, falls Sie dazu aufgefordert werden.
Klicken Sie auf Erstellen.
Geben Sie einen Alias für Ihr Secret ein (z. B.
Chrome Extension Secret) und klicken Sie auf Erstellen, um das Secret zu generieren.Kopieren Sie den generierten Secret value (Secret-Wert).
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 so lange gleich bleibt, wie die Erweiterung installiert ist.
Für die Verwendung von chrome.storage.local ist die Berechtigung storage in Ihrer 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 = `${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 mit einer 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 dem Echtzeitbericht 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 des Nutzers 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 für jedes Ereignis eine neue Sitzungs-ID generieren, z. B. mithilfe eines Zeitstempels.
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 Schaltflächen-Click-Event hinzugefügt. Für engagement_time_msec ist es am besten, die seit dem letzten Ereignis vergangene Zeit anzugeben. Wenn das nicht möglich ist, 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 getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
id: "my-button",
},
},
],
}),
}
);
Das Ereignis wird im Google Analytics-Echtzeitbericht so angezeigt:
Seitenaufrufe in Pop-ups, 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 Dialogfelder, Menüseiten, Seitenleisten und Erweiterungsseiten in einem neuen Tab aufrufen. 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 Erweiterungsmenü 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 Seitenaufruf in Google Analytics im Echtzeitbericht angezeigt:
Analyseereignisse in Service Workern erfassen
Mit dem Google Analytics Measurement Protocol können Sie Analyseereignisse in Service Workern für Erweiterungen erfassen. Wenn Sie beispielsweise auf das unhandledrejection event in Ihrem Service Worker warten, 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) => {
fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
{
method: "POST",
body: JSON.stringify({
client_id: await 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 getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
message: event.reason.message,
stack: event.reason.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.