وصل Measurement Protocol إلى حالة منتج نهائية ومكتملة، وسيظل قيد التشغيل بدون أي خطط لإيقافه. ومع ذلك، لضمان إعداداتك الفنية المحصّنة ضدّ التغييرات المستقبلية، ننصحك بإنشاء عمليات دمج للأحداث من خادم إلى خادم باستخدام Data Manager API، وهو بنيتنا الأساسية المركزية لابتكارات نقل البيانات المستقبلية.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إرسال أحداث Measurement Protocol إلى "إحصاءات Google"

يوضّح هذا الدليل كيفية إرسال أحداث مصدر بيانات الموقع الإلكتروني ومصدر بيانات التطبيق في Measurement Protocol من "إحصاءات Google" إلى أحد خوادم "إحصاءات Google"، وذلك حتى تتمكّن من عرض أحداث Measurement Protocol في تقارير "إحصاءات Google".

تعتمد المعرّفات والمَعلمات المطلوبة لطلبات Measurement Protocol على ما إذا كنت سترسل الأحداث إلى مصدر بيانات من موقع إلكتروني أو مصدر بيانات تطبيق.

بالنسبة إلى مصادر بيانات المواقع الإلكترونية (التي يتم عادةً قياسها باستخدام gtag.js أو أداة "إدارة العلامات من Google")، يمكنك استخدام measurement_id في عنوان URL للطلب وclient_id في نص JSON لتحديد مثيل المستخدِم. يجب أن يتطابق client_id مع رقم التعريف الذي تم إنشاؤه بواسطة علامة "إحصاءات Google" على موقعك الإلكتروني.
بالنسبة إلى مصادر بيانات التطبيقات (التي تمّت إضافتها باستخدام Firebase SDK)، يمكنك استخدام firebase_app_id في عنوان URL للطلب وapp_instance_id في نص JSON، وهما متوفّران من خلال ‫SDK "إحصاءات Google لـ Firebase".

يقدّم هذا الدليل أمثلة على كلتا الحالتين.

مكوّنات طلب المفتاح حسب نوع البث

المكوّن	مصدر بيانات من موقع إلكتروني (gtag.js/إدارة العلامات من Google)	مصدر بيانات التطبيق (Firebase)
مَعلمة عنوان URL لمصدر البيانات	`measurement_id`	`firebase_app_id`
مَعلمة عنوان URL لواجهة برمجة تطبيقات سرّية	مطلوب	مطلوب
حقل نص JSON الخاص برقم تعريف الجهاز	`client_id`	`app_instance_id`

اختَر المنصة التي تريد الاطّلاع عليها في هذا الدليل:

تعرض علامة التبويب هذه تعليمات لإرسال الأحداث من خادمك التي تتوافق مع نشاط المستخدم في مصدر بيانات تطبيق باستخدام حزمة تطوير البرامج (SDK) لأداة "إحصاءات Google لبرنامج Firebase". يُرجى العِلم أنّ هذه الطلبات تستخدم firebase_app_id وapp_instance_id.

المتطلبات الأساسية

لإرسال الأحداث باستخدام Measurement Protocol، عليك توفير معرّفات معيّنة من موقعك على "إحصاءات Google" أو مشروعك على Firebase.

واجهة برمجة تطبيقات سرّية

يُستخدَم api_secret لمصادقة طلباتك. ومن الضروري الحفاظ على سرية هذا المفتاح.

لإنشاء مفتاح سرّي جديد، اتّبِع الخطوات التالية:

انتقِل إلى إحصاءات Google وانتقِل إلى حسابك وموقعك.
انقر على المشرف في أسفل يمين الصفحة.
ضِمن جمع البيانات وتعديلها، انقر على مصادر البيانات.
اختَر مصدر بيانات الموقع الإلكتروني أو التطبيق.
انقر على واجهات برمجة التطبيقات السرّية لمنصّة Measurement Protocol.
انقر على إنشاء.
أدخِل لقبًا للسرّ وانقر على إنشاء.
انسخ قيمة المفتاح السرّي.
ملاحظة مهمة: api_secret خاص. ولا تعرضه في الرمز البرمجي من جهة العميل لموقعك الإلكتروني أو تطبيقك.
- مخاطر أمنية: يؤدي الكشف عن api_secret إلى السماح لجهات غير مصرّح لها بإرسال بيانات عشوائية أو غير مرغوب فيها إلى موقعك على "إحصاءات Google"، ما قد يؤدي إلى إتلاف تقاريرك.
- الاستخدام الصحيح: تم تصميم Measurement Protocol في الأساس للبيئات من جهة الخادم أو البيئات الموثوقة (مثل الأنظمة غير المتصلة بالإنترنت أو الاتصال بين الخوادم).
- التتبُّع من جهة العميل: إذا كنت بحاجة إلى إرسال الأحداث مباشرةً من متصفّح ويب، استخدِم علامة تتبُّع من Google‏ (gtag.js) أو Google Tag Manager.
- إضافات Chrome: بالنسبة إلى إضافات Chrome المتوافقة مع الإصدار 3 من Manifest، لا يمكنك تحميل رمز برمجي عن بُعد، مثل gtag.js. في هذه الحالة، ننصحك باستخدام Measurement Protocol. اطّلِع على مقالة استخدام "إحصاءات Google" في إضافات Chrome.

