تعيينات الحقول

استخدِم عمليات الربط في الجداول لربط طلب جمع البيانات Measurement Protocol (/mp/collect) بمكافئه IngestEventsRequest في Data Manager API.

حقول الطلب

طلب /mp/collect (Measurement Protocol)	IngestEventsRequest (Data Manager API)	ملاحظات
measurement_id (مَعلمة طلب البحث)	destinations	خريطة إلى product_destination_id لـ أحداث الويب راجِع حقول الوجهة للاطّلاع على التفاصيل.
firebase_app_id (مَعلمة طلب البحث)	destinations	خريطة إلى product_destination_id لأحداث التطبيق راجِع حقول الوجهة للاطّلاع على التفاصيل.
api_secret (مَعلمة طلب البحث)	بدون مكافئ	اطّلِع على إعداد إذن الوصول إلى واجهة برمجة التطبيقات للتعرّف على كيفية مصادقة الطلبات في Data Manager API.
consent	consent	يجب ضبطها على عنصر Consent.
events	events	يجب ضبطها على قائمة بموارد Event. راجِع قسم حقول الأحداث للحصول على التفاصيل.
client_id	events.client_id	مطلوب للأحداث على الويب.
app_instance_id	events.app_instance_id	مطلوب لأحداث التطبيق.
user_id	events.user_id	اختياريّ. هي معرّف فريد لعميل.
timestamp_micros	events.event_timestamp	في Measurement Protocol، يمكن تقديم ذلك على مستوى الطلب أو لحدث فردي. في Data Manager API، لا يتوفّر طابع زمني على مستوى الطلب. اضبط قيمة event_timestamp على كل حدث لتكون وقت وقوع الحدث. في حال استخدام تنسيق JSON، اضبط القيمة بتنسيق RFC 3339. في حال استخدام بروتوكولات المخزن المؤقت، استخدِم Timestamp واضبط الحقلَين seconds وnanoseconds (اختياريًا). لمزيد من التفاصيل، يُرجى الاطّلاع على تنسيق الطابع الزمني.
user_properties	events.user_properties	يجب ضبطها على عنصر UserProperties. لا تتيح واجهة برمجة التطبيقات الخاصة بأداة "إدارة بيانات إعلانات Google" ضبط الطوابع الزمنية لسمات المستخدم الفردية. يتم استنتاج الطوابع الزمنية المرتبطة بالتغييرات في خصائص المستخدم من الطابع الزمني للحدث (event_timestamp).
user_data	events.user_data	يجب ضبطها على عنصر UserData. راجِع حقول معرّفات المستخدمين لمعرفة التفاصيل.
non_personalized_ads	events.consent.ad_personalization	إذا كان non_personalized_ads هو true، اضبط ad_personalization على DENIED.
user_location	events.event_location	لمزيد من التفاصيل، يُرجى الاطّلاع على حقول موقع المستخدم.
ip_override	events.event_device_info.ip_address
device	events.event_device_info	لمزيد من التفاصيل، يمكنك الاطّلاع على حقول الأجهزة.
user_agent	events.event_device_info.user_agent
validation_behavior	بدون مكافئ	استخدِم بيانات التشخيص لاسترداد حالة عملية التحميل بالإضافة إلى الأخطاء والتحذيرات للأحداث الفردية أثناء المعالجة النهائية. في حال تعذّر تنفيذ IngestEventsRequest (على سبيل المثال، بسبب عدم توفّر الحقول المطلوبة)، لن تتم معالجة أي أحداث، وسيكون عليك حلّ الخطأ وإعادة محاولة تنفيذ الطلب. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة التعرّف على أخطاء واجهة برمجة التطبيقات.
/debug/mp/collect	validate_only	اضبط validate_only على true للتحقّق من صحة الأحداث بدون استيعاب أي بيانات، على غرار خادم التحقّق من الصلاحية في Measurement Protocol.
بدون مكافئ	encoding	هذا الحقل مطلوب لتحميل UserData. اضبطها على Encoding المستخدَمة لقيم UserIdentifier.

حقول الوجهة

ترسل منصة Measurement Protocol الأحداث مباشرةً إلى مصدر بيانات معيّن باستخدام مَعلمة طلب البحث measurement_id أو firebase_app_id.

تستخدِم Data Manager API عنصر Destination لتحديد مكان إرسال البيانات. يمكنك الاطّلاع على مقالة ضبط الوجهات للحصول على مزيد من المعلومات حول الوجهات.

في ما يلي كيفية ربط حقول Measurement Protocol بالحقول المكافئة في Destination:

Measurement Protocol	Destination (Data Manager API)	ملاحظات
measurement_id (مَعلمة طلب البحث)	product_destination_id	يجب ضبطه على رقم تعريف القياس لمصدر بيانات الموقع الإلكتروني في "إحصاءات Google".
firebase_app_id (مَعلمة طلب البحث)	product_destination_id	يجب ضبطه على رقم تعريف تطبيق Firebase لمصدر بيانات التطبيق في "إحصاءات Google".
بدون مكافئ	operating_account	اضبط قيمة account_id على رقم تعريف الموقع على "إحصاءات Google". اضبط account_type على GOOGLE_ANALYTICS_PROPERTY.
بدون مكافئ	login_account	اضبط قيمة account_id على رقم تعريف الموقع على "إحصاءات Google". اضبط account_type على GOOGLE_ANALYTICS_PROPERTY.

حقول الأحداث

