پلتفرمی را که می خواهید در این راهنما ببینید انتخاب کنید:
فرمت درخواست
پروتکل اندازه گیری Google Analytics فقط از درخواست های HTTP POST پشتیبانی می کند.
برای ارسال رویداد از فرمت زیر استفاده کنید:
POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA
شما باید موارد زیر را در URL درخواست ارائه دهید:
api_secret : API SECRET ایجاد شده در رابط کاربری Google Analytics.
برای ایجاد راز جدید، به Admin > Data collection and modification > Data streams > جریان خود را انتخاب کنید > Measurement Protocol API Secrets > Create را انتخاب کنید.
measurement_id : شناسه اندازه‌گیری مرتبط با یک جریان، که در رابط کاربری Google Analytics در زیر Admin > Data Streams > جریان خود را انتخاب کنید > Measurement ID یافت می‌شود.
measurement_idشناسه جریان شما نیست.
شما باید بدنه درخواستی را در قالب بدنه JSON POST برای پروتکل اندازه گیری ارائه دهید. در اینجا یک مثال است:
در حالی که session_start یک نام رویداد رزرو شده است، ایجاد یک session_id جدید یک جلسه جدید بدون نیاز به ارسال session_start ایجاد می کند. نحوه شمارش جلسات را درک کنید.
آن را امتحان کنید
در اینجا مثالی وجود دارد که می توانید از آن برای ارسال چندین رویداد به طور همزمان استفاده کنید. این مثال یک رویداد tutorial_begin و یک رویداد join_group را به سرور Google Analytics شما ارسال می‌کند، شامل اطلاعات جغرافیایی با استفاده از قسمت user_location و شامل اطلاعات دستگاه با استفاده از فیلد device است.
پروتکل اندازه گیری از اولین مهر زمانی که در لیست زیر پیدا می کند برای هر رویداد در درخواست استفاده می کند:
timestamp_micros رویداد.
timestamp_micros درخواست.
زمانی که پروتکل اندازه گیری درخواست را دریافت می کند.
مثال زیر یک مهر زمانی در سطح درخواست ارسال می کند که برای همه رویدادهای درخواست اعمال می شود. در نتیجه، پروتکل اندازه گیری به هر دو رویداد tutorial_begin و join_group یک مهر زمانی از requestUnixEpochTimeInMicros اختصاص می دهد.
مثال زیر هم یک مهر زمانی در سطح درخواست و هم مهر زمانی در سطح رویداد را ارسال می کند. در نتیجه، پروتکل اندازه‌گیری به رویداد tutorial_begin یک مهر زمانی از tutorialBeginUnixEpochTimeInMicros و رویداد join_group یک مهر زمانی از requestUnixEpochTimeInMicros اختصاص می‌دهد.
محدودیت‌های زیر برای ارسال رویدادهای پروتکل اندازه‌گیری به Google Analytics اعمال می‌شود:
درخواست ها می توانند حداکثر 25 رویداد داشته باشند.
رویدادها می توانند حداکثر 25 پارامتر داشته باشند.
رویدادها می توانند حداکثر 25 ویژگی کاربر داشته باشند.
نام ویژگی های کاربر باید 24 کاراکتر یا کمتر باشد.
مقادیر ویژگی کاربر باید 36 کاراکتر یا کمتر باشد.
نام رویدادها باید 40 نویسه یا کمتر باشد، فقط می‌توانند شامل نویسه‌های الفبای عددی و زیرخط باشند و باید با یک نویسه الفبا شروع شوند.
نام پارامترها شامل پارامترهای آیتم باید 40 کاراکتر یا کمتر باشد، فقط می‌تواند شامل نویسه‌های الفبای عددی و زیرخط باشد و باید با یک نویسه الفبایی شروع شود.
مقادیر پارامتر شامل مقادیر پارامتر آیتم باید 100 نویسه یا کمتر برای یک ویژگی استاندارد Google Analytics و 500 کاراکتر یا کمتر برای ویژگی Google Analytics 360 باشد.
پارامترهای مورد می توانند حداکثر 10 پارامتر سفارشی داشته باشند.
بدنه پست باید کوچکتر از 130 کیلوبایت باشد.
رویدادهای پروتکل اندازه‌گیری برنامه ارسال شده به Google Analytics مخاطبان جستجو در Google Ads را برای کاربران برنامه پر نمی‌کند.
تاریخ آخرین بهروزرسانی 2025-09-06 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-09-06 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eThis guide explains how to send web and app stream events to a Google Analytics server using the Measurement Protocol.\u003c/p\u003e\n"],["\u003cp\u003eYou must format the request as an HTTP POST request and include your API Secret and Measurement ID in the URL.\u003c/p\u003e\n"],["\u003cp\u003eThe request body should contain client ID, optional user ID and consent settings, timestamp, and an array of events.\u003c/p\u003e\n"],["\u003cp\u003eEvents can include parameters like \u003ccode\u003eengagement_time_msec\u003c/code\u003e and \u003ccode\u003esession_id\u003c/code\u003e to display user activity in Realtime reports.\u003c/p\u003e\n"],["\u003cp\u003eThe Measurement Protocol has limitations on the number of events, parameters, and user properties allowed in a single request.\u003c/p\u003e\n"]]],["To send events to Google Analytics, use HTTP `POST` requests to `www.google-analytics.com/mp/collect`. Include `api_secret` and `measurement_id` in the URL. The request body should include `client_id`, and optionally `user_id`, `consent`, and `timestamp_micros`. Send events as an array within the `events` key. For real-time reporting, include `engagement_time_msec` and `session_id` in the event parameters. Timestamps can be set per event or at the request level. There are limitations on request size, event, and parameter counts.\n"],null,["This guide explains how you can send\n[Google Analytics Measurement Protocol](/analytics/devguides/collection/protocol/ga4) web and app stream\n[events](/analytics/devguides/collection/protocol/ga4/reference/events) to a\nGoogle Analytics server, so that you can view Measurement Protocol events in your\n[Google Analytics reports](/analytics/devguides/reporting/data/v1/basics).\n\nChoose the platform you want to see in this guide: \nFirebase gtag.js\n\nFormat the request\n\nThe Google Analytics Measurement Protocol only supports HTTP `POST` requests.\n\nTo send an event, use the following format: \n\n POST /mp/collect HTTP/1.1\n HOST: www.google-analytics.com\n Content-Type: application/json\n\n \u003cvar translate=\"no\"\u003ePAYLOAD_DATA\u003c/var\u003e\n\n| **Tip:** If you want your data to be collected in the EU, change the `HOST` in the example to `region1.google-analytics.com`.\n\nYou must provide the following in the request URL:\n\n- `api_secret`: The **API SECRET** generated in the Google Analytics UI.\n\n To create a new secret, navigate to\n **Admin** \\\u003e **Data collection and modification** \\\u003e **Data streams** \\\u003e\n **choose your stream** \\\u003e **Measurement Protocol API secrets** \\\u003e **Create**.\n\n\u003cbr /\u003e\n\n- `measurement_id`: The measurement ID associated with a stream, found in the\n Google Analytics UI under **Admin** \\\u003e **Data Streams** \\\u003e **choose your\n stream** \\\u003e **Measurement ID**.\n\n The `measurement_id` isn't your **Stream ID**.\n\nYou must provide a request body in the [JSON POST body](/analytics/devguides/collection/protocol/ga4/reference#payload_post_body) format for\nthe Measurement Protocol. Here's an example:\n\n\u003cbr /\u003e\n\n {\n \"client_id\": \"\u003cvar translate=\"no\"\u003eCLIENT_ID\u003c/var\u003e\",\n \"events\": [\n {\n \"name\": \"login\",\n \"params\": {\n \"method\": \"Google\",\n \"session_id\": \"\u003cvar translate=\"no\"\u003eSESSION_ID\u003c/var\u003e\",\n \"engagement_time_msec\": 100\n }\n }\n ]\n }\n\nWhile `session_start` is a [reserved event\nname](/analytics/devguides/collection/protocol/ga4/reference#reserved_names),\ncreating a new `session_id` creates a new session without the need to send\n`session_start`. Understand how [sessions are\ncounted](//support.google.com/analytics/answer/9191807).\n\nTry it\n\nHere's an example you can use to send multiple events at once. This example\nsends a [`tutorial_begin`](/analytics/devguides/collection/protocol/ga4/reference/events?tech=aw_measurement_protocol#tutorial_begin) event and a\n[`join_group`](/analytics/devguides/collection/protocol/ga4/reference/events?tech=aw_measurement_protocol#join_group) event to your Google Analytics server, includes [geographic\ninformation](/analytics/devguides/collection/protocol/ga4/reference#payload_geo_info) using the `user_location` field, and includes [device information](/analytics/devguides/collection/protocol/ga4/reference#payload_device_info)\nusing the `device` field.\n\n\u003cbr /\u003e\n\n const measurementId = \"\u003cvar translate=\"no\"\u003eMEASUREMENT_ID\u003c/var\u003e\";\n const apiSecret = \"\u003cvar translate=\"no\"\u003eAPI_SECRET\u003c/var\u003e\";\n\n fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {\n method: \"POST\",\n body: JSON.stringify({\n client_id: \"\u003cvar translate=\"no\"\u003eCLIENT_ID\u003c/var\u003e\",\n events: [\n {\n name: \"tutorial_begin\",\n params: {\n \"session_id\": \"\u003cvar translate=\"no\"\u003eSESSION_ID\u003c/var\u003e\",\n \"engagement_time_msec\": 100\n }\n },\n {\n name: \"join_group\",\n params: {\n \"group_id\": \"G_12345\",\n \"session_id\": \"\u003cvar translate=\"no\"\u003eSESSION_ID\u003c/var\u003e\",\n \"engagement_time_msec\": 150\n }\n }\n ],\n user_location: {\n city: \"Mountain View\",\n region_id: \"US-CA\",\n country_id: \"US\",\n subcontinent_id: \"021\",\n continent_id: \"019\"\n },\n device: {\n category: \"mobile\",\n language: \"en\",\n screen_resolution: \"1280x2856\",\n operating_system: \"Android\",\n operating_system_version: \"14\",\n model: \"Pixel 9 Pro\",\n brand: \"Google\",\n browser: \"Chrome\",\n browser_version: \"136.0.7103.60\"\n }\n })\n });\n\nOverride timestamp\n\nThe Measurement Protocol uses the *first* timestamp it finds in the following list\nfor each event in the request:\n\n1. The `timestamp_micros` of the event.\n2. The `timestamp_micros` of the request.\n3. The time that the Measurement Protocol receives the request.\n\nThe following example sends a request-level timestamp that applies to all of the\nevents in the request. As a result, the Measurement Protocol assigns both the\n`tutorial_begin` and `join_group` events a timestamp of\n`requestUnixEpochTimeInMicros`. \n\n {\n \"timestamp_micros\": requestUnixEpochTimeInMicros,\n \"events\": [\n {\n \"name\": \"tutorial_begin\"\n },\n {\n \"name\": \"join_group\",\n \"params\": {\n \"group_id\": \"G_12345\",\n }\n }\n ]\n }\n\nThe following example sends both a request-level timestamp and an event-level\ntimestamp. As a result, the Measurement Protocol assigns the `tutorial_begin`\nevent a timestamp of `tutorialBeginUnixEpochTimeInMicros`, and the `join_group`\nevent a timestamp of `requestUnixEpochTimeInMicros`. \n\n {\n \"timestamp_micros\": requestUnixEpochTimeInMicros,\n \"events\": [\n {\n \"name\": \"tutorial_begin\",\n \"timestamp_micros\": tutorialBeginUnixEpochTimeInMicros\n },\n {\n \"name\": \"join_group\",\n \"params\": {\n \"group_id\": \"G_12345\",\n }\n }\n ]\n }\n\nLimitations\n\nThe following limitations apply to sending Measurement Protocol events to Google\nAnalytics:\n| **Note:** For information on the limitations of 360 features, see [Google Analytics\n| 360](//support.google.com/analytics/answer/11202874).\n\n- Requests can have a maximum of 25 events.\n- Events can have a maximum of 25 parameters.\n- Events can have a maximum of 25 user properties.\n- User property names must be 24 characters or fewer.\n- User property values must be 36 characters or fewer.\n- Event names must be 40 characters or fewer, can only contain alphanumeric characters and underscores, and must start with an alphabetic character.\n- Parameter names including item parameters must be 40 characters or fewer, can only contain alphanumeric characters and underscores, and must start with an alphabetic character.\n- Parameter values including item parameter values must be 100 characters or fewer for a standard Google Analytics property, and 500 characters or fewer for a Google Analytics 360 property.\n- Item parameters can have a maximum of 10 custom parameters.\n- The post body must be smaller than 130kB.\n- App Measurement Protocol events sent to Google Analytics don't populate Search audiences in Google Ads for app users.\n\nFor additional requirements of each use case, see [common use cases](/analytics/devguides/collection/protocol/ga4/use-cases)."]]
