Użyj Google Analytics 4

W tym samouczku pokazujemy, jak śledzić wykorzystanie rozszerzenia za pomocą Google Analytics. Na GitHubie znajdziesz sprawną próbkę Google Analytics 4, 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, 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 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ą uruchamiać kodu hostowanego zdalnie. Oznacza to, że do śledzenia zdarzeń rozszerzeń musisz korzystać z 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 ono 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. Zapoznaj się z dokumentacją platformy Measurement Protocol, aby dowiedzieć się, jak pobierać te dane na konto Analytics.

Wygeneruj client_id

Drugim krokiem jest wygenerowanie unikalnego identyfikatora dla 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, ale powinien być unikalny dla klienta. Aby go wygenerować, zadzwoń pod numer self.crypto.randomUUID(). Rozszerzenie client_id zapisz w usłudze chrome.storage.local, aby pozostawało bez zmian do czasu zainstalowania rozszerzenia.

Użycie usługi chrome.storage.local wymaga uprawnienia storage w pliku manifestu:

manifest.json:

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

Potem możesz używać chrome.storage.local do przechowywania tych elementów (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;
}

Wysyłanie zdarzenia analitycznego

Korzystając z danych logowania do interfejsu API i identyfikatora client_id, możesz wysył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',
          },
        },
      ],
    }),
  }
);

Spowoduje to wysłanie zdarzenia button_clicked, które pojawi się w raporcie Zdarzenia w Google Analytics. Jeśli chcesz widzieć swoje zdarzenia w raporcie Czas rzeczywisty w Google Analytics, musisz podać 2 dodatkowe parametry: session_id i engagement_time_msec.

Używaj zalecanych parametrów session_id i engagement_time_msec

Parametry session_id i engagement_time_msec są zalecanymi parametrami w ramach platformy Google Analytics Measurement Protocol, ponieważ są wymagane do wyświetlania aktywności użytkowników w standardowych raportach, np. w czasie rzeczywistym.

session_id to 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 przypadku rozszerzeń do Chrome, w przeciwieństwie do zwykłych witryn, nie ma wyraźnego pojęcia o sesji użytkownika. Musisz więc zdefiniować w rozszerzeniu, co oznacza sesja użytkownika. Na przykład każda interakcja nowego użytkownika może być nową sesją. W takim przypadku możesz po prostu generować dla każdego zdarzenia nowy identyfikator sesji (na podstawie sygnatury czasowej).

Poniższy przykład pokazuje metodę polegającą na przekroczeniu limitu czasu nowej sesji po upływie 30 minut od momentu, gdy nie zostaną zgłoszone żadne zdarzenia (ten czas można dostosować do sposobu działania rozszerzenia). W tym przykładzie wykorzystywana jest właściwość chrome.storage.session do przechowywania aktywnej sesji, gdy przeglądarka jest uruchomiona. Razem z sesją zapisujemy informację o ostatnim wywołaniu zdarzenia. Dzięki temu wiemy, czy aktywna sesja nie 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 poniższym przykładzie dodano session_id i engagement_time_msec do poprzedniego żądania zdarzenia kliknięcia przycisku. W polu 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 ten sposób:

Śledzenie wyświetleń stron w wyskakujących okienkach, panelu bocznym i rozszerzeniach

Google Analytics Measurement Protocol obsługuje specjalne zdarzenie page_view do śledzenia wyświetleń stron. Umożliwia śledzenie użytkowników odwiedzających 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 wywołuje zdarzenie wyświetlenia strony w zdarzeniu load dokumentu dla wyskakującego okienka 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 musisz zaimportować do pliku HTML wyskakującego okienka i powinien być uruchamiany 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ącego okienka jest wyświetlany w raporcie Czas rzeczywisty w Google Analytics tak samo jak każdy inny widok strony:

Śledzenie zdarzeń analitycznych w skryptach service worker

Protokół Google Analytics Measurement Protocol umożliwia śledzenie zdarzeń analitycznych w skryptach service worker. Na przykład nasłuchując unhandledrejection event w skrypcie service worker, możesz rejestrować w Google Analytics wszystkie niewyłapane wyjątki, co może bardzo pomóc w debugowaniu 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,
          },
        },
      ],
    }),
  }
});

Możesz teraz zobaczyć w raportach Google Analytics zdarzenie błędu:

Debugowanie

Google Analytics udostępnia 2 przydatne funkcje do debugowania zdarzeń analitycznych w rozszerzeniu:

1. Specjalny punkt końcowy debugowania https://www.google-analytics.com**/debug**/mp/collect, który zgłasza wszelkie błędy w definicjach zdarzeń.
2. Raport Czas rzeczywisty w Google Analytics, który pokazuje na bieżąco następujące zdarzenia.