این صفحه سازوکار انتقال و پارامترهای داده را برای «پروتکل اندازهگیری» شرح میدهد.
حملونقل
همه دادهها باید بهطور ایمن بااستفاده از درخواستهای 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 کد خطا برنمیگرداند.
پایهبار
پایهبار دو بخش دارد:
- پارامترهای پُرسمان.
- بدنه JSON
POST.
پارامترهای پُرسمان
| نام پارامتر | شرح |
|---|---|
|
الزامی. رمز میانای برنامهسازی کاربردی از میانای کاربر Google Analytics.
در سرپرست > جاریسازیهای داده > انتخاب جاریسازی > پروتکل اندازهگیری > ایجاد یافت میشود. خصوصی برای سازمان شما. باید بهطور مرتب بهروز شود تا از هرزنامه بیشازحد جلوگیری شود. |
|
الزامی. شناسه Firebase App. شناسه برنامه Firebase.
در کنسول Firebase در بخش تنظیمات پروژه > عمومی > برنامههای شما > شناسه برنامه یافت میشود. |
بدنه JSON POST
اندازه بدنه JSON POST باید کمتر از ۱۳۰ کیلوبایت باشد.
| کلید | نوع | شرح |
|---|---|---|
|
string |
الزامی. شناسه یکتا برای نصب خاصی از
برنامه Firebase.
با باید بااستفاده از کیت توسعه نرمافزار Firebase بازیابی شود: |
|
string |
اختیاری. شناسه یکتا برای کاربر. برای اطلاعات بیشتر درباره این شناسه، به شناسه کاربر برای تجزیهوتحلیل چندپلاتفرمی مراجعه کنید. فقط میتواند شامل نویسههای utf-8 باشد. |
|
number |
اختیاری. مُهر زمان یونیکس، میکروثانیه، نه
میلیثانیه. زمان رویداد را نشان میدهد. باید فقط برای ثبت رویدادهایی تنظیم شود که در گذشته اتفاق افتادهاند. میتواند با
|
|
object |
اختیاری. مشخصههای کاربر برای سنجش. در هر درخواست، حداکثر ۲۵ ویژگی کاربر میتواند ارسال شود. نامهای ویژگی کاربر باید ۲۴ نویسه یا کمتر باشد و مقادیر ویژگی کاربر باید ۳۶ نویسه یا کمتر باشد. |
|
object |
اختیاری. دادههای ارائهشده توسط کاربر. |
|
object |
اختیاری. تنظیمات موافقت برای درخواست. برای اطلاعات بیشتر، بخش رضایت را ببینید. |
|
boolean |
اختیاری. روی true تنظیم کنید تا نشان دهید نباید از دادههای کاربر
برای آگهیهای شخصیسازیشده استفاده شود.
|
|
object |
اختیاری. اطلاعات جغرافیایی را برای درخواست در قالب ساختاریافته تنظیم میکند. |
|
string |
اختیاری. نشانی IP که Google Analytics برای استخراج اطلاعات جغرافیایی برای درخواست استفاده میکند. |
|
object |
اختیاری. اطلاعات دستگاه را برای درخواست در قالب ساختاریافته تنظیم میکند. |
|
string |
اختیاری. رفتار اعتبارسنجی را برای درخواست تنظیم میکند. |
|
array |
الزامی. آرایهای از event مورد. در هر درخواست، حداکثر ۲۵ رویداد میتواند ارسال شود. برای رویدادهای توصیهشده، به مرجع رویدادها مراجعه کنید.
|
|
string |
الزامی. نام رویداد. نام رویداد باید ۴۰ نویسه یا کمتر باشد. برای رویدادهای توصیهشده، رویدادها را ببینید. |
|
object |
اختیاری. پارامترهای رویداد. حداکثر ۲۵ پارامتر را میتوان
برای هر رویداد ارسال کرد. برای پارامترهای توصیهشده برای هر رویداد، رویدادها را ببینید، و پارامترهای رویداد رایج.
نام پارامترها باید ۴۰ نویسه یا کمتر باشد. مقادیر پارامتر باید ۱۰۰ نویسه یا کمتر برای دارایی استاندارد Google Analytics، و ۵۰۰ نویسه یا کمتر برای دارایی Google Analytics 360 باشد. |
پارامترهای رویداد معمول
Measurement Protocol پارامترهای رویداد رایج زیر را دارد:
| کلید | نوع | شرح |
|---|---|---|
|
number |
عددی مثبت که جلسه کاربر را شناسایی میکند. برای چندین
مورد استفاده رایج لازم است.
باید با عبارت باقاعده ^\d+$ مطابقت داشته باشد.
باید بااستفاده از کیت توسعه نرمافزار Firebase بازیابی شود: |
|
number |
مدت مشارکت کاربر، برحسب میلیثانیه، برای رویداد. از مقداری استفاده کنید که نشاندهنده میزان زمان تعامل کاربر از رویداد قبلی باشد. |
|
number |
زمان تاریخ یونیکس، برحسب میکروثانیه، برای رویداد. از این پارامتر برای لغو کردن مُهر زمان رویداد استفاده کنید. |
رضایت
مشخصه consent انواع و وضعیتهای رضایت را پیکربندی میکند.
اگر consent را مشخص نکنید، Google Analytics از تنظیمات رضایت
مربوط به تعاملات آنلاین برای کارخواه یا نمونه برنامه استفاده میکند.
| کلید | نوع | شرح |
|---|---|---|
|
string |
اختیاری. رضایت برای ارسال دادههای کاربر از رویدادهای درخواست و ویژگیهای کاربر به Google برای اهداف تبلیغاتی. |
|
string |
اختیاری. موافقت کاربر با تبلیغات شخصیسازیشده. |
اطلاعات جغرافیایی
مشخصههای user_location و ip_override اطلاعات جغرافیایی را ارائه میدهند.
user_location بر ip_override اولویت دارد.
ساختار فیلد user_location در اینجا آمده است. تا حد امکان مشخصههای بیشتری ارائه دهید. حداقل country_id و region_id را توصیه میکنیم.
| کلید | نوع | شرح |
|---|---|---|
|
string |
اختیاری. نام
شهر. اگر شهر در ایالات متحده است، country_id و region_id را نیز تنظیم کنید تا Google Analytics بتواند نام شهر را بهدرستی به شناسه شهر نگاشت کند.
|
|
string |
اختیاری. کشور و بخش فرعی ISO 3166. برای مثال، US-CA، US-AR،
CA-BC، GB-LND، CN-HK.
|
|
string |
اختیاری. کشور در قالب ISO 3166-1 alpha-2. برای مثال، US، AU،
ES، FR.
|
|
string |
اختیاری. شبهقاره در قالب UN M49. برای
مثال، 011، 021، 030،
039.
|
|
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 را توصیه میکنیم.
| کلید | نوع | شرح |
|---|---|---|
|
string |
اختیاری. دسته دستگاه. برای مثال،
desktop،
tablet،
mobile،
smart TV.
|
|
string |
اختیاری. زبان در قالب ISO 639-1. برای
مثال، en، en-US.
|
|
string |
اختیاری. وضوح دستگاه، قالببندیشده بهصورت
WIDTHxHEIGHT. برای مثال، 1280x2856،
1080x2340.
|
|
string |
اختیاری. سیستمعامل یا پلاتفرم. برای مثال،
MacOS.
|
|
string |
اختیاری. نسخه سیستمعامل یا پلاتفرم. برای
مثال، 13.5.
|
|
string |
اختیاری. مدل دستگاه. برای مثال،
Pixel 9 Pro، Samsung Galaxy S24.
|
|
string |
اختیاری. نمانام دستگاه. برای مثال،
Google، Samsung.
|
|
string |
اختیاری. نمانام یا نوع مرورگر. برای مثال،
Chrome، Firefox.
|
|
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_activeviewad_clickad_exposuread_queryad_rewardadunit_exposureapp_clear_dataapp_exceptionapp_installapp_removeapp_store_refundapp_updateapp_upgradedynamic_link_app_opendynamic_link_app_updatedynamic_link_first_openerrorfirebase_campaignfirebase_in_app_message_actionfirebase_in_app_message_dismissfirebase_in_app_message_impressionfirst_openfirst_visitnotification_dismissnotification_foregroundnotification_opennotification_receivenotification_sendos_updatesession_startuser_engagement
علاوهبراین، رویدادهای ad_impression، in_app_purchase، و screen_view فقط برای جاریسازیهای «برنامه» مجاز است.
نامهای پارامتر رزروشده
نامهای پارامتر زیر رزرو شدهاند و نمیتوان از آنها استفاده کرد:
firebase_conversion
نام پارامترها نمیتواند با موارد زیر شروع شود:
_ (underscore)firebase_ga_google_gtag.
نامهای مشخصه کاربر رزروشده
نامهای مشخصه کاربر زیر رزرو شدهاند و نمیتوان از آنها استفاده کرد:
first_open_timefirst_visit_timelast_deep_link_referreruser_idfirst_open_after_install
علاوهبراین، نامهای مشخصه کاربر نمیتوانند با موارد زیر شروع شوند:
_ (underscore)firebase_ga_google_