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

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

المتطلبات

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

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

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

منذ الإصدار Manifest V3، لم يعُد مسموحًا لإضافات Chrome بتنفيذ رمز برمجي مستضاف عن بُعد. وهذا يعني أنّه عليك استخدام Measurement Protocol من "إحصاءات Google" لتتبُّع أحداث الإضافة. تتيح لك منصة Measurement Protocol إرسال الأحداث مباشرةً إلى خوادم "إحصاءات Google" من خلال طلبات HTTP. من مزايا هذا النهج أنّه يتيح لك إرسال أحداث إحصاءات من أي مكان في إضافتك، بما في ذلك مشغّل الخدمات.

إعداد بيانات اعتماد واجهة برمجة التطبيقات

لإرسال الأحداث إلى "إحصاءات Google"، تحتاج إلى api_secret وmeasurement_id. اتّبِع مستندات Measurement Protocol للتعرّف على مزيد من المعلومات حول المواصفات العامة لمنصّة Measurement Protocol.

الخطوة 1: إنشاء مصدر بيانات موقع إلكتروني

بما أنّه يتم تتبُّع إضافات Chrome على أنّها بيئات ويب، عليك إعداد مصدر بيانات موقع إلكتروني في موقعك على "إحصاءات Google" باتّباع الخطوات التالية:

  1. انتقِل إلى صفحة "المشرف" في "إحصاءات Google".
  2. في عمود الموقع، انقر على جمع البيانات وتعديلها، ثم اختَر مصادر البيانات.
  3. انقر على إضافة مصدر بيانات، ثمّ على الموقع الإلكتروني.
  4. أدخِل أي عنوان URL للنائب في حقل عنوان URL للموقع الإلكتروني (على سبيل المثال، https://extension أو عنوان URL الخاص بإضافتك على "سوق Chrome الإلكتروني").
  5. أدخِل اسم مصدر البيانات (على سبيل المثال، My Chrome Extension).
  6. انقر على إنشاء مصدر بيانات.

بعد إنشاء رقم تعريف القياس (الذي يبدو على النحو التالي: G-XXXXXXXXXX)، سيظهر في أعلى صفحة "تفاصيل مصدر البيانات".

الخطوة 2: إنشاء واجهة برمجة تطبيقات سرّية لمنصّة Measurement Protocol

لإنشاء api_secret المطلوبة لبروتوكول القياس، انتقِل إلى إعدادات مصدر بيانات الموقع الإلكتروني الذي أنشأته للتو:

  1. انتقِل إلى المشرف > جمع البيانات وتعديلها > مصادر البيانات واختَر مصدر بيانات الموقع الإلكتروني.

  2. في قسم الأحداث، انقر على واجهات برمجة التطبيقات السرّية في Measurement Protocol.

  3. إذا طُلب منك ذلك، اقرأ بنود Measurement Protocol ووافِق عليها.

  4. انقر على إنشاء.

  5. أدخِل لقبًا للسر (على سبيل المثال، Chrome Extension Secret) وانقر على إنشاء لإنشاء السر.

  6. انسخ قيمة المفتاح السرّي التي تم إنشاؤها.

إنشاء client_id

تتمثّل الخطوة الثانية في إنشاء معرّف فريد لجهاز أو مستخدم معيّن، وهو client_id. يجب أن يظل المعرّف كما هو طالما أنّ الإضافة مثبّتة على متصفّح أحد المستخدمين. يمكن أن تكون سلسلة عشوائية، ولكن يجب أن تكون فريدة للعميل. خزِّن client_id في browser.storage.local للتأكّد من بقائه كما هو طالما أنّ الإضافة مثبّتة.

يتطلّب استخدام browser.storage.local الإذن storage في ملف البيان:

manifest.json:

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

بعد ذلك، يمكنك استخدام browser.storage.local لتخزين client_id:

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 browser.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 browser.storage.local.set({clientId});
  }
  return clientId;
}

إرسال حدث إحصائي

باستخدام بيانات اعتماد واجهة برمجة التطبيقات وclient_id، يمكنك إرسال حدث إلى &quot;إحصاءات Google&quot; باستخدام طلب 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 دقيقة من عدم تسجيل أي أحداث (يمكن تخصيص هذا الوقت ليناسب سلوك المستخدمين في إضافتك بشكل أفضل). يستخدم المثال browser.storage.session لتخزين الجلسة النشطة أثناء تشغيل المتصفّح. بالإضافة إلى الجلسة، نخزِّن آخر وقت تم فيه تشغيل حدث. يمكننا معرفة ما إذا كانت صلاحية الجلسة النشطة قد انتهت باتّباع الخطوات التالية:

const SESSION_EXPIRATION_IN_MIN = 30;

async function getOrCreateSessionId() {
  // Store session in memory storage
  let {sessionData} = await browser.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 browser.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await browser.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 getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

سيتم عرض الحدث على النحو التالي في تقرير "الوقت الفعلي" على "إحصاءات Google".

الأحداث في الوقت الفعلي في &quot;إحصاءات Google&quot;

تتبُّع مشاهدات الصفحة في النوافذ المنبثقة واللوحة الجانبية وصفحات الإضافات

يتوافق 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>

سيتم عرض طريقة العرض المنبثقة مثل أي مشاهدة صفحة على الويب أخرى في تقرير &quot;الوقت الفعلي&quot; في &quot;إحصاءات Google&quot;، وذلك على النحو التالي:

حدث مشاهدة صفحة على الويب كما يظهر في لوحة بيانات &quot;الوقت الفعلي&quot; في &quot;إحصاءات Google&quot;

تتبُّع أحداث الإحصاءات في برامج الخدمة

يتيح استخدام Google Analytics Measurement Protocol تتبُّع أحداث الإحصاءات في عاملي الخدمة للإضافات. على سبيل المثال، من خلال الاستماع إلى unhandledrejection event في عامل الخدمة، يمكنك تسجيل أي استثناءات غير معالَجة في عامل الخدمة في &quot;إحصاءات Google&quot;، ما يمكن أن يساعد بشكل كبير في تصحيح الأخطاء التي قد يبلغ عنها المستخدمون.

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

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

حدث الخطأ كما يظهر في لوحة بيانات الأحداث في &quot;إحصاءات Google&quot;

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

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

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