Utilizzare Google Analytics 4

Questo tutorial mostra come monitorare l'utilizzo della tua 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. Se hai bisogno di informazioni su come scrivere un'estensione, leggi il tutorial Guida introduttiva.

Devi anche configurare un account Google Analytics 4 per monitorare la tua 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 proprio URL.

Utilizzo di Measurement Protocol di Google Analytics

A partire da Manifest V3, le estensioni di Chrome non possono eseguire codice ospitato da remoto. Ciò significa che devi utilizzare il Measurement Protocol di Google Analytics per il monitoraggio degli eventi delle estensioni. Measurement Protocol ti consente di inviare 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 punto dell'estensione, incluso il service worker.

Configura le credenziali API

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

Genera un client_id

Il secondo passaggio consiste nel generare un identificatore univoco per un dispositivo/utente specifico, ovvero l'client_id. L'ID deve rimanere invariato finché l'estensione è installata sul browser di un utente. Può essere una stringa arbitraria, ma deve essere univoca per il cliente. Memorizza client_id in chrome.storage.local per assicurarti che rimanga invariato per tutta la durata dell'installazione dell'estensione.

L'utilizzo di chrome.storage.local richiede l'autorizzazione storage nel file manifest:

manifest.json:

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

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

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

Inviare un evento Analytics

Con le credenziali API e 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',
          },
        },
      ],
    }),
  }
);

In questo modo viene inviato un evento button_clicked che verrà visualizzato nel report sugli eventi di Google Analytics. Se vuoi visualizzare i tuoi 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 che engagement_time_msec sono parametri consigliati quando si utilizza Measurement Protocol di Google Analytics, in quanto sono necessari per visualizzare l'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 una nozione chiara di sessione utente. Pertanto, devi definire cosa significa una sessione utente nella tua estensione. Ad esempio, ogni nuova interazione dell'utente potrebbe essere una nuova sessione. In questo caso, puoi semplicemente generare un nuovo ID sessione con ogni evento (ad es. utilizzando un timestamp).

L'esempio seguente mostra un approccio che imposta il timeout di una nuova sessione dopo 30 minuti senza eventi segnalati (questo tempo può essere personalizzato per adattarsi meglio al comportamento degli utenti dell'estensione). L'esempio utilizza chrome.storage.session per archiviare la sessione attiva durante l'esecuzione del browser. Insieme alla sessione, memorizziamo l'ultima volta che è stato attivato un evento. 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;
}

L'esempio seguente aggiunge session_id e engagement_time_msec 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 nel seguente modo nel report in tempo reale di Google Analytics.

Eventi in tempo reale in Google Analytics.

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

Measurement Protocol di Google Analytics supporta un evento page_view speciale per il monitoraggio delle visualizzazioni di pagina. Utilizza questo evento per monitorare gli utenti che visitano le pagine popup, il riquadro laterale o una pagina di estensione in una nuova scheda. L'evento page_view richiede anche i parametri page_title e page_location. L'esempio seguente attiva un evento visualizzazione di pagina in corrispondenza dell'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 deve essere eseguito prima 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à visualizzata come qualsiasi altra visualizzazione di pagina nel report In tempo reale di Google Analytics:

Evento visualizzazione di pagina visualizzato nella dashboard in tempo reale di Google Analytics.

Monitoraggio degli eventi di analisi nei service worker

L'utilizzo di Measurement Protocol di Google Analytics consente di monitorare gli eventi di analisi nei service worker delle estensioni. Ad esempio, ascoltando unhandledrejection event nel service worker, puoi registrare eventuali eccezioni non rilevate nel service worker in Google Analytics, il che può essere di grande aiuto per eseguire il debug dei problemi che gli utenti potrebbero segnalare.

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

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

Evento di errore visualizzato nella dashboard degli eventi di Google Analytics.

Debug

Google Analytics offre due utili funzionalità per il debug degli eventi Analytics nella tua 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 mostrerà gli eventi man mano che vengono registrati.