يشرح هذا الدليل التوجيهي كيفية تتبُّع استخدام إضافتك باستخدام "إحصاءات Google". يمكنك العثور على نموذج صالح من "إحصاءات Google 4" على جيت هب، حيث يتضمّن google-analytics.js كل الرموز البرمجية ذات الصلة بخدمة "إحصاءات Google".
المتطلّبات
يفترض هذا البرنامج التعليمي أنك على دراية بكتابة إضافات Chrome. إذا كنت بحاجة إلى معلومات حول كيفية كتابة إضافة، يُرجى قراءة البرنامج التعليمي للبدء.
عليك أيضًا إعداد حساب على "إحصاءات Google 4" لتتبُّع إضافتك. تجدر الإشارة إلى أنّه عند إعداد الحساب، يمكنك استخدام أي قيمة في حقل "عنوان URL للموقع الإلكتروني"، لأنّ إضافتك لن يكون لها عنوان URL خاص بها.
استخدام Measurement Protocol في "إحصاءات Google"
منذ إصدار Manifest V3، لا يُسمح لإضافات Chrome بتنفيذ رمز مُستضاف عن بُعد. وهذا يعني أنه عليك استخدام Google Analytics Measurement Protocol لتتبُّع أحداث إضافات البيانات. يتيح لك Measurement Protocol إرسال الأحداث مباشرةً إلى خوادم "إحصاءات Google" عبر طلبات HTTP. تتمثل إحدى فوائد هذا الأسلوب في أنّه يتيح لك إرسال أحداث إحصاءات من كل مكان في الإضافة، بما في ذلك مشغّل الخدمات.
إعداد بيانات اعتماد واجهة برمجة التطبيقات
الخطوة الأولى هي الحصول على api_secret وmeasurement_id. اتّبع مستندات Measurement Protocol للتعرّف على كيفية الحصول عليها لحسابك على "إحصاءات Google".
إنشاء client_id
تتمثّل الخطوة الثانية في إنشاء معرّف فريد لجهاز/مستخدم محدّدَين، وهو client_id. يجب أن يظل المعرّف كما هو، ما دامت الإضافة مثبّتة في متصفّح المستخدم. ويمكن أن يكون سلسلة عشوائية، ولكن يجب أن يكون فريدًا للعميل. يمكنك إنشاء رقم من خلال الاتصال على self.crypto.randomUUID(). يمكنك تخزين client_id في chrome.storage.local لضمان بقاء الإضافة كما هي ما دامت الإضافة مثبّتة.
ويتطلّب استخدام chrome.storage.local الحصول على إذن storage في ملف البيان:
manifest.json:
{
…
"permissions": ["storage"],
…
}
بعد ذلك، يمكنك استخدام "chrome.storage.local" لتخزين "client_id":
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;
}
إرسال حدث إحصاءات
باستخدام بيانات اعتماد واجهة برمجة التطبيقات وclient_id، يمكنك إرسال حدث إلى "إحصاءات Google" من خلال طلب 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',
},
},
],
}),
}
);
يؤدي ذلك إلى إرسال حدث button_clicked الذي سيظهر في تقرير أحداث "إحصاءات Google". إذا كنت تريد الاطّلاع على أحداثك في تقرير الوقت الفعلي من "إحصاءات Google"، عليك تقديم مَعلمتَين إضافيتَين: session_id وengagement_time_msec.
استخدام المعلمتَين المقترحتَين session_id وengagement_time_msec
يُعد كل من session_id وengagement_time_msec مَعلمتين مُقترحتين عند استخدام Measurement Protocol في "إحصاءات Google" لأنهما مطلوبتان لعرض نشاط المستخدم في التقارير العادية مثل "الوقت الفعلي".
تصف السمة session_id فترة زمنية يتفاعل خلالها المستخدِم باستمرار مع الإضافة. تنتهي الجلسة تلقائيًا بعد مرور 30 دقيقة على توقّف نشاط المستخدِم. وليس هناك حدّ لطول مدة الجلسة.
في إضافات Chrome، ما مِن مفهوم واضح لجلسة المستخدم على عكس المواقع الإلكترونية العادية. وبالتالي، يجب تحديد ما تعنيه جلسة المستخدم في إضافتك. على سبيل المثال، قد يكون كل تفاعل جديد للمستخدم جلسة جديدة. في هذه الحالة، يمكنك ببساطة إنشاء معرّف جلسة جديد مع كل حدث (أي باستخدام طابع زمني).
يوضح المثال التالي النهج الذي سيؤدي إلى انتهاء مهلة جلسة جديدة بعد 30 دقيقة من عدم الإبلاغ عن الأحداث (يمكن تخصيص هذه المرة لتناسب سلوك مستخدم الإضافة بشكل أفضل). يستخدم المثال chrome.storage.session لتخزين الجلسة النشطة أثناء تشغيل المتصفِّح. مع الجلسة، نخزِّن آخر مرة تم فيها تنشيط الحدث. بهذه الطريقة، يمكننا معرفة ما إذا كانت صلاحية الجلسة النشطة قد انتهت صلاحيتها:
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;
}
يضيف المثال التالي session_id وengagement_time_msec إلى طلب الحدث السابق نتيجة النقر على الزر. بالنسبة إلى engagement_time_msec، يمكنك توفير قيمة تلقائية تبلغ 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 this.getOrCreateSessionId(),
engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
id: "my-button",
},
},
],
}),
}
);
سيتم عرض الحدث على النحو التالي في تقرير "الوقت الفعلي" على "إحصاءات Google".
تتبُّع مشاهدات الصفحات في النافذة المنبثقة واللوحة الجانبية وصفحات الإضافات
يتيح Measurement Protocol في "إحصاءات Google" حدث page_view خاص لتتبُّع مشاهدات الصفحات. استخدِم هذا الخيار لتتبُّع المستخدمين الذين يزورون صفحات النوافذ المنبثقة أو اللوحة الجانبية أو صفحة الإضافات في علامة تبويب جديدة. يتطلّب الحدث page_view أيضًا المَعلمتَين page_title وpage_location. يؤدي المثال التالي إلى تنشيط حدث مشاهدة صفحة على الويب عند حدث load للمستند في نافذة منبثقة لإضافة:
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" إلى ملف html الخاص بالنافذة المنبثقة، ويجب تشغيله قبل تنفيذ أي نص برمجي آخر:
<!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>
ستظهر طريقة العرض المنبثقة مثل أي مشاهدة أخرى للصفحة في تقرير الوقت الفعلي لخدمة "إحصاءات Google":
تتبع أحداث التحليلات في عاملي الخدمة
يتيح استخدام Measurement Protocol في "إحصاءات Google" تتبُّع أحداث الإحصاءات لدى العاملين في خدمات الإضافات. على سبيل المثال، من خلال الاستماع إلى unhandledrejection event في مشغّل الخدمات، يمكنك تسجيل أي استثناءات غير مرصودة في مشغّل الخدمات في "إحصاءات Google"، ما يمكن أن يساعد كثيرًا في تصحيح الأخطاء التي قد يُبلغ عنها المستخدمون.
service-factor.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,
},
},
],
}),
}
});
يمكنك الآن الاطّلاع على حدث الخطأ في تقارير "إحصاءات Google":
تصحيح الأخطاء
توفّر "إحصاءات Google" ميزتَين مفيدتَين لتصحيح أخطاء أحداث الإحصاءات في إضافتك:
- نقطة نهاية خاصة لتصحيح الأخطاء
https://www.google-analytics.com**/debug**/mp/collectستُبلغ عن أي أخطاء في تعريفات الأحداث. - تقرير الوقت الفعلي لخدمة "إحصاءات Google" الذي سيعرض الأحداث فور ورودها.