مرجع پروتکل اندازه گیری

این صفحه مکانیسم انتقال و پارامترهای داده برای پروتکل اندازه‌گیری را شرح می‌دهد.

حمل و نقل

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

پروتکل اندازه‌گیری در صورت دریافت درخواست HTTP یک کد وضعیت 2xx برمی‌گرداند. در صورت ناقص بودن payload، یا نادرست بودن داده‌ها یا عدم پردازش آنها توسط گوگل آنالیتیکس، پروتکل اندازه‌گیری کد خطایی برنمی‌گرداند.

بار مفید

محموله دارای دو بخش است:

  1. پارامترهای پرس و جو.
  2. یک بدنه‌ی JSON POST .

پارامترهای پرس و جو

نام پارامتر توضیحات

api_secret

 الزامی . راز API از رابط کاربری گوگل آنالیتیکس.

در مسیر Admin > Data Streams > Choose your stream > Measurement Protocol > Create یافت می‌شود.

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

بدنه پست JSON

کلید نوع توضیحات

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 که گوگل آنالیتیکس برای استخراج اطلاعات جغرافیایی درخواست استفاده می‌کند.

device

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

validation_behavior

 string

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

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

events[]

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

events[].name

 string الزامی . نام رویداد. برای مشاهده‌ی همه گزینه‌ها به بخش رویدادها مراجعه کنید.

events[].params

 object اختیاری . پارامترهای رویداد. برای پارامترهای پیشنهادی برای هر رویداد به بخش رویدادها و برای پارامترهای رایج رویداد به بخش پارامترهای رویداد مراجعه کنید.

پارامترهای رویداد مشترک

پروتکل اندازه‌گیری دارای پارامترهای رویداد مشترک زیر است:

کلید نوع توضیحات

session_id

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

engagement_time_msec

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

timestamp_micros

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

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

کلید نوع توضیحات

ad_user_data

 string

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

یا 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 نیز تنظیم کنید تا گوگل آنالیتیکس بتواند نام شهر را به درستی به یک city ID نگاشت کند.

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 ارسال کنید، گوگل آنالیتیکس اطلاعات جغرافیایی را از آدرس IP استخراج می‌کند. اگر user_location ارسال کنید، گوگل آنالیتیکس ip_override نادیده می‌گیرد.

اگر user_location یا ip_override ارسال نکنید، گوگل آنالیتیکس اطلاعات جغرافیایی را از برچسب‌گذاری رویدادها با استفاده ازclient_id .

گوگل آنالیتیکس صرف نظر از اطلاعات جغرافیایی ارسالی، تنظیمات جزئی داده‌های مکانی ملک را برای درخواست اعمال می‌کند.

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

برای ارسال اطلاعات دستگاه، از فیلد 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"
}

صرف نظر از اینکه شما مشخص کنید یا نهگوگل آنالیتیکس تنظیمات جزئی داده‌های دستگاه مربوط به ملک را برای درخواست اعمال می‌کند.

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

ویژگی validation_behavior نحوه اعتبارسنجی محتوای درخواست توسط پروتکل اندازه‌گیری را کنترل می‌کند.

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

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

  • هنگام اعتبارسنجی رویدادها از ENFORCE_RECOMMENDATIONS استفاده کنید تا تا حد امکان در مورد مشکلات احتمالی درخواست‌هایتان بازخورد دریافت کنید.

    همچنین می‌توانید درخواست‌ها را با استفاده از Event Builder اعتبارسنجی کنید، زیرا هنگام اعتبارسنجی درخواست‌ها، ENFORCE_RECOMMENDATIONS را مشخص می‌کند.

  • هنگام ارسال رویدادها برای به حداقل رساندن داده‌های رد شده توسط پروتکل اندازه‌گیری، validation_behavior مشخص نکنید.

    اگر می‌خواهید هنگام ارسال یک درخواست خاص، اعتبارسنجی دقیق را بر جمع‌آوری داده‌ها اولویت دهید، فیلد 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 فقط برای استریم‌های App مجاز هستند.

نام پارامترهای رزرو شده

نام پارامترهای زیر رزرو شده هستند و نمی‌توان از آنها استفاده کرد:

  • 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_