رقم تعريف تطبيق Firebase

firebase_app_id هو معرّف تطبيقك على Firebase، وهو يختلف عن app_instance_id.

للعثور على معرّف تطبيق Firebase، اتّبِع الخطوات التالية:

افتح مشروعك في وحدة تحكّم Firebase.
انقر على رمز الترس الخاص بالإعدادات بجانب نظرة عامة على المشروع، ثم اختَر إعدادات المشروع.
ضِمن علامة التبويب الإعدادات العامة، انتقِل إلى قسم تطبيقاتك.
اختَر تطبيق iOS أو Android المحدّد.
انسخ قيمة رقم تعريف التطبيق.

تهيئة الطلب

لا يتيح بروتوكول القياس في "إحصاءات Google" سوى طلبات HTTP POST.

لإرسال حدث، استخدِم التنسيق التالي:

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

يجب توفير ما يلي في مَعلمات طلب البحث في عنوان URL (راجِع المتطلبات الأساسية للحصول على تفاصيل حول كيفية العثور على هذه القيم أو إنشائها):

‫api_secret: هو سرّ واجهة برمجة التطبيقات المستخدَم لمصادقة الطلب.
firebase_app_id: رقم تعريف تطبيق Firebase الخاص بتطبيقك.

يجب تقديم نص الطلب بتنسيق نص POST بتنسيق JSON لبروتوكول القياس. وفي ما يلي مثال لذلك:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

يجب تقديم app_instance_id في نص الطلب لتحديد عملية تثبيت فريدة لتطبيقك على الأجهزة الجوّالة، مع العلم أنّ هذا المعرّف يختلف عن firebase_app_id الذي يحدّد التطبيق نفسه. لمزيد من المعلومات عن app_instance_id وكيفية استرداده باستخدام حزمة تطوير البرامج (SDK) لمنصة Firebase، راجِع المستندات المرجعية الخاصة بمعرّف مثيل التطبيق.

مع أنّ session_start هو اسم حدث محجوز، يؤدي إنشاء session_id جديد إلى إنشاء جلسة جديدة بدون الحاجة إلى إرسال session_start. كيفية احتساب الجلسات

تجربة الميزة

في ما يلي مثال يمكنك استخدامه لإرسال أحداث متعددة في الوقت نفسه. يرسل هذا المثال الحدث tutorial_begin والحدث join_group إلى خادم "إحصاءات Google"، ويتضمّن معلومات جغرافية باستخدام الحقل user_location، ويتضمّن معلومات الجهاز باستخدام الحقل device.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    device: {
      category: "mobile",
      language: "en",
      screen_resolution: "1280x2856",
      operating_system: "Android",
      operating_system_version: "14",
      model: "Pixel 9 Pro",
      brand: "Google",
      browser: "Chrome",
      browser_version: "136.0.7103.60"
    }
  })
});

تنسيق firebase_app_id خاص بالنظام الأساسي. راجِع رقم تعريف التطبيق ضمن ملفات وأهداف إعدادات Firebase.

تجاهل الطابع الزمني

يستخدِم Measurement Protocol الطابع الزمني الأول الذي يعثر عليه في القائمة التالية لكل حدث وخاصية مستخدم في الطلب:

timestamp_micros الحدث أو خاصية المستخدم
timestamp_micros الطلب
الوقت الذي تتلقّى فيه منصّة Measurement Protocol الطلب

يرسل المثال التالي طابعًا زمنيًا على مستوى الطلب ينطبق على جميع الأحداث وخصائص المستخدم في الطلب. نتيجةً لذلك، يحدّد Measurement Protocol طابعًا زمنيًا بقيمة requestUnixEpochTimeInMicros للحدثَين tutorial_begin وjoin_group وخاصية المستخدِم customer_tier.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

يرسل المثال التالي طابعًا زمنيًا على مستوى الطلب، وطابعًا زمنيًا على مستوى الحدث، وطابعًا زمنيًا على مستوى خاصية المستخدم. نتيجةً لذلك، يحدّد Measurement Protocol الطوابع الزمنية التالية:

tutorialBeginUnixEpochTimeInMicros لفعالية tutorial_begin
customerTierUnixEpochTimeInMicros لخاصية المستخدِم customer_tier
requestUnixEpochTimeInMicros للحدث join_group وخاصية المستخدم newsletter_reader.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

سلوك التحقّق من الصحة للأحداث وخصائص المستخدمين السابقة

يمكن إرجاع تاريخ الأحداث وخصائص المستخدمين إلى 72 ساعة كحدّ أقصى. إذا كانت قيمة timestamp_micros أقدم من 72 ساعة، يقبل Measurement Protocol الحدث أو خاصية المستخدم أو يرفضهما على النحو التالي:

