Bu eğiticide, Google Analytics'i kullanarak uzantınızın kullanımını nasıl izleyeceğiniz gösterilmektedir. Github'da çalışan bir Google Analytics 4 örneği bulabilirsiniz. Bu örnekte 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ılır. Uzantı yazma hakkında bilgiye ihtiyacınız varsa lütfen Başlangıç Eğitimi'ni okuyun.
Ayrıca uzantınızı izlemek için bir Google Analytics 4 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, etkinlikleri HTTP istekleri aracılığıyla 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
İlk adım, api_secret ve measurement_id edinmektir. Analytics hesabınız için bunları nasıl alacağınızla ilgili bilgileri Measurement Protocol dokümanında bulabilirsiniz.
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üklü olduğu sürece kimlik aynı kalır. Rastgele bir dize olabilir ancak istemciye özgü 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 kullanmak için manifest dosyanızda storage izni gerekir:
manifest.json:
{
…
"permissions": ["storage"],
…
}
Ardından client_id öğesini saklamak 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 = `${this.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 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 etkinlik raporunuzda görünecek bir button_clicked etkinliği gönderir. Etkinliklerinizi Google Analytics anlık raporunda 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ırken önerilen parametrelerdir. Bunun nedeni, kullanıcı etkinliğinin Anlık gibi standart raporlarda gösterilmesi için bu parametrelerin gerekli olmasıdır.
session_id, kullanıcının uzantınızla sürekli etkileşim kurduğu süreyi ifade eder. 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ı 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 etkinlikte yeni bir oturum kimliği oluşturmanız yeterlidir (ö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 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österilir.
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, pop-up sayfalarınızı, yan panelinizi veya yeni sekmedeki bir uzantı sayfasını 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ı pop-up'ı 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ının pop-up'ınızın HTML dosyasına aktarılması ve diğer komut dosyaları yürütülmeden önce çalıştırılması 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 Anlık raporunda diğer tüm sayfa görünümleri gibi gösterilir:
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ı kodunuzda yakalanmayan tüm 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) => {
`${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,
},
},
],
}),
}
});
Artık Google Analytics raporlarınızda hata etkinliğini görebilirsiniz:
Hata ayıklama
Google Analytics, Analytics etkinliklerinde uzantınızda hata ayıklamak için iki faydalı özellik sunar:
- Etkinlik tanımlarınızdaki hataları bildiren bir özel hata ayıklama uç noktası
https://www.google-analytics.com**/debug**/mp/collect. - Etkinlikleri geldikleri sırada gösterecek olan Google Analytics Gerçek Zamanlı Raporu.