Gebruik Google Analytics

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

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

Gebruik het Google Analytics-meetprotocol.

Since Manifest V3, Chrome Extensions are not allowed to execute remote hosted code . This means you have to use the Google Analytics Measurement Protocol for tracking extension events. The Measurement Protocol lets you send events directly to Google Analytics servers with HTTP requests. A benefit of this approach is that it lets you send analytics events from everywhere in your extension, including your service worker.

API-referenties instellen

Om gebeurtenissen naar Google Analytics te verzenden, hebt u een api_secret en een measurement_id nodig. Raadpleeg de documentatie van het Measurement Protocol voor meer informatie over de algemene specificaties van het Measurement Protocol.

Stap 1: Een webdatastroom creëren

Omdat Chrome-extensies worden bijgehouden als webomgevingen, moet u een webgegevensstroom instellen in uw Google Analytics-property:

1. Ga naar de beheerderspagina van Google Analytics .
2. Klik in de kolom 'Eigenschap' op 'Gegevensverzameling en -wijziging' en selecteer vervolgens 'Gegevensstromen' .
3. Klik op Stream toevoegen en vervolgens op Web .
4. Voer een willekeurige placeholder-URL in het veld Website-URL in (bijvoorbeeld https://extension of de URL van uw extensie in de Chrome Web Store).
5. Voer een streamnaam in (bijvoorbeeld: My Chrome Extension ).
6. Klik op Stream maken .

Zodra uw meet-ID (die eruitziet als G-XXXXXXXXXX ) is aangemaakt, wordt deze bovenaan de pagina met streamdetails weergegeven.

Stap 2: Genereer een API-geheim voor het meetprotocol

Om de api_secret te genereren die nodig is voor het meetprotocol, ga je naar de instellingen van de webdatastroom die je zojuist hebt aangemaakt:

1. Ga naar Beheer > Gegevensverzameling en -wijziging > Gegevensstromen en selecteer uw webgegevensstroom.

2. Klik in het gedeelte 'Gebeurtenissen' op 'API-geheimen van het meetprotocol' .

3. Lees en accepteer de voorwaarden van het meetprotocol indien daarom wordt gevraagd.

4. Klik op 'Maken' .

5. Geef je geheime sleutel een bijnaam (bijvoorbeeld Chrome Extension Secret ') en klik op 'Maken' om de geheime sleutel te genereren.

6. Kopieer de gegenereerde geheime waarde .

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 browser.storage.local om ervoor te zorgen dat deze hetzelfde blijft zolang de extensie is geïnstalleerd.

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

manifest.json:

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

Vervolgens kunt u browser.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 browser.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 browser.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 met behulp van 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',
          },
        },
      ],
    }),
  }
);

Dit verzendt een button_clicked gebeurtenis die in uw Google Analytics-gebeurtenissenrapport verschijnt. Als u uw gebeurtenissen in het realtime rapport van Google Analytics wilt zien, moet u twee extra parameters opgeven: session_id en 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 bij elke gebeurtenis een nieuwe sessie-ID genereren, bijvoorbeeld met behulp van een tijdstempel.

The following example demonstrates an approach that will timeout a new session after 30 minutes of no events being reported (this time can be customized to better suit your extension's user behavior). The example uses browser.storage.session to store the active session while the browser is running. Together with the session we store the last time an event was fired. This way we can tell if the active session has expired:

const SESSION_EXPIRATION_IN_MIN = 30;

async function getOrCreateSessionId() {
  // Store session in memory storage
  let {sessionData} = await browser.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 browser.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await browser.storage.session.set({sessionData});
  }
  return sessionData.session_id;
}

Het volgende voorbeeld voegt session_id en engagement_time_msec toe aan het verzoek voor de vorige klik op de knop. Voor engagement_time_msec kunt u het beste de verstreken tijd sinds de laatste gebeurtenis opgeven. Als dit echter niet mogelijk is, kunt u een standaardwaarde van 100 ms gebruiken.

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

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

Volg het aantal paginaweergaven in pop-upvensters, zijpanelen en extensiepagina's.

The Google Analytics Measurement Protocol supports a special page_view event for tracking page views. Use this to track users visiting your dialog boxes, menu pages, side panels, and extension pages in a new tab. The page_view event also requires the page_title and page_location parameters. The following example fires a page view event at the document load event for an extension menu:

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:

Volg analysegebeurtenissen bij servicemedewerkers

Met behulp van het Google Analytics Measurement Protocol is het mogelijk om analysegebeurtenissen in service workers van extensies te volgen. Door bijvoorbeeld te luisteren naar de unhandledrejection event in uw service worker, kunt u alle niet-afgevangen uitzonderingen in uw service worker loggen in Google Analytics. Dit kan enorm helpen bij het oplossen van problemen die uw gebruikers mogelijk 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,
          },
        },
      ],
    }),
  });
});

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

Foutopsporing

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

1. Een speciaal debug-eindpunt https://www.google-analytics.com**/debug**/mp/collect dat eventuele fouten in uw gebeurtenisdefinities rapporteert.
2. Het realtime rapport van Google Analytics toont gebeurtenissen zodra ze binnenkomen.