Validate events

AI-generated Key Takeaways

• The Measurement Protocol Validation Server helps ensure your Google Analytics 4 events are correctly formatted before deploying to production.

• The Validation Server uses a different URL endpoint (/debug/mp/collect) than the standard Measurement Protocol (/mp/collect).

• Validation responses provide detailed error messages including the field path, description, and a validation code for easier debugging.

• Events sent to the Validation Server are not processed and will not appear in your Google Analytics reports.

• The Google Analytics Event Builder offers an interactive way to construct and validate events before sending them to the server.

Choose your platform:

Firebase gtag.js

The Google Analytics Measurement Protocol does not return HTTP error codes, even if an event is malformed or missing required parameters. To verify your events are valid, you should test them against the Measurement Protocol validation server before deploying them to production. After you have validated that your events are structured properly, you should verify your implementation to make sure you're using the correct keys.

Caution: The validation server does not validate the api_secret or Carefully review those values to make sure they are correct.

You can either call the validation server directly, or use the Google Analytics Event Builder. The Google Analytics Event Builder lets you interactively construct events, and uses the Measurement Protocol validation server to validate them.

This guide describes how to send events to the Measurement Protocol for Google Analytics 4 validation server and interpret the response.

Important: Events sent to the validation server don't show up in reports.

Send events for validation

The only difference in the request for events sent to the Measurement Protocol and the Measurement Protocol validation server is the URL.

Server	URL
Measurement Protocol	/mp/collect
Measurement Protocol validation server	/debug/mp/collect

All other request fields are the same.

We recommend the following approach to validation:

• Use strict validation checks during development using either of the following options:
  • Validate requests with the Event Builder.
  • Send requests to the validation server with validation_behavior set to ENFORCE_RECOMMENDATIONS.
• In production, send requests without validation_behavior set to minimize the data rejected by the Measurement Protocol.

The following code shows an invalid event being sent to the Measurement Protocol validation server:

Tip: If you want your data to be collected in the EU, change the URL passed to the fetch method to begin with https://region1.google-analytics.com instead of https://www.google-analytics.com.

Validation response

Here's the validation server's response to the previous event:

{
  "validationMessages": [
    {
      "fieldPath": "events",
      "description": "Event at index: [0] has invalid name [_badEventName]. Names must start with an alphabetic character.",
      "validationCode": "NAME_INVALID"
    }
  ]
}

Here's the validation server's response to a request with no validation issues:

{
  "validationMessages": []
}

Response

Key	Type	Description
validationMessages	Array<ValidationMessage>	An array of validation messages.

ValidationMessage

Key	Type	Description
fieldPath	string	The path to the field that was invalid.
description	string	A description of the error.
validationCode	ValidationCode	A validation code that corresponds to the error.

ValidationCode

Value	Description
VALUE_INVALID	The value provided for a fieldPath was invalid. See limitations.
VALUE_REQUIRED	A required value for a fieldPath was not provided.
NAME_INVALID	The name provided was invalid. See limitations.
NAME_RESERVED	The name provided was one of the reserved names. See reserved names.
VALUE_OUT_OF_BOUNDS	The value provided was too large. See limitations.
EXCEEDED_MAX_ENTITIES	There were too many parameters in the request. See limitations.
NAME_DUPLICATED	The same name was provided more than once in the request.