مرجع 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 را با بار مفید درخواست جایگزین کنید.

اگر درخواست HTTP دریافت شود، «پروتکل اندازه‌گیری» رمز وضعیت 2xx را برمی‌گرداند. اگر بار داده بدشکل باشد یا اگر داده‌ها نادرست باشند یا توسط Google Analytics پردازش نشوند، Measurement Protocol کد خطا برنمی‌گرداند.

پایه‌بار

پایه‌بار دو بخش دارد:

  1. پارامترهای پُرسمان.
  2. بدنه JSON POST.

پارامترهای پُرسمان

نام پارامتر شرح

api_secret

الزامی. رمز میانای برنامه‌سازی کاربردی از میانای کاربر Google Analytics.

در سرپرست > جاری‌سازی‌های داده > انتخاب جاری‌سازی > پروتکل اندازه‌گیری > ایجاد یافت می‌شود.

خصوصی برای سازمان شما. باید به‌طور مرتب به‌روز شود تا از هرزنامه بیش‌ازحد جلوگیری شود.

firebase_app_id

الزامی. شناسه Firebase App. شناسه برنامه Firebase.

در کنسول Firebase در بخش تنظیمات پروژه > عمومی > برنامه‌های شما > شناسه برنامه یافت می‌شود.

بدنه JSON POST

اندازه بدنه JSON POST باید کمتر از ۱۳۰ کیلوبایت باشد.

کلید نوع شرح

app_instance_id

string الزامی. شناسه یکتا برای نصب خاصی از برنامه Firebase.

با client_id وب یکسان نیست.

باید بااستفاده از کیت توسعه نرم‌افزار Firebase بازیابی شود:

user_id

string

اختیاری. شناسه یکتا برای کاربر. برای اطلاعات بیشتر درباره این شناسه، به شناسه کاربر برای تجزیه‌وتحلیل چندپلاتفرمی مراجعه کنید. فقط می‌تواند شامل نویسه‌های utf-8 باشد.

timestamp_micros

number

اختیاری. مُهر زمان یونیکس، میکروثانیه، نه میلی‌ثانیه. زمان رویداد را نشان می‌دهد. باید فقط برای ثبت رویدادهایی تنظیم شود که در گذشته اتفاق افتاده‌اند. می‌تواند با user_property یا مهرهای زمان رویداد لغو شود. رویدادها را می‌توان تا ۷۲ ساعت قبل تاریخ‌گذاری کرد.

user_properties

object اختیاری. مشخصه‌های کاربر برای سنجش. در هر درخواست، حداکثر ۲۵ ویژگی کاربر می‌تواند ارسال شود. نام‌های ویژگی کاربر باید ۲۴ نویسه یا کمتر باشد و مقادیر ویژگی کاربر باید ۳۶ نویسه یا کمتر باشد.

user_data

object اختیاری. داده‌های ارائه‌شده توسط کاربر.
object اختیاری. تنظیمات موافقت برای درخواست. برای اطلاعات بیشتر، بخش رضایت را ببینید.

non_personalized_ads

boolean اختیاری. روی true تنظیم کنید تا نشان دهید نباید از داده‌های کاربر برای آگهی‌های شخصی‌سازی‌شده استفاده شود.

user_location

object اختیاری. اطلاعات جغرافیایی را برای درخواست در قالب ساختاریافته تنظیم می‌کند.

ip_override

string اختیاری. نشانی IP که Google Analytics برای استخراج اطلاعات جغرافیایی برای درخواست استفاده می‌کند.

device

object اختیاری. اطلاعات دستگاه را برای درخواست در قالب ساختاریافته تنظیم می‌کند.

validation_behavior

string

اختیاری. رفتار اعتبارسنجی را برای درخواست تنظیم می‌کند.

‫RELAXED یا ENFORCE_RECOMMENDATIONS. اگر مشخص نشده باشد، به‌طور پیش‌فرض روی RELAXED تنظیم می‌شود.

events[]

array الزامی. آرایه‌ای از event مورد. در هر درخواست، حداکثر ۲۵ رویداد می‌تواند ارسال شود. برای رویدادهای توصیه‌شده، به مرجع رویدادها مراجعه کنید.

events[].name

string الزامی. نام رویداد. نام رویداد باید ۴۰ نویسه یا کمتر باشد. برای رویدادهای توصیه‌شده، رویدادها را ببینید.

events[].params

object اختیاری. پارامترهای رویداد. حداکثر ۲۵ پارامتر را می‌توان برای هر رویداد ارسال کرد. برای پارامترهای توصیه‌شده برای هر رویداد، رویدادها را ببینید، و پارامترهای رویداد رایج.

نام پارامترها باید ۴۰ نویسه یا کمتر باشد. مقادیر پارامتر باید ۱۰۰ نویسه یا کمتر برای دارایی استاندارد Google Analytics، و ۵۰۰ نویسه یا کمتر برای دارایی Google Analytics 360 باشد.

