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.
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 met HTTP-verzoeken. Een voordeel van deze aanpak is dat u hiermee overal in uw extensie, inclusief uw service worker, analysegebeurtenissen kunt verzenden.
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:
- Ga naar de beheerderspagina van Google Analytics .
- Klik in de kolom 'Eigenschap' op 'Gegevensverzameling en -wijziging' en selecteer vervolgens 'Gegevensstromen' .
- Klik op Stream toevoegen en vervolgens op Web .
- Voer een willekeurige placeholder-URL in het veld Website-URL in (bijvoorbeeld
https://extensionof de URL van uw extensie in de Chrome Web Store). - Voer een streamnaam in (bijvoorbeeld:
My Chrome Extension). - 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:
- Ga naar Beheer > Gegevensverzameling en -wijziging > Gegevensstromen en selecteer uw webgegevensstroom.
Klik in het gedeelte 'Gebeurtenissen' op 'API-geheimen van het meetprotocol' .
Lees en accepteer de voorwaarden van het meetprotocol indien daarom wordt gevraagd.
Klik op 'Maken' .
Geef je geheime sleutel een bijnaam (bijvoorbeeld
Chrome Extension Secret') en klik op 'Maken' om de geheime sleutel te genereren.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 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 = `${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 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.
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 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.
Het Google Analytics Measurement Protocol ondersteunt een speciale page_view gebeurtenis voor het bijhouden van paginaweergaven. Gebruik deze om gebruikers te volgen die uw dialoogvensters, menupagina's, zijpanelen en extensiepagina's 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 extensiemenu:
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:
- Een speciaal debug-eindpunt
https://www.google-analytics.com**/debug**/mp/collectdat eventuele fouten in uw gebeurtenisdefinities rapporteert. - Het realtime rapport van Google Analytics toont gebeurtenissen zodra ze binnenkomen.