في حال عدم ضبط validation_behavior أو ضبطه على RELAXED، يقبل Measurement Protocol الحدث أو خاصية المستخدم، ولكنّه يتجاهل الطابع الزمني ويضبطه على 72 ساعة مضت.
إذا تم ضبط validation_behavior على ENFORCE_RECOMMENDATIONS، سيرفض Measurement Protocol الحدث أو خاصية المستخدِم.

يجب أن تتلقّى "إحصاءات Google" الأحداث المُرسَلة باستخدام Measurement Protocol والمخصّصة للدمج أو المعالجة مع الأحداث التي تجمعها حزمة تطوير البرامج (SDK) الخاصة بخدمة "إحصاءات Google لبرنامج Firebase" أو gtag.js في غضون 48 ساعة من الطابع الزمني الأصلي للحدث من جهة العميل. وقد لا تتم معالجة الأحداث التي يتم تلقّيها بعد هذا الوقت على النحو المتوقّع، خاصةً لأغراض مثل تحديد مصدر الإحالة الناجحة.

القيود

تنطبق القيود التالية على إرسال أحداث Measurement Protocol إلى "إحصاءات Google":

يمكنك إرسال 100 مليون طلب غير مرتبط بإحالات ناجحة كحدّ أقصى في الساعة لكل موقع. الطلب هو طلب غير مرتبط بإحالة ناجحة إذا لم يكن أي من الأحداث في الطلب حدثًا رئيسيًا تم تسجيل إحالة ناجحة له في "إعلانات Google". في حال تجاوز هذا الحدّ، سيتجاهل Measurement Protocol تلقائيًا جميع الطلبات غير المرتبطة بإحالات ناجحة للموقع لبقية الساعة.

نقطة أساسية: لا ينطبق هذا الحدّ على مواقع "إحصاءات Google‏ 360".
يمكن أن تتضمّن الطلبات 25 حدثًا كحدّ أقصى.
يمكن أن تحتوي الأحداث على 25 معلَمة كحدّ أقصى.
يمكن أن تحتوي الأحداث على 25 خاصيّة مستخدم كحدّ أقصى.
يجب أن تحتوي أسماء خصائص المستخدمين على 24 حرفًا أو أقل.
يجب أن تحتوي قيم خصائص المستخدمين على 36 حرفًا أو أقل.
يجب أن تحتوي أسماء الأحداث على 40 حرفًا أو أقل، وأن تحتوي على أحرف أبجدية رقمية وشرطات سفلية فقط، ويجب أن تبدأ بحرف أبجدي.
يجب أن تحتوي أسماء المَعلمات، بما في ذلك مَعلمات السلع، على 40 حرفًا أو أقل، وأن تحتوي على أحرف أبجدية رقمية وشرطات سفلية فقط، ويجب أن تبدأ بحرف أبجدي.
يجب أن تحتوي قيم المَعلمات، بما في ذلك قيم مَعلمات السلع، على 100 حرف أو أقلّ في موقع عادي على "إحصاءات Google"، و500 حرف أو أقلّ في موقع على "إحصاءات Google‏ 360".

لا ينطبق هذا الحدّ على المَعلمتَين session_id وsession_number عندما يتم توفير قيمهما من خلال المتغيّرَين المضمّنَين رقم تعريف جلسة "إحصاءات Google" ورقم جلسة "إحصاءات Google" المقابلَين في "إدارة العلامات من Google".
يمكن أن تتضمّن مَعلمات المنتجات أو الخدمات 10 مَعلمات مخصّصة كحدّ أقصى.
يجب أن يكون حجم نص المشاركة أقل من 130 كيلوبايت.
لا تؤدّي أحداث Measurement Protocol لقياس بيانات التطبيق المُرسَلة إلى "إحصاءات Google" إلى تعبئة شرائح جمهور البحث في "إعلانات Google" لمستخدمي التطبيق.
بعض أسماء الأحداث والمَعلمات وخصائص المستخدمين محجوزة ولا يمكن استخدامها. اطّلِع على الأسماء المحجوزة للحصول على التفاصيل.

الأسماء المحجوزة

يحتوي Measurement Protocol على العديد من الأسماء المحجوزة التي لا يمكن استخدامها للأحداث أو المَعلمات أو خصائص المستخدِمين.

في ما يلي أسماء الأحداث التي غالبًا ما يتم الخلط بينها:

screen_view: لا يُسمح بهذا الحدث إلا في "تدفقات التطبيقات". بالنسبة إلى مصادر بيانات من موقع إلكتروني، استخدِم page_view بدلاً من ذلك.
ad_impression: لا يُسمح بهذا الحدث إلا في "تدفقات التطبيقات".
in_app_purchase: لا يُسمح بهذا الحدث إلا في "تدفقات التطبيقات". بالنسبة إلى مصادر بيانات من موقع إلكتروني، استخدِم حدث purchase بدلاً من ذلك.

للاطّلاع على المتطلبات الإضافية لكل حالة استخدام، راجِع حالات الاستخدام الشائعة.