پارامترهای رویداد معمول

‫Measurement Protocol پارامترهای رویداد رایج زیر را دارد:

کلید نوع شرح

session_id

number عددی مثبت که جلسه کاربر را شناسایی می‌کند. برای چندین مورد استفاده رایج لازم است. باید با عبارت باقاعده ^\d+$ مطابقت داشته باشد.

باید بااستفاده از کیت توسعه نرم‌افزار Firebase بازیابی شود:

engagement_time_msec

number مدت مشارکت کاربر، برحسب میلی‌ثانیه، برای رویداد. از مقداری استفاده کنید که نشان‌دهنده میزان زمان تعامل کاربر از رویداد قبلی باشد.

timestamp_micros

number زمان تاریخ یونیکس، برحسب میکروثانیه، برای رویداد. از این پارامتر برای لغو کردن مُهر زمان رویداد استفاده کنید.

مشخصه consent انواع و وضعیت‌های رضایت را پیکربندی می‌کند. اگر consent را مشخص نکنید، Google Analytics از تنظیمات رضایت مربوط به تعاملات آنلاین برای کارخواه یا نمونه برنامه استفاده می‌کند.

کلید نوع شرح

ad_user_data

string

اختیاری. رضایت برای ارسال داده‌های کاربر از رویدادهای درخواست و ویژگی‌های کاربر به Google برای اهداف تبلیغاتی.

‫GRANTED یا DENIED.

ad_personalization

string

اختیاری. موافقت کاربر با تبلیغات شخصی‌سازی‌شده.

‫GRANTED یا DENIED.

اطلاعات جغرافیایی

مشخصه‌های user_location و ip_override اطلاعات جغرافیایی را ارائه می‌دهند. user_location بر ip_override اولویت دارد.

ساختار فیلد user_location در اینجا آمده است. تا حد امکان مشخصه‌های بیشتری ارائه دهید. حداقل country_id و region_id را توصیه می‌کنیم.

کلید نوع شرح

city

string اختیاری. نام شهر. اگر شهر در ایالات متحده است، country_id و region_id را نیز تنظیم کنید تا Google Analytics بتواند نام شهر را به‌درستی به شناسه شهر نگاشت کند.

region_id

string اختیاری. کشور و بخش فرعی ISO 3166. برای مثال، US-CA، US-AR، CA-BC، GB-LND، CN-HK.

country_id

string اختیاری. کشور در قالب ISO 3166-1 alpha-2. برای مثال، US،‏ AU،‏ ES،‏ FR.

subcontinent_id

string اختیاری. شبه‌قاره در قالب UN M49. برای مثال، 011،‏ 021،‏ 030،‏ 039.

continent_id

string اختیاری. قاره در قالب 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 Analytics اطلاعات جغرافیایی را از نشانی IP استخراج می‌کند. اگر user_location را ارسال کنید، Google Analytics از ip_override صرف‌نظر می‌کند.

اگر user_location یا ip_override را ارسال نکنید، Google Analytics اطلاعات جغرافیایی را بااستفاده ازapp_instance_id از رویدادهای برچسب‌گذاری استخراج می‌کند.

Google Analytics تنظیمات داده‌های مکان دانه‌ای دارایی را، صرف‌نظر از اطلاعات جغرافیایی ارسال‌شده، در درخواست اعمال می‌کند.

اطلاعات دستگاه

برای ارسال اطلاعات دستگاه، از فیلد 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 Analytics اطلاعات دستگاه را از رویدادهای برچسب‌گذاری بااستفاده از app_instance_id استخراج می‌کند.

صرف‌نظر از اینکه device، Google Analytics تنظیمات داده‌های دستگاه گرانولار دارایی را برای درخواست اعمال می‌کند.

رفتار اعتبارسنجی

مشخصه validation_behavior کنترل می‌کند که «پروتکل اندازه‌گیری» چگونه محتوای درخواست را اعتبارسنجی کند.

  • اعتبارسنجی RELAXED فقط درخواست‌های بدشکل را رد می‌کند. ممکن است همچنان رویدادها و پارامترهای دارای نام فیلد نامعتبر یا داده‌های دارای نوع نادرست را بپذیرد، اما پارامترهایی را که از حدود فراتر می‌روند نادیده می‌گیرد. «پروتکل اندازه‌گیری» به‌طور پیش‌فرض از اعتبارسنجی RELAXED استفاده می‌کند.
  • اعتبارسنجی ENFORCE_RECOMMENDATIONS پارامترهای رویداد و موردی را که از نوع صحیح نیستند یا حاوی پارامترهایی هستند که از حدود فراتر می‌روند رد می‌کند. علاوه‌براین، ENFORCE_RECOMMENDATIONS هر رویداد یا ویژگی کاربری را که مهر زمان آن مربوط به ۷۲ ساعت گذشته نباشد رد می‌کند.

رویکرد زیر را توصیه می‌کنیم:

  • هنگام اعتبارسنجی رویدادها، از 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_