Questo tutorial mostra come monitorare l'utilizzo della tua estensione utilizzando Google
Analytics. Puoi trovare un esempio funzionante di Google Analytics 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 per monitorare l'estensione. Tieni presente che durante la configurazione dell'account puoi utilizzare qualsiasi valore nel campo URL del sito web, poiché l'estensione non avrà un proprio URL.
Utilizzare Measurement Protocol di Google Analytics
A partire da Manifest V3, le estensioni di Chrome non possono eseguire codice ospitato in remoto. Ciò significa che devi utilizzare il Measurement Protocol di Google Analytics per monitorare gli eventi delle estensioni. Measurement Protocol ti consente di inviare eventi direttamente ai server di Google Analytics con richieste HTTP. Un vantaggio di questo approccio è che ti consente di inviare eventi di dati e analisi da qualsiasi punto dell'estensione, incluso il service worker.
Configura le credenziali API
Per inviare eventi a Google Analytics, hai bisogno di un api_secret e di un
measurement_id. Consulta la documentazione di Measurement Protocol per scoprire di più sulle specifiche generali di Measurement Protocol.
Passaggio 1: crea uno stream di dati web
Poiché le estensioni di Chrome vengono monitorate come ambienti web, devi configurare uno stream di dati web nella proprietà Google Analytics:
- Vai alla pagina Amministrazione di Google Analytics.
- Nella colonna Proprietà, fai clic su Raccolta e modifica dei dati, poi seleziona Stream di dati.
- Fai clic su Aggiungi stream e poi su Web.
- Inserisci un URL segnaposto nel campo URL sito web (ad esempio,
https://extensiono l'URL di Chrome Web Store della tua estensione). - Inserisci un Nome stream (ad esempio,
My Chrome Extension). - Fai clic su Crea stream.
Una volta creato, l'ID misurazione (simile a G-XXXXXXXXXX) verrà visualizzato nella parte superiore della pagina dei dettagli dello stream.
Passaggio 2: genera un API secret di Measurement Protocol
Per generare il api_secret richiesto per Measurement Protocol, vai alle impostazioni dello stream di dati web che hai appena creato:
- Vai ad Amministrazione > Raccolta e modifica dei dati > Stream di dati e seleziona lo stream di dati web.
Nella sezione Eventi, fai clic su API secret di Measurement Protocol.
Se richiesto, leggi e accetta i termini del Measurement Protocol.
Fai clic su Crea.
Inserisci un nickname per il secret (ad esempio,
Chrome Extension Secret) e fai clic su Crea per generare il secret.Copia il valore del secret generato.
Genera un client_id
Il secondo passaggio consiste nel generare un identificatore univoco per un dispositivo/utente specifico,
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 = `${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 utilizzando 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
session_id e engagement_time_msec sono parametri consigliati quando
utilizzi 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 generare un nuovo ID sessione con ogni evento, ad esempio utilizzando un timestamp.
L'esempio seguente mostra un approccio che interrompe una nuova sessione
dopo 30 minuti senza eventi segnalati (questo tempo può essere personalizzato per
adattarsi meglio 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 è 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 del pulsante precedente. Per engagement_time_msec, è meglio
fornire il tempo trascorso dall'ultimo evento. Tuttavia, se non è fattibile, 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 getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
id: "my-button",
},
},
],
}),
}
);
L'evento verrà visualizzato nel report In tempo reale di Google Analytics nel seguente modo.
Monitorare le visualizzazioni di pagina nelle pagine popup, del riquadro laterale e delle estensioni
Il 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 tue finestre di dialogo,
le pagine dei menu, i riquadri laterali e le pagine delle estensioni 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 in corrispondenza dell'evento load del documento per un
menu delle estensioni:
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:
Monitorare gli 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 l'evento
unhandledrejection event nel service worker, puoi registrare eventuali
eccezioni non rilevate nel service worker in Google Analytics, il che può
aiutare notevolmente a eseguire il debug dei problemi che gli utenti potrebbero segnalare.
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,
},
},
],
}),
});
});
Ora puoi visualizzare l'evento di errore nei report Google Analytics:
Debug
Google Analytics offre due utili funzionalità per il debug degli eventi Analytics nella tua estensione:
- Un endpoint di debug speciale
https://www.google-analytics.com**/debug**/mp/collectche segnalerà eventuali errori nelle definizioni degli eventi. - Il report in tempo reale di Google Analytics che mostrerà gli eventi man mano che vengono registrati.