Nền tảng Measurement Protocol của Google Analytics chỉ hỗ trợ các yêu cầu HTTP POST.
Để gửi một sự kiện, hãy sử dụng định dạng sau:
POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA
Bạn phải cung cấp những thông tin sau trong URL yêu cầu:
api_secret: MÃ THÔNG BÁO BÍ MẬT CHO API được tạo trong giao diện người dùng Google Analytics.
Để tạo một khoá bí mật mới, hãy chuyển đến mục Quản trị > Thu thập và sửa đổi dữ liệu > Luồng dữ liệu > chọn luồng của bạn > Khoá bí mật API Measurement Protocol > Tạo.
measurement_id: Mã đo lường được liên kết với một luồng, có trong giao diện người dùng Google Analytics ở mục Quản trị > Luồng dữ liệu > chọn luồng của bạn > Mã đo lường.
measurement_id không phải là Mã luồng của bạn.
Bạn phải cung cấp nội dung yêu cầu ở định dạng nội dung POST JSON cho Giao thức đo lường. Ví dụ:
Mặc dù session_start là một tên sự kiện được dành riêng, việc tạo session_id mới sẽ tạo ra một phiên mới mà không cần gửi session_start. Tìm hiểu cách tính số phiên.
Dùng thử
Dưới đây là ví dụ bạn có thể dùng để gửi nhiều sự kiện cùng một lúc. Ví dụ này gửi sự kiện tutorial_begin và sự kiện join_group đến máy chủ Google Analytics của bạn, bao gồm thông tin địa lý bằng cách sử dụng trường user_location và bao gồm thông tin thiết bị bằng cách sử dụng trường device.
Measurement Protocol sử dụng dấu thời gian đầu tiên mà giao thức này tìm thấy trong danh sách sau cho mỗi sự kiện trong yêu cầu:
timestamp_micros của sự kiện.
timestamp_micros của yêu cầu.
Thời gian Measurement Protocol nhận được yêu cầu.
Ví dụ sau đây sẽ gửi dấu thời gian ở cấp yêu cầu áp dụng cho tất cả các sự kiện trong yêu cầu. Do đó, Measurement Protocol sẽ chỉ định cho cả sự kiện tutorial_begin và join_group dấu thời gian requestUnixEpochTimeInMicros.
Ví dụ sau đây sẽ gửi cả dấu thời gian ở cấp yêu cầu và dấu thời gian ở cấp sự kiện. Do đó, Measurement Protocol sẽ chỉ định dấu thời gian tutorialBeginUnixEpochTimeInMicros cho sự kiện tutorial_begin và dấu thời gian requestUnixEpochTimeInMicros cho sự kiện join_group.
Các giới hạn sau đây áp dụng cho việc gửi sự kiện Measurement Protocol đến Google Analytics:
Các yêu cầu có thể có tối đa 25 sự kiện.
Sự kiện có thể có tối đa 25 thông số.
Sự kiện có thể có tối đa 25 thuộc tính người dùng.
Tên thuộc tính người dùng chỉ được có tối đa 24 ký tự.
Giá trị thuộc tính người dùng chỉ được có tối đa 36 ký tự.
Tên sự kiện chỉ được có tối đa 40 ký tự, chỉ được chứa các ký tự chữ và số, dấu gạch dưới và phải bắt đầu bằng một ký tự chữ cái.
Tên thông số (bao gồm cả thông số mục) chỉ được có tối đa 40 ký tự, chỉ được chứa ký tự chữ và số, dấu gạch dưới và phải bắt đầu bằng một ký tự chữ cái.
Giá trị tham số (kể cả giá trị tham số của mặt hàng) chỉ được có tối đa 100 ký tự đối với tài sản Google Analytics chuẩn và tối đa 500 ký tự đối với tài sản Google Analytics 360.
Thông số mặt hàng có thể có tối đa 10 thông số tuỳ chỉnh.
Nội dung bài đăng phải nhỏ hơn 130 kB.
Các sự kiện Measurement Protocol của ứng dụng được gửi đến Google Analytics không điền sẵn đối tượng Tìm kiếm trong Google Ads cho người dùng ứng dụng.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-09-06 UTC."],[[["\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)."]]
