مرجع Measurement Protocol

توضّح هذه الصفحة آلية النقل ومعلمات البيانات الخاصة ببروتوكول القياس.

وسائل النقل

يجب إرسال جميع البيانات بشكل آمن باستخدام طلبات POST HTTPS.

أرسِل الطلبات إلى نقطة النهاية التالية:

https://www.google-analytics.com/mp/collect

إذا كنت تريد جمع بياناتك في الاتحاد الأوروبي، استخدِم نقطة النهاية التالية بدلاً من ذلك:

https://region1.google-analytics.com/mp/collect

إليك نموذج طلب POST:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

استبدِل PAYLOAD_DATA بـ الحِمل الخاص بالطلب.

يعرض Measurement Protocol رمز الحالة 2xx في حال تلقّي الطلب HTTP. لا يعرض Measurement Protocol رمز خطأ في حال كان الحمولة منسّقة بشكل غير صحيح، أو إذا كانت البيانات غير صحيحة أو لم تتم معالجتها من قِبل "إحصاءات Google".

الحمولة

تحتوي الحمولة على جزأين:

  1. مَعلمات طلب البحث
  2. نص POST بتنسيق JSON

مَعلمات طلب البحث

اسم المَعلمة الوصف

api_secret

 مَعلمة مطلوبة. واجهة برمجة تطبيقات سرّية من واجهة مستخدم "إحصاءات Google"

يمكنك العثور عليه ضمن المشرف > مصادر البيانات > اختَر مصدر بياناتك > Measurement Protocol > إنشاء.

خاص بمؤسستك يجب تعديلها بانتظام لتجنُّب المحتوى غير المرغوب فيه بشكل مفرط.

firebase_app_id

 مَعلمة مطلوبة. رقم تعريف تطبيق Firebase معرّف تطبيق Firebase

يمكنك العثور عليه في وحدة تحكّم Firebase ضمن إعدادات المشروع > عام > تطبيقاتك > رقم تعريف التطبيق.

نص POST بتنسيق JSON

يجب أن يكون حجم نص JSON POST أقل من 130 كيلوبايت.

المفتاح النوع الوصف

app_instance_id

 string مَعلمة مطلوبة. معرّف فريد لعملية تثبيت محدّدة لتطبيق Firebase

وهو يختلف عن client_id الويب.

يجب استردادها باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase:

user_id

 string

Optional. هي معرّف فريد لعميل. اطّلِع على User-ID لإجراء تحليل من عدّة منصات لمزيد من المعلومات عن هذا المعرّف. يمكن أن تتضمّن أحرف utf-8 فقط.

timestamp_micros

 number

Optional. طابع زمني لنظام التشغيل Unix، بالميكروثانية، وليس بالملي ثانية تمثّل هذه السمة وقت الحدث. يجب ضبطها فقط لتسجيل الأحداث التي وقعت في الماضي. يمكن تجاوزها باستخدام user_property أو الطوابع الزمنية للأحداث. يمكن تحديد تاريخ سابق للأحداث بما يصل إلى 72 ساعة.

user_properties

 object Optional. خصائص المستخدِم الخاصة بالقياس يمكن إرسال ما يصل إلى 25 خاصية مستخدم لكل طلب. يجب أن تحتوي أسماء خصائص المستخدمين على 24 حرفًا أو أقل، وأن تحتوي قيم خصائص المستخدمين على 36 حرفًا أو أقل.

user_data

 object Optional. البيانات المقدَّمة من المستخدم
object Optional. إعدادات الموافقة للطلب راجِع قسم "الموافقة" للحصول على مزيد من المعلومات.

non_personalized_ads

 boolean اختياري اضبط القيمة على true للإشارة إلى أنّه يجب عدم استخدام بيانات المستخدم لعرض إعلانات مخصّصة.

user_location

 object Optional. تضبط هذه السمة المعلومات الجغرافية للطلب بتنسيق منظَّم.

ip_override

 string Optional. عنوان IP الذي تستخدمه "إحصاءات Google" لاستخلاص المعلومات الجغرافية للطلب.

device

 object اختيارية: تضبط هذه السمة معلومات الجهاز للطلب بتنسيق منظَّم.

validation_behavior

 string

اختيارية: تضبط هذه السمة سلوك التحقّق من الصحة للطلب.

إما RELAXED أو ENFORCE_RECOMMENDATIONS يتم ضبط القيمة تلقائيًا على RELAXED في حال عدم تحديدها.

events[]

 array مَعلمة مطلوبة. مصفوفة من event عنصر يمكن إرسال ما يصل إلى 25 حدثًا لكل طلب. راجِع مرجع الأحداث للاطّلاع على الأحداث المقترَحة.

