Bu eğitim, uzantınızın kullanımını Google Analytics kullanarak nasıl izleyeceğinizi gösterir. GitHub'da çalışan bir Google Analytics 4 örneği bulabilirsiniz. Burada google-analytics.js, Google Analytics ile ilgili tüm kodları içerir.
Koşullar
Bu eğitim, Chrome uzantılarını yazma konusunda bilgi sahibi olduğunuz varsayılmaktadır. Uzantı yazma konusunda bilgiye ihtiyacınız varsa lütfen Başlangıç eğitimini okuyun.
Uzantınızı izlemek için bir Google Analytics 4 hesabı da oluşturmanız gerekir. Hesabınızı oluştururken, uzantınızın kendi URL'si olmayacağından Web sitesinin URL alanındaki herhangi bir değeri kullanabilirsiniz.
Google Analytics Measurement Protocol'u kullanma
Manifest V3 sürümünden itibaren Chrome Uzantılarının uzaktan barındırılan kodu yürütmesine izin verilmemektedir. Bu nedenle, uzantı etkinliklerini izlemek için Google Analytics Measurement Protocol'u kullanmanız gerekir. Measurement Protocol, HTTP istekleri aracılığıyla etkinlikleri doğrudan Google Analytics sunucularına göndermenize olanak tanır. Bu yaklaşımın avantajlarından biri, hizmet çalışanınız dahil olmak üzere uzantınızın her yerinden analiz etkinlikleri göndermenize olanak tanımasıdır.
API kimlik bilgilerini ayarlama
İlk adım bir api_secret ve measurement_id edinmektir. Analytics Hesabınız için bu verileri nasıl alacağınızı öğrenmek için Measurement Protocol belgelerine göz atın.
client_id oluştur
İkinci adım, belirli bir cihaz/kullanıcı için benzersiz bir tanımlayıcı (client_id) oluşturmaktır. Uzantı bir kullanıcının tarayıcısında yüklü olduğu sürece kimlik aynı kalmalıdır. Rastgele bir dize olabilir ancak müşteriye özel olmalıdır. self.crypto.randomUUID() yöntemini çağırarak bir etiket oluşturabilirsiniz. Uzantı yüklü olduğu sürece aynı kalmasını sağlamak için client_id öğesini chrome.storage.local içinde depolayın.
chrome.storage.local işlevinin kullanılabilmesi için manifest dosyanızda storage izninin bulunması gerekir:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Ardından client_id öğelerini depolamak için chrome.storage.local kullanabilirsiniz:
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;
}
Analiz etkinliği gönderme
API kimlik bilgileri ve client_id sayesinde, fetch isteği aracılığıyla 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 etkinlikler raporunuzda görünecek bir button_clicked etkinliği gönderir. Etkinliklerinizi Google Analytics Gerçek Zamanlı Raporu'nda görmek isterseniz iki ek parametre sağlamanız gerekir: session_id ve engagement_time_msec.
Önerilen session_id ve engagement_time_msec parametrelerini kullan
Hem session_id hem de engagement_time_msec, kullanıcı etkinliğinin gerçek zamanlı gibi standart raporlarda görüntülenmesi için gerekli olduğundan Google Analytics Measurement Protocol kullanılırken önerilen parametrelerdir.
session_id, bir kullanıcının uzantınızla sürekli olarak etkileşimde bulunduğu süreyi belirtir. Varsayılan olarak, kullanıcı 30 dakika boyunca hiçbir işlem yapmazsa oturum sonlandırılır. Oturumlar için maksimum süre sınırı yoktur.
Normal web sitelerinin aksine Chrome uzantılarında kullanıcı oturumuna dair net bir kavram yoktur. 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, hiçbir etkinlik bildirilmediğinde 30 dakika sonra yeni bir oturumu zaman aşımına uğratan 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ılmaktadır. Oturumla birlikte, bir etkinliğin en son ne zaman tetiklendiğini kaydediyoruz. Bu şekilde etkin oturumun süresinin dolup dolmadığını 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 eklenmiştir. engagement_time_msec için 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 this.getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
id: "my-button",
},
},
],
}),
}
);
Etkinlik, Google Analytics gerçek zamanlı raporunda aşağıdaki gibi görüntülenir.
Pop-up, yan panel ve uzantı sayfalarında sayfa görüntüleme sayısını izleme
Google Analytics Measurement Protocol, sayfa görüntülemelerini izlemek için özel bir page_view etkinliğini destekler. Pop-up sayfalarınızı, yan panelinizi veya bir uzantı sayfasını yeni bir sekmede ziyaret eden kullanıcıları izlemek için bunu kullanın. page_view etkinliği, page_title ve page_location parametrelerini de gerektirir. Aşağıdaki örnek, bir uzantı pop-up'ı için doküman 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ının pop-up'ınızın html dosyasına aktarılması ve diğer herhangi bir komut dosyası yürütülmeden önce çalışması gerekir:
<!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 Gerçek Zamanlı raporundaki diğer sayfa görüntülemeleri gibi görüntülenir:
Service Worker'larda analiz etkinliklerini izleme
Google Analytics Measurement Protocol, uzantı hizmeti çalışanlarındaki analiz etkinliklerini izlemeyi mümkün kılar. Örneğin, hizmet çalışanınızda unhandledrejection event ifadesini dinleyerek hizmet çalışanınızda yakalanmamış istisnaları Google Analytics'e kaydedebilirsiniz. Bu, kullanıcılarınızın bildirebileceği sorunların giderilmesine büyük ölçüde yardımcı olabilir.
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,
},
},
],
}),
}
});
Hata etkinliğini artık Google Analytics raporlarınızda görebilirsiniz:
Hata ayıklama
Google Analytics, uzantınızda analiz etkinlikleri için hata ayıklamanız için iki faydalı özellik sunar:
- Etkinlik tanımlarınızdaki hataları bildirecek olan özel bir hata ayıklama uç noktası
https://www.google-analytics.com**/debug**/mp/collect. - Etkinlikleri geldikçe gösterecek Google Analytics Gerçek Zamanlı Raporu.