Google Analytics 4 verwenden

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.

Achtung:Bei Verwendung des Measurement Protocol sind einige Informationen wie die Standortbestimmung nicht enthalten.

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,
          },
        },
      ],
    }),
  }
});

Achtung:Durch Logging-Ausnahmen können versehentlich personenbezogene Daten offengelegt werden. Je nach Erweiterung müssen Sie möglicherweise alle Informationen aus dem Stacktrace entfernen, die nicht an Google Analytics gesendet werden sollen.

Das Fehlerereignis wird jetzt in Ihren Google Analytics-Berichten angezeigt:

Debugging

Google Analytics bietet zwei hilfreiche Funktionen zum Debuggen von Analyseereignissen in Ihrer Erweiterung:

1. Einen speziellen Fehlerbehebungsendpunkt https://www.google-analytics.com**/debug**/mp/collect, der alle Fehler in Ihren Ereignisdefinitionen meldet.
2. Den Google Analytics-Echtzeitbericht, in dem Ereignisse angezeigt werden, sobald sie eingehen