استخدام "إحصاءات Google 4"

يوضح هذا البرنامج التعليمي كيفية تتبع استخدام الإضافة باستخدام Google Analytics. يمكنك العثور على نموذج "إحصاءات Google 4" قيد التشغيل على GitHub، حيث تتضمّن google-analytics.js جميع الرموز البرمجية ذات الصلة بخدمة "إحصاءات Google".

المتطلبات

يفترض هذا البرنامج التعليمي أنك على دراية بكتابة إضافات Chrome. إذا كنت بحاجة إلى معلومات حول كيفية كتابة إضافة، يُرجى قراءة الدليل التعليمي للبدء.

عليك أيضًا إعداد حساب على "إحصاءات Google 4" لتتبُّع الإضافة. تجدر الإشارة إلى أنه عند إعداد الحساب، يمكنك استخدام أي قيمة في حقل عنوان URL لموقع الويب، حيث لن يكون للإضافة عنوان URL خاص بها.

استخدام Measurement Protocol في "إحصاءات Google"

بما أنّ إصدار Manifest V3، لا يُسمح لإضافات Chrome بتنفيذ الرموز البرمجية المستضافة عن بُعد. وهذا يعني أن عليك استخدام Measurement Protocol في "إحصاءات Google" لتتبُّع أحداث الإضافات. يتيح لك 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-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,
          },
        },
      ],
    }),
  }
});

يمكنك الآن الاطّلاع على حدث الخطأ في تقارير "إحصاءات Google":

تصحيح الأخطاء

توفِّر "إحصاءات Google" ميزتَين مفيدتَين لتصحيح أخطاء أحداث الإحصاءات في إضافتك:

1. نقطة نهاية خاصة لتصحيح الأخطاء https://www.google-analytics.com**/debug**/mp/collect ستُبلغ عن أي أخطاء في تعريفات الأحداث.
2. تقرير الوقت الفعلي من "إحصاءات Google" الذي سيعرض الأحداث فور ورودها