Google Analytics'i kullan

Bu eğitimde, Google Analytics'i kullanarak uzantınızın kullanımını nasıl izleyeceğiniz gösterilmektedir. GitHub'da çalışan bir Google Analytics örneğini bulabilirsiniz. google-analytics.js, Google Analytics ile ilgili tüm kodu içerir.

Şartlar

Bu eğitimde, Chrome uzantıları yazma konusunda bilgi sahibi olduğunuz varsayılmaktadır. Uzantı yazma hakkında bilgiye ihtiyacınız varsa Başlangıç eğitimini okuyun.

Uzantınızı izlemek için Google Analytics hesabı da oluşturmanız gerekir. Hesabı oluştururken, uzantınızın kendi URL'si olmayacağından Web sitesinin URL'si alanında herhangi bir değeri kullanabileceğinizi unutmayın.

Google Analytics Measurement Protocol'u kullanma

Manifest V3'ten itibaren Chrome uzantılarının uzaktan barındırılan kodu yürütmesine izin verilmez. Bu nedenle, uzantı etkinliklerini izlemek için Google Analytics Measurement Protocol'ü kullanmanız gerekir. Measurement Protocol, HTTP istekleriyle etkinlikleri doğrudan Google Analytics sunucularına göndermenize olanak tanır. Bu yaklaşımın avantajlarından biri, hizmet çalışanınız da dahil olmak üzere uzantınızın her yerinden analiz etkinlikleri göndermenize olanak tanımasıdır.

API kimlik bilgilerini ayarlama

Etkinlikleri Google Analytics'e göndermek için api_secret ve measurement_id gerekir. Genel Measurement Protocol spesifikasyonları hakkında daha fazla bilgi edinmek için Measurement Protocol belgelerini inceleyin.

1. adım: Web veri akışı oluşturun

Chrome uzantıları web ortamı olarak izlendiğinden Google Analytics mülkünüzde web veri akışı oluşturmanız gerekir:

  1. Google Analytics Yönetici sayfasına gidin.
  2. Mülk sütununda Veri toplama ve değiştirme'yi tıklayın, ardından Veri Akışları'nı seçin.
  3. Akış ekle'yi ve ardından Web'i tıklayın.
  4. Web sitesi URL'si alanına herhangi bir yer tutucu URL girin (örneğin, https://extension veya uzantınızın Chrome Web Mağazası URL'si).
  5. Akış adı girin (ör. My Chrome Extension).
  6. Akış oluştur'u tıklayın.

Oluşturulduktan sonra ölçüm kimliğiniz (G-XXXXXXXXXX gibi görünür) Akış ayrıntıları sayfasının üst kısmında gösterilir.

2. adım: Measurement Protocol API gizli anahtarı oluşturma

Measurement Protocol için gereken api_secret oluşturmak üzere, yeni oluşturduğunuz web veri akışının ayarlarına gidin:

  1. Yönetici > Veri toplama ve değiştirme > Veri Akışları'na gidin ve web veri akışınızı seçin.

  2. Etkinlikler bölümünde Measurement Protocol API gizli anahtarları'nı tıklayın.

  3. İstenirse Measurement Protocol şartlarını okuyup kabul edin.

  4. Oluştur'u tıklayın.

  5. Gizli anahtarınız için bir takma ad girin (örneğin, Chrome Extension Secret) ve gizli anahtarı oluşturmak için Oluştur'u tıklayın.

  6. Oluşturulan Gizli anahtar değerini kopyalayın.

client_id oluşturma

İkinci adım, belirli bir cihaz/kullanıcı için benzersiz bir tanımlayıcı olan client_id oluşturmaktır. Uzantı, kullanıcının tarayıcısına yüklendiği sürece kimlik aynı kalır. Bu, rastgele bir dize olabilir ancak istemciye özel olmalıdır. Uzantı yüklü olduğu sürece aynı kalmasını sağlamak için client_id değerini chrome.storage.local içinde saklayın.

chrome.storage.local özelliğini kullanmak için manifest dosyanızda storage izni gerekir:

manifest.json:

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

Ardından client_id öğesini depolamak için chrome.storage.local kullanabilirsiniz:

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;
}

Analiz etkinliği gönderme

API kimlik bilgileri ve client_id ile fetch isteği kullanarak Google Analytics'e etkinlik gönderebilirsiniz:

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

Bu işlem, Google Analytics etkinlik raporunuzda gösterilecek bir button_clicked etkinliği gönderir. Etkinliklerinizi Google Analytics Anlık Raporu'nda görmek istiyorsanız iki ek parametre sağlamanız gerekir: session_id ve engagement_time_msec.

