Deze pagina is vertaald door de Cloud Translation API.

Gebruik Google Analytics4

Deze handleiding laat zien hoe u het gebruik van uw extensie kunt bijhouden met Google Analytics. U vindt een werkend voorbeeld van Google Analytics 4 op GitHub , waar het bestand google-analytics.js alle code bevat die nodig is voor Google Analytics.

Vereisten

Deze handleiding gaat ervan uit dat u bekend bent met het schrijven van Chrome-extensies. Als u meer informatie nodig hebt over het schrijven van een extensie, lees dan de handleiding 'Aan de slag' .

Je moet ook een Google Analytics 4-account instellen om je extensie te volgen. Houd er rekening mee dat je bij het instellen van het account elke waarde kunt gebruiken in het veld 'Website-URL', aangezien je extensie geen eigen URL heeft.

Gebruikmaken van het Google Analytics-meetprotocol

Sinds Manifest V3 is het Chrome-extensies niet toegestaan om code uit te voeren die op een externe server wordt gehost . Dit betekent dat u het Google Analytics Measurement Protocol moet gebruiken om gebeurtenissen in uw extensie bij te houden. Met het Measurement Protocol kunt u gebeurtenissen rechtstreeks naar de Google Analytics-servers sturen via HTTP-verzoeken. Een voordeel van deze aanpak is dat u hiermee overal in uw extensie analysegebeurtenissen kunt verzenden, zelfs vanuit uw service worker.

API-referenties instellen

The first step is to obtain an api_secret and measurement_id . Follow the Measurement Protocol documentation for how to get these for your Analytics Account.

Genereer een `client_id`

De tweede stap is het genereren van een unieke identificatiecode voor een specifiek apparaat/gebruiker, de client_id . Deze ID moet hetzelfde blijven zolang de extensie in de browser van de gebruiker is geïnstalleerd. Het kan een willekeurige tekenreeks zijn, maar moet uniek zijn voor de client. Sla de client_id op in chrome.storage.local om ervoor te zorgen dat deze hetzelfde blijft zolang de extensie is geïnstalleerd.

Voor het gebruik van chrome.storage.local is de storage in uw manifestbestand vereist:

manifest.json:

{
  …
  "permissions": ["storage"],
  …
}

Vervolgens kun je chrome.storage.local gebruiken om de client_id op te slaan:

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;
}

Verzend een analysegebeurtenis

Met de API-gegevens en de client_id kunt u een gebeurtenis naar Google Analytics verzenden via een fetch -verzoek:

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

This sends a button_clicked event which will appear in your Google Analytics events report . If you want to see your events in the Google Analytics Realtime Report , you need to provide two additional parameters: session_id and engagement_time_msec .

Gebruik de aanbevolen parameters `session_id` en `engagement_time_msec`

Zowel session_id als engagement_time_msec zijn aanbevolen parameters bij gebruik van het Google Analytics Measurement Protocol, omdat ze nodig zijn om gebruikersactiviteit weer te geven in standaardrapporten zoals Realtime.

Een session_id beschrijft een tijdsperiode waarin een gebruiker continu interactie heeft met uw extensie. Standaard eindigt een sessie na 30 minuten inactiviteit van de gebruiker. Er is geen limiet aan de duur van een sessie.

In Chrome-extensies bestaat, in tegenstelling tot normale websites, geen duidelijk concept van een gebruikerssessie. Daarom moet u in uw extensie definiëren wat een gebruikerssessie inhoudt. Elke nieuwe gebruikersinteractie zou bijvoorbeeld een nieuwe sessie kunnen zijn. In dat geval kunt u eenvoudigweg bij elke gebeurtenis een nieuwe sessie-ID genereren (bijvoorbeeld met behulp van een tijdstempel).

Het volgende voorbeeld demonstreert een aanpak die een nieuwe sessie na 30 minuten beëindigt als er geen gebeurtenissen worden gerapporteerd (deze tijd kan worden aangepast aan het gebruikersgedrag van uw extensie). Het voorbeeld gebruikt chrome.storage.session om de actieve sessie op te slaan terwijl de browser actief is. Samen met de sessie slaan we het tijdstip op waarop de laatste gebeurtenis plaatsvond. Op deze manier kunnen we vaststellen of de actieve sessie is verlopen.

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;
}

Het volgende voorbeeld voegt session_id en engagement_time_msec toe aan het verzoek voor de klikgebeurtenis van de vorige knop. Voor engagement_time_msec kunt u een standaardwaarde van 100 ms opgeven.

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

De gebeurtenis wordt als volgt weergegeven in het realtime rapport van Google Analytics.

Realtime gebeurtenissen in Google Analytics.

Het bijhouden van paginaweergaven in pop-up-, zijpaneel- en extensiepagina's.

Het Google Analytics Measurement Protocol ondersteunt een speciale page_view gebeurtenis voor het bijhouden van paginaweergaven. Gebruik deze om gebruikers te volgen die uw pop-uppagina's, zijpaneel of een extensiepagina in een nieuw tabblad bezoeken. De page_view gebeurtenis vereist ook de parameters page_title en page_location . Het volgende voorbeeld activeert een `page_view`-gebeurtenis bij de `document load gebeurtenis voor een extensie-pop-up:

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

Het script popup.js moet in het HTML-bestand van je pop-up worden geïmporteerd en moet worden uitgevoerd voordat andere scripts worden uitgevoerd:

<!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>

De pop-upweergave wordt in het realtime rapport van Google Analytics op dezelfde manier weergegeven als elke andere paginaweergave:

De gebeurtenis 'Paginaweergave' zoals deze wordt weergegeven in het realtime dashboard van Google Analytics.

Het volgen van analysegebeurtenissen bij servicemedewerkers

Using the Google Analytics Measurement Protocol makes it possible to track analytics events in extension service workers. For example, by listening to the unhandledrejection event in your service worker, you can log any uncaught exceptions in your service worker to Google Analytics, which can greatly help to debug problems your users might report.

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

Je kunt de foutmelding nu zien in je Google Analytics-rapporten:

Foutmelding zoals deze wordt weergegeven in het Google Analytics-dashboard.

Foutopsporing

Google Analytics biedt twee handige functies voor het debuggen van analysegebeurtenissen in uw extensie:

A special debugging endpoint https://www.google-analytics.com**/debug**/mp/collect that will report any errors in your event definitions.
Het realtime rapport van Google Analytics toont gebeurtenissen zodra ze binnenkomen.