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

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

حمل و نقل

همه داده ها باید با استفاده از درخواست های 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 را برمی گرداند. اگر بارگذاری ناقص باشد، یا اگر داده‌ها نادرست باشند یا توسط Google Analytics پردازش نشده باشند، پروتکل اندازه‌گیری کد خطایی را بر نمی‌گرداند.

بار

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

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

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

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

api_secret

 مورد نیاز . راز API از رابط کاربری Google Analytics.

در زیر Admin > Data Streams > Choose Stream > Measurement Protocol > Create یافت می شود.

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

بدنه JSON POST

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

user_id

 string

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

timestamp_micros

 number

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

user_properties

 object اختیاری ویژگی های کاربر برای اندازه گیری

user_data

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

non_personalized_ads

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

user_location

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

ip_override

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

device

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

events[]

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

events[].name

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

events[].params

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

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

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

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

session_id

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

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 آلفا-2 . به عنوان مثال، US ، AU ، ES ، FR .

subcontinent_id

 string اختیاری شبه قاره در قالب سازمان ملل متحد M49 . به عنوان مثال، 011 ، 021 ، 030 ، 039 .

continent_id

 string اختیاری قاره در قالب 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 اطلاعات جغرافیایی را از برچسب‌گذاری رویدادها با استفاده از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"
}

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

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

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

  • پارامترهای سفارشی با محدوده کاربر را می توان در 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

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

نام پارامترهای زیر رزرو شده است و قابل استفاده نیست:

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