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

يوضّح هذا البرنامج التعليمي كيفية تتبُّع استخدام الإضافة باستخدام "إحصاءات Google". يمكنك العثور على نموذج عملي لخدمة "إحصاءات Google‏ 4" على Github، حيث يتضمّن 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. يجب أن يظلّ المعرّف كما هو طالما أنّ الإضافة مثبّتة على متصفّح المستخدم. يمكن أن تكون سلسلة عشوائية، ولكن يجب أن تكون فريدة للعميل. خزِّن client_id في chrome.storage.local للتأكّد من بقائه كما هو طالما أنّ الإضافة مثبّتة.

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

manifest.json:

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

بعد ذلك، يمكنك استخدام chrome.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 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;
}

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

باستخدام بيانات اعتماد واجهة برمجة التطبيقات و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".

الأحداث في الوقت الفعلي في &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>

سيتم عرض طريقة العرض المنبثقة مثل أيّ طريقة عرض أخرى للصفحة في تقرير "الوقت الفعلي" في "إحصاءات Google":

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

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

يتيح استخدام 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":

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

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

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

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