مرجع Measurement Protocol

توضّح هذه الصفحة آلية النقل ومَعلمات البيانات في Measurement Protocol.

وسائل النقل

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

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

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. نص JSON POST.

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

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

api_secret

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

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

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

firebase_app_id

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

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

نص JSON POST

يجب أن يكون حجم نص 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_