Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

استخدام "إحصاءات 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" باتّباع الخطوات التالية:

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

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

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

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

انتقِل إلى المشرف > جمع البيانات وتعديلها > مصادر البيانات واختَر مصدر بيانات الموقع الإلكتروني.
في قسم الأحداث، انقر على واجهات برمجة التطبيقات السرّية في Measurement Protocol.

ملاحظة: إذا لم يظهر لك هذا الخيار، تأكَّد من أنّ حساب المستخدم على "إحصاءات Google" لديه أذونات **محرِّر** أو **مشرف** لموقع "إحصاءات Google‏ 4". لا تكفي أدوار المشاهد أو المحلّل العادية.
إذا طُلب منك ذلك، اقرأ بنود Measurement Protocol ووافِق عليها.
انقر على إنشاء.
أدخِل لقبًا للسر (على سبيل المثال، Chrome Extension Secret) وانقر على إنشاء لإنشاء السر.
انسخ القيمة السرية التي تم إنشاؤها.

إنشاء `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 = `${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 getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

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

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

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

يتيح "بروتوكول القياس" في "إحصاءات 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"، وذلك على النحو التالي:

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

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

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

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":

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

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

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

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