مرجع Measurement Protocol

نظرة عامة

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

  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>

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

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

الحمولة

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

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

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

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

api_secret

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

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

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

محتوى النشر بتنسيق JSON

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

user_id

 string

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

timestamp_micros

 number

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

user_properties

 object اختياريّ. خصائص المستخدِمين للقياس اطّلِع على خصائص المستخدِمين للحصول على مزيد من المعلومات.

user_data

 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_