W tym samouczku pokazujemy, jak śledzić wykorzystanie rozszerzenia za pomocą Google Analytics. Praktyczny przykład działania Google Analytics 4 znajdziesz na GitHubie, gdzie google-analytics.js zawiera cały kod związany z Google Analytics.
Wymagania
W tym samouczku zakładamy, że umiesz tworzyć rozszerzenia do Chrome. Jeśli potrzebujesz informacji o tym, jak napisać rozszerzenie, przeczytaj samouczek dla początkujących.
Aby śledzić rozszerzenie, musisz też skonfigurować konto Google Analytics 4. Pamiętaj, że podczas konfigurowania konta możesz użyć dowolnej wartości w polu Adres URL witryny, ponieważ rozszerzenie nie ma własnego adresu URL.
Korzystanie z platformy Google Analytics Measurement Protocol
Od platformy Manifest V3 rozszerzenia do Chrome nie mogą wykonywać kodu hostowanego zdalnie. Oznacza to, że do śledzenia zdarzeń związanych z rozszerzeniem musisz używać platformy Google Analytics Measurement Protocol. Measurement Protocol umożliwia wysyłanie zdarzeń bezpośrednio na serwery Google Analytics za pomocą żądań HTTP. Zaletą tego podejścia jest to, że umożliwia wysyłanie zdarzeń analitycznych z dowolnego miejsca w rozszerzeniu, w tym z skryptu service worker.
Skonfiguruj dane logowania do interfejsu API
Pierwszym krokiem jest uzyskanie api_secret i measurement_id. Aby uzyskać te informacje na koncie Analytics, postępuj zgodnie z dokumentacją Measurement Protocol.
Wygeneruj client_id
Drugim krokiem jest wygenerowanie unikalnego identyfikatora określonego urządzenia/użytkownika – client_id. Identyfikator powinien pozostać taki sam, o ile rozszerzenie jest zainstalowane w przeglądarce użytkownika. Może to być dowolny ciąg znaków, ale powinien być unikalny dla klienta. Możesz go wygenerować, wywołując self.crypto.randomUUID(). Zapisz parametr client_id w usłudze chrome.storage.local, aby mieć pewność, że się nie zmieni, dopóki masz zainstalowane rozszerzenie.
Używanie usługi chrome.storage.local wymaga uprawnienia storage w pliku manifestu:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Następnie możesz użyć chrome.storage.local do przechowywania 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;
}
Wyślij zdarzenie Analytics
Dane logowania do interfejsu API i client_id możesz wysyłać do Google Analytics zdarzenie za pomocą żądania 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',
},
},
],
}),
}
);
Spowoduje to wysłanie zdarzenia button_clicked, które pojawi się w raporcie Zdarzenia Google Analytics. Jeśli chcesz, aby zdarzenia były widoczne w raporcie Czas rzeczywisty w Google Analytics, musisz podać 2 dodatkowe parametry: session_id i engagement_time_msec.
Użyj zalecanych parametrów session_id i engagement_time_msec
Zarówno session_id, jak i engagement_time_msec są parametrami zalecanymi podczas korzystania z platformy Google Analytics Measurement Protocol, ponieważ są niezbędne do wyświetlania aktywności użytkownika w standardowych raportach, np. w czasie rzeczywistym.
session_id określa czas, w którym użytkownik stale korzysta z rozszerzenia. Domyślnie sesja kończy się po 30 minutach braku aktywności użytkownika. Nie ma ograniczenia długości sesji.
W rozszerzeniach do Chrome, w przeciwieństwie do zwykłych witryn, nie ma jasnego pojęcia sesji użytkownika. Dlatego musisz zdefiniować, co oznacza sesja użytkownika w rozszerzeniu. Na przykład każda nowa interakcja z użytkownikiem może być nową sesją. W takim przypadku możesz po prostu wygenerować nowy identyfikator sesji dla każdego zdarzenia (za pomocą sygnatury czasowej).
Poniższy przykład ilustruje metodę, która powoduje wygaszanie nowej sesji po upływie 30 minut od zarejestrowania żadnych zdarzeń (ten czas można dostosować do zachowania użytkownika rozszerzenia). W tym przykładzie użyliśmy metody chrome.storage.session do przechowywania aktywnej sesji, gdy przeglądarka jest uruchomiona. Razem z sesją przechowujemy informacje o ostatnim wywołaniu zdarzenia. Dzięki temu dowiemy się, czy aktywna sesja wygasła:
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;
}
W tym przykładzie dodano atrybuty session_id i engagement_time_msec do poprzedniego żądania zdarzenia kliknięcia przycisku. Dla funkcji engagement_time_msec możesz podać wartość domyślną 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",
},
},
],
}),
}
);
Zdarzenie będzie wyświetlane w raporcie Czas rzeczywisty w Google Analytics w podany niżej sposób.
Śledzenie wyświetleń stron w wyskakujących okienkach, panelu bocznym i stronach rozszerzeń
Platforma Google Analytics Measurement Protocol obsługuje specjalne zdarzenie page_view służące do śledzenia wyświetleń strony. Służy do śledzenia użytkowników, którzy odwiedzają wyskakujące okienka, panel boczny lub stronę rozszerzenia w nowej karcie. Zdarzenie page_view wymaga też parametrów page_title i page_location. Ten przykład powoduje uruchomienie zdarzenia wyświetlenia strony w wyniku zdarzenia load dokumentu w wyskakującym okienku rozszerzenia:
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
},
},
],
}),
});
});
Skrypt popup.js należy zaimportować do pliku HTML wyskakującego okienka i uruchomić przed wykonaniem jakiegokolwiek innego skryptu:
<!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>
Wyskakujące okienko będzie wyświetlane w raporcie Czas rzeczywisty w Google Analytics tak jak każdy inny widok strony:
Śledzenie zdarzeń Analytics w skryptach service worker
Korzystając z platformy Google Analytics Measurement Protocol, można śledzić zdarzenia Analytics w skryptach usług rozszerzeń. Na przykład, nasłuchując unhandledrejection event w skrypcie service worker, możesz rejestrować w Google Analytics wszystkie niewykryte wyjątki, co znacznie ułatwia debugowanie problemów zgłaszanych przez użytkowników.
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,
},
},
],
}),
}
});
Zdarzenie błędu będzie teraz widoczne w raportach Google Analytics:
Debugowanie
Google Analytics udostępnia 2 przydatne funkcje debugowania zdarzeń Analytics w rozszerzeniu:
- Specjalny punkt końcowy debugowania
https://www.google-analytics.com**/debug**/mp/collect, który zgłasza wszystkie błędy w definicjach zdarzeń. - Raport Czas rzeczywisty w Google Analytics, który wyświetla zdarzenia na bieżąco.