مرجع Measurement Protocol

نظرة عامة

هناك قسمان لإرسال البيانات إلى "إحصاءات Google" باستخدام "بروتوكول القياس":

  1. النقل - مكان إرسال البيانات وكيفية إرساله
  2. الحمولة - البيانات التي ترسلها

يصف هذا المستند كيفية تنسيق النقل والحمولة.

خدمة نقل

نقطة نهاية عنوان URL

يمكنك إرسال البيانات باستخدام Measurement Protocol عن طريق تقديم طلبات HTTP POST إلى نقطة النهاية التالية:

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

لإرسال حدث، يمكنك إصدار طلب "POST" التالي:

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

  • تمثّل هذه السمة BODY للطلب. راجِع حمولة.

رموز الاستجابة

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

المحتوى

يتم إرسال البيانات إلى "إحصاءات Google" باستخدام بيانات Measurement Protocol في جزأين:

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

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

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

api_secret

مطلوبة. نوع API Secret يتم إنشاؤه من خلال واجهة مستخدم "إحصاءات Google".

لإنشاء مفتاح سرّي جديد، انتقِل في واجهة مستخدِم "إحصاءات Google" إلى:
المشرف > مصادر البيانات > اختيار مصدر بياناتك > Measurement Protocol > إنشاء

وننصحك بإبقاء هذه الإعدادات خاصة في مؤسستك. في حال تفعيل Measurement Protocol من جهة العميل، يجب عرض api_secret بالتناوب بشكل منتظم لتجنُّب الرسائل غير المرغوب فيها بشكلٍ مفرط.

firebase_app_id

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

measurement_id

 رقم تعريف القياس. معرِّف مصدر البيانات. يمكن العثور عليه في واجهة مستخدم "إحصاءات Google" ضمن:
المشرف > مصادر البيانات > اختيار مصدر بياناتك > رقم تعريف القياس

نص مشاركة JSON

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

app_instance_id

 string

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

client_id

 string

مطلوبة. يحدِّد بشكلٍ فريد مثيل المستخدم في عميل ويب. اطّلِع على إرسال الحدث إلى Measurement Protocol.

user_id

 string

اختياريّ. معرّف فريد للمستخدِم. راجِع User-ID للتحليل من عدّة منصات للحصول على مزيد من المعلومات عن هذا المعرّف.

timestamp_micros

 number

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

user_properties

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

non_personalized_ads

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

events[]

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

events[].name

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

events[].params

 object اختياريّ. مَعلمات الحدث اطّلِع على الأحداث للاطّلاع على المَعلمات المقترَحة لكل حدث.

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

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

ad_user_data

 string

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

يجب أن تكون القيمة GRANTED أو DENIED.

ad_personalization

 string

اختيارية. لضبط الموافقة على الإعلانات المخصّصة للمستخدم.

يجب أن تكون القيمة GRANTED أو DENIED.

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

إضافةً إلى المَعلمات المحدّدة، يمكنك تضمين مَعلمات مخصّصة على مستوى المستخدم وعلى مستوى الحدث وعلى مستوى المنتج أو الخدمة داخل حمولة بيانات 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_