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

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

نکته: اگر کد وضعیت 2xx دریافت نکردید، خطاهای موجود در درخواست HTTP خود را اصلاح کنید. همان درخواست را دوباره امتحان نکنید.

پایه‌بار

Firebase gtag.js

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

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

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

نام پارامتر	شرح
api_secret	الزامی. رمز API از واسط کاربر Google Analytics. در سرپرست > جاری‌سازی‌های داده > انتخاب جاری‌سازی > پروتکل اندازه‌گیری > ایجاد پیدا می‌شود. خصوصی برای سازمان شما. باید به‌طور منظم به‌روز شود تا از هرزنامه بیش‌ازحد جلوگیری شود.
firebase_app_id	الزامی. شناسه برنامه Firebase. شناسه برنامه Firebase. در کنسول Firebase در بخش تنظیمات پروژه > کلی > برنامه‌های شما > شناسه برنامه پیدا می‌شود.

بدنه JSON POST

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

کلید	نوع	شرح
app_instance_id	string	الزامی. شناسه یکتا برای نصب خاص برنامه Firebase. با client_id وب یکسان نیست. باید بااستفاده از کیت توسعه نرم‌افزار Firebase بازیابی شود: ‫Android - getAppInstanceId() Kotlin - getAppInstanceId() Swift - appInstanceID() Objective-C - appInstanceID C++ - GetAnalyticsInstanceId() ‫Unity - GetAnalyticsInstanceIdAsync()
user_id	string	اختیاری. شناسه یکتا برای کاربر. برای اطلاعات بیشتر درباره این شناسه، شناسه کاربر برای تجزیه‌وتحلیل چندپلاتفرمی را ببینید. فقط می‌تواند شامل نویسه‌های utf-8 باشد.
timestamp_micros	number	اختیاری. مُهر زمان یونیکس، میکروثانیه، نه میلی‌ثانیه. نشان‌دهنده زمان رویداد است. باید فقط برای ثبت رویدادهایی که در گذشته اتفاق افتاده‌اند تنظیم شود. می‌تواند با user_property یا مُهرهای زمان رویداد ملغی شود. رویدادها را می‌توان تا ۷۲ ساعت به عقب برگرداند.
user_properties	object	اختیاری. مشخصه‌های کاربر برای اندازه‌گیری. در هر درخواست می‌توانید حداکثر ۲۵ دارایی کاربر ارسال کنید. نام‌های دارایی کاربر باید ۲۴ نویسه یا کمتر باشد و مقادیر دارایی کاربر باید ۳۶ نویسه یا کمتر باشد.
user_data	object	اختیاری. داده‌های ارائه‌شده توسط کاربر.
consent	object	اختیاری. تنظیمات موافقت برای درخواست. برای اطلاعات بیشتر، بخش موافقت را ببینید.
non_personalized_ads	boolean	منسوخ‌شده: درعوض از فیلد ad_personalization consent استفاده کنید. اختیاری. روی 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 بازیابی شود: Android - getSessionId() Kotlin - getSessionId() Swift - sessionID() Objective-C - sessionIDWithCompletion(...) C++ - GetSessionId() ‫Unity - GetSessionIdAsync()
engagement_time_msec	number	مدت مشارکت کاربر، برحسب میلی‌ثانیه، برای رویداد. از مقداری استفاده کنید که نشان‌دهنده میزان زمان تعامل کاربر از زمان رویداد قبلی باشد.
timestamp_micros	number	زمان تاریخ یونیکس، برحسب میکروثانیه، برای رویداد. از این پارامتر برای ملغی کردن برچسب زمان رویداد استفاده کنید.

نکته: برای اطمینان از دقیق بودن سنجه‌های تعامل کاربر و جلسه در گزارش‌هایتان، ازجمله زمان واقعی، پارامترهای session_id و engagement_time_msec را به رویدادهایتان اضافه کنید. اگرچه رویدادهای ارسال‌شده بدون این پارامترها ممکن است همچنان در برخی‌از گزارش‌ها نشان داده شوند، اما این رویدادها به‌درستی در سنجه‌هایی مثل «زمان تعامل میانگین» یا «جلسه‌های تعامل» مشارکت نخواهند داشت و ممکن است این رویدادها به‌طور کامل در «تعداد کاربران هم‌زمان» منعکس نشوند.

رضایت

مشخصه 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 را مشخص نکنید تا داده‌های ردشده توسط «پروتکل اندازه‌گیری» را به‌حداقل برسانید.

  اگر می‌خواهید هنگام ارسال درخواست خاصی، اعتبارسنجی دقیق را بر جمع‌آوری داده‌ها اولویت دهید، فیلد validation_behavior را اضافه کنید و آن را روی ENFORCE_RECOMMENDATIONS تنظیم کنید.

پارامترهای سفارشی

می‌توانید پارامترهای سفارشی با حوزه کاربر، حوزه رویداد، و حوزه مورد را در بار داده «پروتکل اندازه‌گیری» بگنجانید.

• پارامترهای سفارشی با حوزه کاربر را می‌توان در 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_