Gunakan Google Analytics

Tutorial ini menunjukkan cara melacak penggunaan ekstensi Anda menggunakan Google Analytics. Anda dapat menemukan contoh Google Analytics yang berfungsi di GitHub, tempat google-analytics.js menyertakan semua kode terkait Google Analytics.

Persyaratan

Tutorial ini mengasumsikan bahwa Anda sudah memahami cara menulis ekstensi Chrome. Jika Anda membutuhkan informasi tentang cara menulis ekstensi, baca tutorial Memulai.

Anda juga harus menyiapkan akun Google Analytics untuk melacak ekstensi Anda. Perhatikan bahwa saat menyiapkan akun, Anda dapat menggunakan nilai apa pun di kolom URL Situs, karena ekstensi Anda tidak akan memiliki URL sendiri.

Menggunakan Measurement Protocol Google Analytics

Sejak Manifes V3, Ekstensi Chrome tidak diizinkan untuk mengeksekusi kode yang dihosting dari jarak jauh. Artinya, Anda harus menggunakan Measurement Protocol Google Analytics untuk melacak peristiwa ekstensi. Measurement Protocol memungkinkan Anda mengirim peristiwa langsung ke server Google Analytics dengan permintaan HTTP. Manfaat dari pendekatan ini adalah Anda dapat mengirim peristiwa analisis dari mana saja di ekstensi, termasuk service worker.

Menyiapkan kredensial API

Untuk mengirim peristiwa ke Google Analytics, Anda memerlukan api_secret dan measurement_id. Ikuti dokumentasi Measurement Protocol untuk mempelajari lebih lanjut spesifikasi Measurement Protocol umum.

Langkah 1: Buat aliran data Web

Karena Ekstensi Chrome dilacak sebagai lingkungan web, Anda harus menyiapkan Aliran data web di properti Google Analytics Anda:

  1. Buka halaman Admin Google Analytics.
  2. Di kolom Properti, klik Pengumpulan dan perubahan data, lalu pilih Aliran Data.
  3. Klik Tambahkan aliran data, lalu klik Web.
  4. Masukkan URL placeholder apa pun di kolom URL Situs (misalnya, https://extension atau URL Chrome Web Store ekstensi Anda).
  5. Masukkan Nama aliran data (misalnya, My Chrome Extension).
  6. Klik Buat aliran data.

Setelah dibuat, ID Pengukuran Anda (yang terlihat seperti G-XXXXXXXXXX) akan ditampilkan di bagian atas halaman Detail aliran data.

Langkah 2: Buat rahasia API Measurement Protocol

Untuk membuat api_secret yang diperlukan untuk Measurement Protocol, buka setelan aliran data Web yang baru saja Anda buat:

  1. Buka Admin > Pengumpulan dan modifikasi data > Aliran Data lalu pilih aliran data Web Anda.

  2. Di bagian Peristiwa, klik Rahasia API Measurement Protocol.

  3. Jika diminta, baca dan setujui persyaratan Measurement Protocol.

  4. Klik Buat.

  5. Masukkan nama panggilan untuk secret Anda (misalnya, Chrome Extension Secret) lalu klik Buat untuk membuat secret.

  6. Salin Nilai rahasia yang dibuat.

Buat client_id

Langkah kedua adalah membuat ID unik untuk perangkat/pengguna tertentu, yaitu client_id. ID harus tetap sama, selama ekstensi diinstal di browser pengguna. Dapat berupa string arbitrer, tetapi harus unik untuk klien. Simpan client_id di browser.storage.local untuk memastikan nilainya tetap sama selama ekstensi diinstal.

Penggunaan browser.storage.local memerlukan izin storage dalam file manifes Anda:

manifest.json:

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

Kemudian, Anda dapat menggunakan browser.storage.local untuk menyimpan 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 browser.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 browser.storage.local.set({clientId});
  }
  return clientId;
}

Mengirim peristiwa analisis

Dengan kredensial API dan client_id, Anda dapat mengirim peristiwa ke Google Analytics menggunakan permintaan 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',
          },
        },
      ],
    }),
  }
);

Tindakan ini akan mengirim peristiwa button_clicked yang akan muncul di laporan peristiwa Google Analytics. Jika ingin melihat peristiwa di Laporan Real-Time Google Analytics, Anda harus memberikan dua parameter tambahan: session_id dan engagement_time_msec.

