Utilizzare Google Analytics 4

Questo tutorial illustra come monitorare l'utilizzo dell'estensione utilizzando Google Analytics. Puoi trovare un esempio funzionante di Google Analytics 4 su GitHub, dove google-analytics.js include tutto il codice correlato a Google Analytics.

Requisiti

Questo tutorial presuppone che tu abbia familiarità con la scrittura di estensioni di Chrome. Per informazioni su come scrivere un'estensione, consulta il tutorial introduttivo.

Devi anche configurare un account Google Analytics 4 per monitorare l'estensione. Tieni presente che durante la configurazione dell'account puoi utilizzare qualsiasi valore nel campo URL del sito web, in quanto l'estensione non avrà un URL proprio.

Utilizzo del Measurement Protocol di Google Analytics

A partire da Manifest V3, le estensioni di Chrome non sono autorizzate a eseguire codice ospitato in remoto. Ciò significa che devi utilizzare il Measurement Protocol di Google Analytics per monitorare gli eventi delle estensioni. Measurement Protocol consente di inviare gli eventi direttamente ai server di Google Analytics tramite richieste HTTP. Un vantaggio di questo approccio è che ti consente di inviare eventi di analisi da qualsiasi posizione all'interno dell'estensione, incluso il service worker.

Attenzione: se utilizzi Measurement Protocol, alcune informazioni, come la geolocalizzazione, non saranno incluse.

Configurare le credenziali API

Il primo passaggio consiste nell'ottenere un api_secret e un measurement_id. Consulta la documentazione di Measurement Protocol per informazioni su come ottenerle per il tuo account Analytics.

Genera un client_id

Il secondo passaggio consiste nel generare un identificatore univoco per un dispositivo/utente specifico, client_id. L'ID dovrebbe rimanere lo stesso, a condizione che l'estensione sia installata sul browser dell'utente. Può essere una stringa arbitraria, ma deve essere univoca per il client. Puoi generarne uno chiamando self.crypto.randomUUID(). Memorizza client_id in chrome.storage.local per assicurarti che rimanga invariato finché l'estensione viene installata.

Per utilizzare chrome.storage.local è necessaria l'autorizzazione storage nel file manifest:

manifest.json:

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

Dopodiché puoi utilizzare chrome.storage.local per archiviare client_id:

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

Invia un evento di analisi

Con le credenziali dell'API e il client_id, puoi inviare un evento a Google Analytics tramite una richiesta fetch:

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

Viene inviato un evento button_clicked che verrà visualizzato nel report Eventi di Google Analytics. Se vuoi visualizzare gli eventi nel report in tempo reale di Google Analytics, devi fornire due parametri aggiuntivi: session_id e engagement_time_msec.

Utilizza i parametri consigliati session_id e engagement_time_msec

Sia session_id sia engagement_time_msec sono parametri consigliati quando si utilizza il Measurement Protocol di Google Analytics, in quanto sono necessari per la visualizzazione dell'attività utente nei report standard come In tempo reale.

Un session_id descrive un periodo di tempo durante il quale un utente interagisce continuamente con la tua estensione. Per impostazione predefinita, una sessione termina dopo 30 minuti di inattività dell'utente. Non esiste un limite alla durata di una sessione.

Nelle estensioni di Chrome, a differenza dei normali siti web, non esiste un'idea chiara di una sessione utente. Di conseguenza, devi definire il significato di una sessione utente nell'estensione. Ad esempio, ogni nuova interazione utente potrebbe essere una nuova sessione. In tal caso, puoi semplicemente generare un nuovo ID sessione per ogni evento (ovvero utilizzando un timestamp).

L'esempio seguente mostra un approccio che determina il timeout di una nuova sessione dopo 30 minuti dall'assenza di eventi segnalati (questa volta può essere personalizzato in base al comportamento degli utenti della tua estensione). L'esempio utilizza chrome.storage.session per archiviare la sessione attiva mentre il browser è in esecuzione. Insieme alla sessione memorizziamo l'ultima volta che un evento è stato attivato. In questo modo possiamo sapere se la sessione attiva è scaduta:

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

Nell'esempio seguente, session_id e engagement_time_msec vengono aggiunti alla richiesta di evento di clic sul pulsante precedente. Per engagement_time_msec puoi fornire un valore predefinito di 100 ms.

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

L'evento verrà visualizzato come segue nel report In tempo reale di Google Analytics.

Monitoraggio delle visualizzazioni di pagina in popup, riquadro laterale e pagine delle estensioni

Measurement Protocol supporta un evento page_view speciale per il monitoraggio delle visualizzazioni di pagina. Utilizzalo per monitorare gli utenti che visitano le tue pagine popup, il riquadro laterale o la pagina di un'estensione in una nuova scheda. L'evento page_view richiede anche i parametri page_title e page_location. L'esempio seguente attiva un evento di visualizzazione di pagina nell'evento load del documento per un popup dell'estensione:

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

Lo script popup.js deve essere importato nel file html del popup e dovrebbe essere eseguito prima dell'esecuzione di qualsiasi altro script:

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

La visualizzazione popup verrà mostrata come qualsiasi altra visualizzazione di pagina nel report In tempo reale di Google Analytics:

Monitoraggio degli eventi di analisi nei Service worker

Measurement Protocol consente di monitorare gli eventi di analisi nei Service worker dell'estensione. Ad esempio, ascoltando unhandledrejection event nel service worker puoi registrare in Google Analytics tutte le eccezioni non rilevate nel service worker, che può essere molto utile per risolvere i problemi segnalati dagli utenti.

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

Attenzione:le eccezioni di Logging potrebbero rivelare accidentalmente informazioni personali. A seconda dell'estensione, potrebbe essere necessario rimuovere dall'analisi dello stack tutte le informazioni che non devono essere inviate a Google Analytics.

Ora puoi visualizzare l'evento di errore nei report di Google Analytics:

Debug

Google Analytics offre due utili funzionalità per il debug degli eventi di analisi nell'estensione:

1. Un endpoint di debug speciale https://www.google-analytics.com**/debug**/mp/collect che segnalerà eventuali errori nelle definizioni degli eventi.
2. Il report In tempo reale di Google Analytics che mostra gli eventi non appena arrivano.