Z tego samouczka dowiesz się, jak śledzić wykorzystanie rozszerzenia za pomocą Google Analytics. Działający przykład Google Analytics znajdziesz na GitHubie, gdzie google-analytics.js zawiera cały kod związany z Google Analytics.
Wymagania
W tym samouczku zakładamy, że wiesz, jak pisać rozszerzenia do Chrome. Jeśli potrzebujesz informacji o tym, jak napisać rozszerzenie, przeczytaj samouczek Pierwsze kroki.
Aby śledzić rozszerzenie, musisz też skonfigurować konto Google Analytics. Pamiętaj, że podczas konfigurowania konta możesz użyć dowolnej wartości w polu Adres URL witryny, ponieważ rozszerzenie nie będzie mieć własnego adresu URL.
Korzystanie z platformy Measurement Protocol Google Analytics
Od czasu wprowadzenia platformy Manifest V3 rozszerzenia Chrome nie mogą wykonywać kodu hostowanego zdalnie. Oznacza to, że do śledzenia zdarzeń rozszerzenia musisz używać platformy Measurement Protocol Google Analytics. Platforma Measurement Protocol umożliwia wysyłanie zdarzeń bezpośrednio do serwerów Google Analytics za pomocą żądań HTTP. Zaletą tego podejścia jest to, że umożliwia ono wysyłanie zdarzeń analitycznych z dowolnego miejsca w rozszerzeniu, w tym ze skryptu service worker.
Konfigurowanie danych logowania interfejsu API
Aby wysyłać zdarzenia do Google Analytics, potrzebujesz api_secret i measurement_id. Zapoznaj się z dokumentacją platformy Measurement Protocol, aby dowiedzieć się więcej o ogólnych specyfikacjach tej platformy.
Krok 1. Utwórz strumień danych z sieci
Rozszerzenia Chrome są śledzone jako środowiska internetowe, więc w usłudze w Google Analytics musisz skonfigurować strumień danych z sieci:
- Otwórz stronę Administracja w Google Analytics.
- W kolumnie Usługa kliknij Zbieranie i modyfikowanie danych, a następnie wybierz Strumienie danych.
- Kliknij Dodaj strumień, a potem Sieć.
- W polu Adres URL witryny wpisz dowolny adres URL zastępczy (np.
https://extensionlub adres URL rozszerzenia w Chrome Web Store). - Wpisz nazwę strumienia (np.
My Chrome Extension). - Kliknij Utwórz strumień.
Po utworzeniu identyfikator pomiaru (który wygląda jak G-XXXXXXXXXX) będzie wyświetlany u góry strony z informacjami o strumieniu.
Krok 2. Wygeneruj tajny klucz API platformy Measurement Protocol
Aby wygenerować api_secret wymagany w przypadku Measurement Protocol, otwórz ustawienia utworzonego właśnie strumienia danych z sieci:
- Kliknij Administracja > Zbieranie i modyfikowanie danych > Strumienie danych i wybierz strumień danych z sieci.
W sekcji Zdarzenia kliknij Tajne klucze API platformy Measurement Protocol.
Jeśli pojawi się taka prośba, przeczytaj i zaakceptuj warunki Measurement Protocol.
Kliknij Utwórz.
Wpisz nazwę tajnego klucza (np.
Chrome Extension Secret) i kliknij Utwórz, aby wygenerować tajny klucz.Skopiuj wygenerowaną wartość obiektu tajnego.
Wygeneruj client_id
Drugi etap to wygenerowanie unikalnego identyfikatora konkretnego urządzenia lub użytkownika, czyli 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. Zapisz client_id w chrome.storage.local, aby mieć pewność, że pozostanie on taki sam, dopóki rozszerzenie jest zainstalowane.
Korzystanie z chrome.storage.local wymaga uprawnienia storage w pliku manifestu:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Następnie możesz użyć chrome.storage.local, aby zapisać 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;
}
Wysyłanie zdarzenia analitycznego
Mając dane logowania API i client_id, możesz wysłać zdarzenie do Google Analytics 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',
},
},
],
}),
}
);
Wysyła to button_clickedzdarzenie, które pojawi się w raporcie zdarzeń w Google Analytics. Jeśli chcesz widzieć zdarzenia 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 parametr session_id, jak i engagement_time_msec są zalecane podczas korzystania z Measurement Protocol Google Analytics, ponieważ są wymagane, aby aktywność użytkowników była wyświetlana w standardowych raportach, takich jak Czas rzeczywisty.
session_id opisuje okres, w którym użytkownik wchodzi w interakcję z Twoim rozszerzeniem w sposób ciągły. 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 Twoim rozszerzeniu. Na przykład każda nowa interakcja użytkownika może być nową sesją. W takim przypadku możesz generować nowy identyfikator sesji przy każdym zdarzeniu, np. używając sygnatury czasowej.
Poniższy przykład pokazuje podejście, które spowoduje przekroczenie limitu czasu nowej sesji po 30 minutach od momentu, w którym nie zgłoszono żadnych zdarzeń (ten czas można dostosować do zachowań użytkowników rozszerzenia). W przykładzie użyto chrome.storage.session do przechowywania aktywnej sesji podczas działania przeglądarki. Wraz z sesją przechowujemy ostatni czas wywołania zdarzenia.
W ten sposób możemy sprawdzić, 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 do żądania zdarzenia kliknięcia poprzedniego przycisku dodano parametry session_id i engagement_time_msec. W przypadku engagement_time_msec najlepiej podać czas, który upłynął od ostatniego zdarzenia. Jeśli jednak nie jest to możliwe, 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 getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
id: "my-button",
},
},
],
}),
}
);
W raporcie Czas rzeczywisty w Google Analytics zdarzenie będzie wyświetlane w ten sposób:
Śledzenie wyświetleń stron w wyskakujących okienkach, panelach bocznych i stronach rozszerzeń
Protokół pomiarowy Google Analytics obsługuje specjalne zdarzenie page_view do śledzenia odsłon. Użyj tego parametru, aby śledzić użytkowników odwiedzających okna, strony menu, panele boczne i strony rozszerzeń w nowej karcie. Zdarzenie page_view wymaga też parametrów page_title i page_location. Poniższy przykład wywołuje zdarzenie wyświetlenia strony w przypadku zdarzenia load dokumentu w menu 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 musi zostać zaimportowany do pliku HTML wyskakującego okienka i powinien zostać uruchomiony 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>
Widok wyskakujący będzie wyświetlany w raporcie Czas rzeczywisty w Google Analytics tak samo jak każde inne odsłona strony:
Śledzenie zdarzeń analitycznych w procesach service worker
Korzystanie z platformy Google Analytics Measurement Protocol umożliwia śledzenie zdarzeń analitycznych w procesach roboczych usługi rozszerzenia. Na przykład nasłuchując zdarzenia unhandledrejection event w skrypcie service worker, możesz rejestrować w Google Analytics wszystkie nieobsłużone wyjątki w skrypcie service worker. Może to znacznie ułatwić debugowanie problemów zgłaszanych przez użytkowników.
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,
},
},
],
}),
});
});
W raportach Google Analytics możesz teraz zobaczyć zdarzenie błędu:
Debugowanie
Google Analytics udostępnia 2 przydatne funkcje do debugowania zdarzeń Analytics w rozszerzeniu:
- Specjalny punkt końcowy debugowania
https://www.google-analytics.com**/debug**/mp/collect, który będzie zgłaszać wszelkie błędy w definicjach zdarzeń. - Raport Czas rzeczywisty w Google Analytics, który będzie wyświetlać zdarzenia w miarę ich rejestrowania.