spyc.ai

Free tool

GA4 Measurement Protocol Builder

Build a GA4 Measurement Protocol request: JSON body, collect and debug URLs, and a curl command.

How it works

What is the GA4 Measurement Protocol Builder?

The GA4 Measurement Protocol Builder is a free tool that assembles a server-side request to Google Analytics 4. Enter the measurement ID, a client_id and one or more events with parameters, and it returns the JSON body, the /mp/collect endpoint, the /debug/mp/collect validation endpoint and a ready curl command, with the API secret left as a placeholder.

How to use the GA4 Measurement Protocol Builder

  1. Enter the measurement ID of your web stream and the visitor's client_id.
  2. Name each event and add its parameters, one key=value per line.
  3. Leave the API secret empty to keep the placeholder, and read any warnings.
  4. Copy the curl command, add your secret on your own machine, and run it against the validation endpoint.
  5. When validation returns no messages, switch to the collect endpoint in your server code.

What is the GA4 Measurement Protocol?

The Measurement Protocol is an HTTP API for sending events to Google Analytics 4 from a server instead of a browser. You POST a JSON body to https://www.google-analytics.com/mp/collect with two query parameters: measurement_id and api_secret.

Google describes it as a way to add to the data your tag already collects, not to replace the tag. Typical uses are offline conversions, refunds, subscription renewals and other events that happen where no browser is present.

What goes in a Measurement Protocol request?

For a web stream the body needs a client_id and an events array. Each event has a name and a params object. A user_id is optional. One request can carry up to 25 events.

Use the client_id the visitor already has (it is stored in the _ga cookie) so the server event joins the same user. Add session_id and engagement_time_msec to an event's parameters if it should appear in session-based reports and Realtime. The builder reminds you when they are missing.

Why should the API secret never be in client-side code?

Anyone who has the measurement ID and the API secret can send events to your property. Code that runs in a browser, a GTM tag or a mobile app can be read by whoever uses it, so a secret placed there is public.

Keep the secret on a server, in an environment variable, and send the request from there. The builder leaves YOUR_API_SECRET as a placeholder for that reason. You create secrets in GA4 under Admin, Data streams, your stream, Measurement Protocol API secrets, and you can revoke one there if it leaks.

How do I test a Measurement Protocol request?

Send it to the validation endpoint first: the same URL with /debug in front of /mp/collect. It records nothing and answers with a validationMessages array describing what is wrong. An empty array means the payload is well formed.

This matters because the live endpoint returns a 2xx status even when the payload is malformed, and the event is then dropped without notice. The curl command the builder writes points at the validation endpoint for that reason.

Which event names does the Measurement Protocol reject?

Names follow the usual GA4 rules: up to 40 characters, starting with a letter, with letters, digits and underscores only. On top of that the protocol reserves a list of names, including session_start, first_visit, user_engagement and app_remove, and the prefixes firebase_, ga_ and google_. The builder checks each event name against these.

To write the browser-side version of the same event, use the GA4 Event Generator. To confirm the events arrive, the BigQuery GA4 Query Library has an event count query for the BigQuery export.

Questions

Can I send past events with the Measurement Protocol?
Yes, within limits. Add timestamp_micros to the request to backdate events. Google documents a window of up to 72 hours.
Does the builder send the request for me?
No. It makes no network calls. It writes the body, the URLs and the curl command for you to run from your own machine or server.
What is the EU endpoint?
Google offers https://region1.google-analytics.com/mp/collect for collecting data within the EU. Tick the option and the builder switches both URLs.
Where do I find the client_id?
In the browser it is the last two number groups of the _ga cookie, or you can read it with gtag('get', measurementId, 'client_id', callback) and pass it to your server.
Is the GA4 Measurement Protocol Builder free?
Yes, with a free spyc.ai account. It runs entirely in your browser, so nothing you type or paste is sent to a server.

Analytics Tools

More in Analytics Tools

GA4 Event Generator

Pick a GA4 recommended or custom event, add parameters, and copy the gtag snippet and dataLayer push.

Generate event

GTM dataLayer Generator

Write dataLayer.push code for GA4 ecommerce and custom events, with the GTM variables to create.

Generate dataLayer

Consent Mode v2 Generator

Set Consent Mode v2 default states, regions and wait time, and copy the gtag default and update snippets.

Generate snippet

Ready when you are

Before your next buyer asks AI about you, ask AI about yourself

One check, four engines, about twenty seconds. We show you the answers before we ask for anything.