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 memerlukan informasi tentang cara menulis ekstensi, baca tutorial Memulai.

Anda juga harus menyiapkan akun Google Analytics untuk melacak ekstensi. 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 menjalankan kode yang dihosting 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 pendekatan ini adalah memungkinkan Anda mengirim peristiwa analisis dari mana saja di ekstensi, termasuk pekerja layanan.

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: Membuat aliran data Web

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

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 (yang terlihat seperti G-XXXXXXXXXX) akan ditampilkan di bagian atas halaman Detail aliran data.

Langkah 2: Membuat rahasia Measurement Protocol API

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

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

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

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

4. Klik Buat.

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

6. Salin Nilai rahasia yang dibuat.

Membuat client_id

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

Menggunakan chrome.storage.local memerlukan izin storage dalam file manifes Anda:

manifest.json:

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

Kemudian, Anda dapat menggunakan chrome.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 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;
}

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 events report. Jika ingin melihat peristiwa di Google Analytics Laporan Real-Time, Anda harus memberikan dua parameter tambahan: session_id dan engagement_time_msec.

Menggunakan 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 Realtime.

session_id menjelaskan periode waktu, selama pengguna terus berinteraksi dengan ekstensi Anda. Secara default, sesi berakhir setelah 30 menit tidak ada aktivitas pengguna. 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 chrome.storage.session untuk menyimpan sesi aktif saat browser sedang berjalan. Bersama dengan sesi, kita menyimpan waktu terakhir peristiwa dipicu. 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 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;
}

Contoh berikut menambahkan session_id dan engagement_time_msec ke permintaan peristiwa klik tombol sebelumnya. Untuk engagement_time_msec, sebaiknya berikan waktu yang berlalu sejak peristiwa terakhir. Namun, jika hal ini tidak memungkinkan, 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 di laporan Real-Time Google Analytics.

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

Measurement Protocol Google Analytics mendukung peristiwa page_view khusus untuk melacak kunjungan halaman. Gunakan peristiwa ini untuk melacak pengguna yang mengunjungi 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 memicu peristiwa kunjungan 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 lainnya 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 kunjungan halaman lainnya di laporan Real-Time Google Analytics:

Melacak peristiwa analisis di pekerja layanan

Dengan Measurement Protocol Google Analytics, Anda dapat melacak peristiwa analisis di pekerja layanan ekstensi. Misalnya, dengan memproses unhandledrejection event di pekerja layanan, Anda dapat mencatat pengecualian yang tidak tertangkap di pekerja layanan ke Google Analytics, yang dapat sangat membantu proses 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:

Proses debug

Google Analytics menyediakan dua fitur bermanfaat untuk melakukan proses debug peristiwa analisis ke ekstensi Anda:

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