‫Measurement Protocol events[]	Event (Data Manager API)	ملاحظات
name	event_name	إذا استخدمت event_name اسمًا محجوزًا، سترفض واجهة برمجة التطبيقات الحدث مع ظهور الخطأ INVALID_EVENT_NAME.
بدون مكافئ	event_source	اضبط القيمة على WEB إذا تم إنشاء الحدث من متصفّح ويب، وعلى APP إذا تم إنشاؤه من تطبيق.
بدون مكافئ	destination_references	مطلوب إذا كانت قائمة destinations على مستوى الطلب تحتوي على أكثر من Destination واحدة من "إحصاءات Google". أضِف إدخالاً لتحديد الوجهة التي يجب أن تتلقّى الحدث.
timestamp_micros	event_timestamp	في حال استخدام تنسيق JSON، اضبط القيمة بتنسيق RFC 3339. في حال استخدام بروتوكولات المخزن المؤقت، استخدِم Timestamp واضبط الحقلَين seconds وnanoseconds (اختياريًا). لمزيد من التفاصيل، يُرجى الاطّلاع على تنسيق الطابع الزمني.
params.currency	currency
params.value	conversion_value
params.customer_type	user_properties.customer_type	في Measurement Protocol، يتم ضبط المَعلمة customer_type كمَعلمة خاصة بالحدث. في Data Manager API، اضبطها في الحقل customer_type في الكائن UserProperties في الحدث.
params.transaction_id	transaction_id	مطلوبة لبعض الأحداث وحالات الاستخدام. لمزيد من التفاصيل، اطّلِع على تحويل البيانات إلى عناصر Event.
params.items	cart_data.items	راجِع حقول المنتجات لبيانات سلة التسوّق لمعرفة التفاصيل.
params.coupon	cart_data.coupon_codes	استخدِم الحقل coupon_codes لتقديم القسائم التي تم تطبيقها على سلة التسوّق. يجب تقديم قسيمة واحدة فقط لخدمة "إحصاءات Google". وهي مستقلة عن القسائم على مستوى Item، والتي يمكن ضبطها باستخدام cart_data.items.additional_item_parameters للسلع الفردية.
params.session_id	additional_event_parameters	خريطة لإدخال تم ضبط parameter_name فيه على session_id
params.engagement_time_msec	additional_event_parameters	خريطة لإدخال تم ضبط parameter_name فيه على engagement_time_msec
params أخرى	additional_event_parameters	اربط المَعلمات الأخرى كقائمة من العناصر التي تتضمّن parameter_name وvalue. ملاحظة: لا تُضِف إدخالات transaction_id أو currency أو value هنا، بل استخدِم الحقول ذات المستوى الأعلى في Event.

حقول معرّفات المستخدمين

Measurement Protocol user_data	UserIdentifier (Data Manager API)	ملاحظات
sha256_email_address[]	email_address	يجب ضبطه على عنوان البريد الإلكتروني المنسَّق والمجزَّأ. يمكنك أيضًا تشفير عنوان البريد الإلكتروني المجزّأ.
sha256_phone_number[]	phone_number	يتم ضبطه على رقم الهاتف المنسَّق والمشفَّر. يمكنك أيضًا تشفير رقم الهاتف المجزّأ.
address[]	address	يجب ضبطها على عنصر AddressInfo. اتّبِع إرشادات التنسيق والتجزئة.
address[].sha256_first_name	address.given_name	اضبط على الاسم الأول المنسّق والمجزّأ. يمكنك أيضًا تشفير الاسم الأول المجزّأ.
address[].sha256_last_name	address.family_name	يجب ضبطها على اسم العائلة المنسّق والمجزّأ. يمكنك أيضًا تشفير اسم العائلة المجزّأ.
address[].country	address.region_code
address[].postal_code	address.postal_code
address[].city	بدون مكافئ	غير متاح في الإصدار الحالي من Data Manager API.
address[].region	بدون مكافئ	غير متاح في الإصدار الحالي من Data Manager API.
address[].sha256_street	بدون مكافئ	غير متاح في الإصدار الحالي من Data Manager API.

حقول السلع لبيانات سلة التسوّق

‫Measurement Protocol items[]	Item (Data Manager API)	ملاحظات
item_id	item_id	مطلوبة
item_name	additional_item_parameters	خريطة لإدخال تم ضبط parameter_name فيه على item_name
quantity	quantity	مطلوبة
price	unit_price	مطلوبة
حقول المنتجات الأخرى	additional_item_parameters	اربط مَعلمات المنتجات أو الخدمات الأخرى (مثل discount وaffiliation وitem_brand وما إلى ذلك) كقائمة من العناصر التي تتضمّن parameter_name وvalue. ملاحظة: لا تُضِف إدخالات quantity أو price أو item_id هنا، بل استخدِم الحقول ذات المستوى الأعلى في Item بدلاً من ذلك.

حقول الموقع الجغرافي للمستخدم

Measurement Protocol user_location	EventLocation (Data Manager API)	ملاحظات
city	city	تمثّل هذه السمة اسم المدينة التي وقع فيها الحدث.
country_id	region_code	يجب ضبطها على رمز CLDR للمنطقة المكوّن من حرفَين.
region_id	subdivision_code	يجب ضبطها على رمز التقسيم الفرعي وفقًا لمعيار ISO 3166-2.
continent_id	continent_code	يجب ضبطها على رمز القارة بتنسيق UN M49.
subcontinent_id	subcontinent_code	يجب ضبطها على رمز المنطقة الفرعية بتنسيق UN M49.

حقول الأجهزة

Measurement Protocol device	DeviceInfo (Data Manager API)	ملاحظات
category	category
language	language_code
screen_resolution	screen_height وscreen_width	في Measurement Protocol، يتمّ تقديم screen_resolution كسلسلة ("1280x720"). في Data Manager API، أرسِل screen_height وscreen_width كقيم أعداد صحيحة منفصلة.
operating_system	operating_system
operating_system_version	operating_system_version
model	model
brand	brand
browser	browser
browser_version	browser_version