Önerilen parametreleri session_id ve engagement_time_msec kullanın.

session_id ve engagement_time_msec, Google Analytics Measurement Protocol kullanılırken önerilen parametrelerdir. Kullanıcı etkinliğinin Gerçek Zamanlı gibi standart raporlarda gösterilmesi için bu parametreler gereklidir.

session_id, kullanıcının uzantınızla sürekli etkileşimde bulunduğu süreyi ifade eder. Varsayılan olarak, kullanıcı 30 dakika boyunca hiçbir işlem yapmazsa oturum sona erer. Oturumlar için maksimum süre sınırı yoktur.

Normal web sitelerinin aksine, Chrome uzantılarında kullanıcı oturumu kavramı net değildir. Bu nedenle, uzantınızda kullanıcı oturumunun ne anlama geldiğini tanımlamanız gerekir. Örneğin, her yeni kullanıcı etkileşimi yeni bir oturum olabilir. Bu durumda, her etkinlik için yeni bir oturum kimliği oluşturabilirsiniz (ör. zaman damgası kullanarak).

Aşağıdaki örnekte, 30 dakika boyunca etkinlik raporlanmaması durumunda yeni oturumun zaman aşımına uğramasına neden olacak bir yaklaşım gösterilmektedir (bu süre, uzantınızın kullanıcı davranışına daha iyi uyacak şekilde özelleştirilebilir). Örnekte, tarayıcı çalışırken etkin oturumu depolamak için chrome.storage.session kullanılır. Oturumla birlikte bir etkinliğin son tetiklenme zamanını da saklarız. Etkin oturumun süresinin dolup dolmadığını şu şekilde anlayabiliriz:

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;
}

Aşağıdaki örnekte, önceki düğme tıklama etkinliği isteğine session_id ve engagement_time_msec eklenir. engagement_time_msec için son etkinlikten bu yana geçen süreyi sağlamak en iyisidir. Ancak bu mümkün değilse 100 ms varsayılan değerini sağlayabilirsiniz.

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

Etkinlik, Google Analytics Gerçek Zamanlı raporunda aşağıdaki gibi gösterilir.

Google Analytics&#39;teki anlık etkinlikler.

Pop-up, yan panel ve uzantı sayfalarındaki sayfa görüntülemelerini izleme

Google Analytics Measurement Protocol, sayfa görüntülemelerini izlemek için özel bir page_view etkinliğini destekler. Bunu, iletişim kutularınızı, menü sayfalarınızı, yan panellerinizi ve uzantı sayfalarınızı yeni bir sekmede ziyaret eden kullanıcıları izlemek için kullanın. page_view etkinliği için page_title ve page_location parametreleri de gerekir. Aşağıdaki örnek, bir uzantı menüsü için belge load etkinliğinde bir sayfa görüntüleme etkinliği tetikler:

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

popup.js komut dosyası, pop-up'ınızın HTML dosyasına aktarılmalı ve diğer komut dosyaları yürütülmeden önce çalıştırılmalıdır:

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

Pop-up görünümü, Google Analytics anlık raporunda diğer tüm sayfa görünümleri gibi gösterilir:

Google Analytics Gerçek Zamanlı kontrol panelinde gösterilen sayfa görüntüleme etkinliği.

Service worker'larda analiz etkinliklerini izleme

Google Analytics Measurement Protocol'ü kullanarak uzantı hizmeti çalışanlarındaki analiz etkinliklerini izleyebilirsiniz. Örneğin, hizmet çalışanı kodunuzdaki unhandledrejection event dinleyerek hizmet çalışanı kodunuzdaki yakalanmamış istisnaları Google Analytics'e kaydedebilirsiniz. Bu, kullanıcılarınızın bildirebileceği sorunları ayıklamanıza büyük ölçüde yardımcı olabilir.

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

Artık hata etkinliğini Google Analytics raporlarınızda görebilirsiniz:

Google Analytics etkinlikler kontrol panelinde gösterildiği şekliyle hata etkinliği.

Hata ayıklama

Google Analytics, Analytics etkinliklerinde uzantınızda hata ayıklamak için iki yararlı özellik sunar:

  1. Etkinlik tanımlarınızdaki hataları bildiren bir özel hata ayıklama uç noktası https://www.google-analytics.com**/debug**/mp/collect.
  2. Etkinlikleri geldikçe gösterecek olan Google Analytics Gerçek Zamanlı Raporu.