مرجع 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 بـ Payload الخاص بالطلب.

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

الحمولة

تتضمّن الحمولة جزأين:

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

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

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

api_secret

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

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

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

نص POST بتنسيق JSON

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

user_id

 string

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

timestamp_micros

 number

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

user_properties

 object Optional. خصائص المستخدِم للقياس

user_data

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

non_personalized_ads

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

user_location

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

ip_override

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

device

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

events[]

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

events[].name

 string مَعلمة مطلوبة. اسم الحدث اطّلِع على الأحداث لمعرفة جميع الخيارات.

events[].params

 object Optional. مَعلمات الحدث اطّلِع على الأحداث للاطّلاع على المَعلمات المقترَحة لكل حدث، وعلى مَعلمات الأحداث الشائعة.

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

يتضمّن Measurement Protocol مَعلمات الأحداث الشائعة التالية:

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

session_id

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

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" المعلومات الجغرافية من الأحداث التي تمّت الإشارة إليها باستخدام client_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"
}

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

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

يمكنك تضمين مَعلمات مخصّصة على مستوى المستخدِم والحدث والمنتج أو الخدمة في حمولة 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

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

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

  • 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_