Gunakan parameter yang direkomendasikan session_id dan engagement_time_msec

session_id dan engagement_time_msec adalah parameter yang direkomendasikan saat menggunakan Measurement Protocol Google Analytics karena diperlukan agar aktivitas pengguna ditampilkan dalam laporan standar seperti Real-Time.

session_id menjelaskan periode waktu saat pengguna terus-menerus berinteraksi dengan ekstensi Anda. Secara default, sesi berakhir setelah pengguna tidak aktif selama 30 menit. Tidak ada batas durasi sesi.

Di ekstensi Chrome, tidak seperti di situs normal, tidak ada konsep yang jelas tentang sesi pengguna. Oleh karena itu, Anda harus menentukan arti sesi pengguna di ekstensi Anda. Misalnya, setiap interaksi pengguna baru dapat menjadi sesi baru. Dalam hal ini, Anda dapat membuat ID sesi baru dengan setiap peristiwa, seperti menggunakan stempel waktu.

Contoh berikut menunjukkan pendekatan yang akan menghentikan sesi baru setelah 30 menit tidak ada peristiwa yang dilaporkan (waktu ini dapat disesuaikan agar lebih sesuai dengan perilaku pengguna ekstensi Anda). Contoh ini menggunakan browser.storage.session untuk menyimpan sesi aktif saat browser sedang berjalan. Bersama dengan sesi, kita menyimpan waktu terakhir kali peristiwa diaktifkan. Dengan cara ini, kita dapat mengetahui apakah sesi aktif telah berakhir:

const SESSION_EXPIRATION_IN_MIN = 30;

async function getOrCreateSessionId() {
  // Store session in memory storage
  let {sessionData} = await browser.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 browser.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await browser.storage.session.set({sessionData});
  }
  return sessionData.session_id;
}

Contoh berikut menambahkan session_id dan engagement_time_msec ke permintaan peristiwa klik tombol sebelumnya. Untuk engagement_time_msec, sebaiknya berikan waktu yang telah berlalu sejak peristiwa terakhir. Namun, jika hal ini tidak mungkin dilakukan, Anda dapat memberikan nilai default 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",
          },
        },
      ],
    }),
  }
);

Peristiwa akan ditampilkan sebagai berikut dalam laporan Real-Time Google Analytics.

Peristiwa real-time di Google Analytics.

Melacak tayangan halaman di halaman pop-up, panel samping, dan ekstensi

Measurement Protocol Google Analytics mendukung peristiwa page_view khusus untuk melacak tayangan halaman. Gunakan ini untuk melacak pengguna yang membuka kotak dialog, halaman menu, panel samping, dan halaman ekstensi di tab baru. Peristiwa page_view juga memerlukan parameter page_title dan page_location. Contoh berikut mengaktifkan peristiwa tayangan halaman pada peristiwa load dokumen untuk menu ekstensi:

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
          },
        },
      ],
    }),
  });
});

Skrip popup.js harus diimpor dalam file html pop-up Anda dan harus dijalankan sebelum skrip lain dieksekusi:

<!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>

Tampilan pop-up akan ditampilkan seperti tayangan halaman lainnya di laporan Realtime Google Analytics:

Peristiwa tayangan halaman seperti yang ditampilkan di dasbor Real-Time Google Analytics.

Melacak peristiwa Analytics di pekerja layanan

Dengan Measurement Protocol Google Analytics, Anda dapat melacak peristiwa analisis di pekerja layanan ekstensi. Misalnya, dengan memantau unhandledrejection event di service worker, Anda dapat mencatat pengecualian yang tidak tertangkap di service worker ke Google Analytics, yang dapat sangat membantu men-debug masalah yang mungkin dilaporkan pengguna.

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,
          },
        },
      ],
    }),
  });
});

Sekarang Anda dapat melihat peristiwa error di laporan Google Analytics:

Peristiwa error seperti yang ditampilkan di dasbor peristiwa Google Analytics.

Proses debug

Google Analytics menyediakan dua fitur berguna untuk men-debug peristiwa Analytics ke dalam ekstensi Anda:

  1. Endpoint debug khusus https://www.google-analytics.com**/debug**/mp/collect yang akan melaporkan error dalam definisi peristiwa Anda.
  2. Laporan Real-Time Google Analytics yang akan menampilkan peristiwa saat peristiwa tersebut masuk.