events[].name

 string مَعلمة مطلوبة. اسم الحدث يجب ألّا يزيد طول أسماء الأحداث عن 40 حرفًا. اطّلِع على الأحداث لمعرفة الأحداث المقترَحة.

events[].params

 object Optional. مَعلمات الحدث يمكن إرسال ما يصل إلى 25 مَعلمة لكل حدث. اطّلِع على الأحداث لمعرفة المَعلمات المقترَحة لكل حدث، وعلى مَعلمات الأحداث الشائعة.

يجب أن تتألف أسماء المَعلمات من 40 حرفًا أو أقل. يجب أن تكون قيم المَعلمات 100 حرف أو أقل لموقع عادي على "إحصاءات Google"، و500 حرف أو أقل لموقع على "إحصاءات Google‏ 360".

مَعلمات الأحداث الشائعة

يحتوي Measurement Protocol على مَعلمات الأحداث الشائعة التالية:

المفتاح النوع الوصف

session_id

 number رقم موجب يحدّد جلسة المستخدِم. مطلوب في العديد من حالات الاستخدام الشائعة. يجب أن يتطابق مع التعبير العادي ^\d+$.

يجب استردادها باستخدام حزمة تطوير البرامج (SDK) لمنصة Firebase:

engagement_time_msec

 number تمثّل هذه السمة مدة تفاعل المستخدم بالملّي ثانية مع الحدث. استخدِم قيمة تعكس مقدار وقت تفاعل المستخدِم منذ الحدث السابق.

timestamp_micros

 number تشير إلى وقت حقبة يونكس بالميكروثانية للحدث. استخدِم هذه المَعلمة لتجاوز الطابع الزمني للحدث.

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

المفتاح النوع الوصف

ad_user_data

 string

Optional. تشير إلى الموافقة على إرسال بيانات المستخدمين من أحداث الطلب وخاصيّات المستخدمين إلى Google لأغراض إعلانية.

إما GRANTED أو DENIED

ad_personalization

 string

Optional. الموافقة على الإعلانات المخصّصة للمستخدم

إما GRANTED أو DENIED

معلومات الموقع الجغرافي

تقدّم السمتان user_location وip_override معلومات جغرافية. تكون user_location لها الأولوية على ip_override.

في ما يلي بنية الحقل user_location. قدِّم أكبر عدد ممكن من السمات. ننصحك بتوفير country_id وregion_id على الأقل.

المفتاح النوع الوصف

city

 string Optional. اسم المدينة إذا كانت المدينة في الولايات المتحدة، اضبط أيضًا country_id وregion_id حتى تتمكّن "إحصاءات Google" من ربط اسم المدينة بشكل صحيح برقم تعريف المدينة.

region_id

 string Optional. تمثّل هذه السمة البلد والقسم الفرعي وفقًا لمعيار ISO 3166. على سبيل المثال، US-CA وUS-AR وCA-BC وGB-LND وCN-HK.

country_id

 string Optional. تمثّل هذه السمة البلد بتنسيق ISO 3166-1 alpha-2. على سبيل المثال، US وAU وES وFR.

subcontinent_id

 string Optional. القارة الفرعية بتنسيق UN M49 على سبيل المثال، 011 و021 و030 و039.

continent_id

 string Optional. تمثّل هذه السمة القارة بتنسيق UN M49. على سبيل المثال، 002 و019 و142 و150.

في ما يلي نموذج user_location:

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

‫ip_override هو بديل لـ user_location. في حال إرسال ip_override بدلاً من ذلك، تستمدّ "إحصاءات Google" المعلومات الجغرافية من عنوان IP. في حال إرسال user_location، تتجاهل "إحصاءات Google" القيمة ip_override.

في حال عدم إرسال user_location أو ip_override، تستمدّ "إحصاءات Google" المعلومات الجغرافية من الأحداث التي تمّت الإشارة إليها باستخداموapp_instance_id.

تطبِّق "إحصاءات Google" إعدادات بيانات الموقع الجغرافي التفصيلية الخاصة بالموقع على الطلب، بغض النظر عن المعلومات الجغرافية المُرسَلة.

معلومات الجهاز

لإرسال معلومات الجهاز، استخدِم الحقل device. في ما يلي بنية الحقل device. قدِّم أكبر عدد ممكن من السمات. ننصحك باستخدام category على الأقل.

المفتاح النوع الوصف

category

 string اختياري فئة الجهاز على سبيل المثال: desktop وtablet وmobile وsmart TV.

language

 string اختياري تمثّل هذه السمة اللغة بتنسيق ISO 639-1. على سبيل المثال، en وen-US.

screen_resolution

 string اختياري تمثّل هذه السمة دقة الجهاز، ويتم تنسيقها على النحو التالي: WIDTHxHEIGHT. على سبيل المثال، 1280x2856 و1080x2340.

operating_system

 string اختياري نظام التشغيل أو النظام الأساسي على سبيل المثال، MacOS.

operating_system_version

 string اختياري إصدار نظام التشغيل أو النظام الأساسي مثلاً: 13.5.

model

 string اختياري طراز الجهاز على سبيل المثال: Pixel 9 Pro وSamsung Galaxy S24.

brand

 string اختياري تمثّل هذه السمة العلامة التجارية للجهاز. على سبيل المثال: Google وSamsung.

browser

 string اختياري تمثّل هذه السمة العلامة التجارية للمتصفّح أو نوعه. على سبيل المثال: Chrome وFirefox.

browser_version

 string اختياري إصدار المتصفّح على سبيل المثال: 136.0.7103.60 و5.0.

يوضّح المقتطف التالي مثالاً على إعدادات device:

"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"
}
إذا لم يحدّد الطلب device، تستخلص "إحصاءات Google" معلومات الجهاز من أحداث وضع العلامات باستخدام app_instance_id.

بغض النظر عمّا إذا كنت تحدّد device, تطبِّق "إحصاءات Google" إعدادات البيانات التفصيلية للأجهزة الخاصة بالموقع على الطلب.

سلوك التحقّق من الصحة

تتحكّم السمة validation_behavior في طريقة تحقّق Measurement Protocol من صحة محتوى الطلب.

  • لا ترفض عملية التحقّق من صحة RELAXED سوى الطلبات التي تمت صياغتها بشكل غير صحيح. قد يظلّ يقبل الأحداث والمَعلمات التي تتضمّن أسماء حقول غير صالحة أو بيانات من النوع غير الصحيح، ولكنّه يتجاهل المَعلمات التي تتجاوز الحدود. يستخدم Measurement Protocol عملية التحقّق من الصحة RELAXED تلقائيًا.
  • ترفض عملية التحقّق من الصحة في ENFORCE_RECOMMENDATIONS مَعلمات الأحداث والمنتجات التي لا تتضمّن النوع الصحيح أو التي تحتوي على مَعلمات تتجاوز الحدود. بالإضافة إلى ذلك، ترفض ENFORCE_RECOMMENDATIONS أي حدث أو خاصية مستخدم يتضمّن طابعًا زمنيًا لا يقع ضمن آخر 72 ساعة.

ننصحك باتّباع الأسلوب التالي:

  • استخدِم ENFORCE_RECOMMENDATIONS عند التحقّق من صحة الأحداث للحصول على أكبر قدر ممكن من الملاحظات حول المشاكل المحتملة في طلباتك.

    يمكنك أيضًا التحقّق من صحة الطلبات باستخدام أداة إنشاء الأحداث لأنّها تحدّد ENFORCE_RECOMMENDATIONS عند التحقّق من صحة الطلبات.

  • لا تحدّد validation_behavior عند إرسال الأحداث للحدّ من البيانات التي يرفضها Measurement Protocol.

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

المعلمات المخصصة

يمكنك تضمين مَعلمات مخصّصة على مستوى المستخدِم وعلى مستوى الحدث وعلى مستوى المنتج أو الخدمة في حمولة Measurement Protocol.

  • يمكن تضمين المَعلمات المخصّصة على مستوى المستخدِم في user_properties.
  • يمكن تضمين المَعلمات المخصّصة على مستوى الحدث في events[].params.
  • يمكن تضمين المَعلمات المخصّصة على مستوى المنتج أو الخدمة في items.

تتضمّن بعض الأحداث مَعلمات مقترَحة. اطّلِع على الأحداث لمعرفة المَعلمات المقترَحة لجميع الأحداث المتوافقة.

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

بعض أسماء الأحداث والمَعلمات وخصائص المستخدمين محجوزة ولا يمكن استخدامها:

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

أسماء الأحداث التالية محجوزة ولا يمكن استخدامها:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

بالإضافة إلى ذلك، لا يُسمح بأحداث ad_impression وin_app_purchase وscreen_view إلا لمصادر بيانات التطبيقات.

أسماء المَعلمات المحجوزة

أسماء المَعلمات التالية محجوزة ولا يمكن استخدامها:

  • firebase_conversion

لا يمكن أن تبدأ أسماء المَعلمات بما يلي:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

أسماء خصائص المستخدمين المحجوزة

أسماء خصائص المستخدِمين التالية محجوزة ولا يمكن استخدامها:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

بالإضافة إلى ذلك، لا يمكن أن تبدأ أسماء خصائص المستخدِمين بما يلي:

  • _ (underscore)
  • firebase_
  • ga_
  • google_