How to Use the Measurement Protocol
How to Use the Measurement Protocol
A measurement protocol is a set of rules which an app must follow in order to send raw hit data directly to a GA server. Read on to learn how to use it!
Join the DZone community and get the full member experience.Join For Free
Bugsnag monitors application stability, so you can make data-driven decisions on whether you should be building new features, or fixing bugs. Learn more.
A measurement protocol is a set of rules which the application must follow in order to send raw hit data directly to a GA server.
What Is a 'Measurement Protocol Request'?
In order to make an HTTP request to the GA server (for sending in the raw hit data directly), the HTTP request needs to be formatted according to the measurement protocol. The formatted HTTP request is called the measurement protocol request.
The protocol request is made up of user agent, transport, and the payload data.
User agent is a string that the web browser sends to the web server in order to identify itself. The user agent can be seen in an HTTP request.
Payload data is the data sent to the GA server using the measurement protocol. In other words, payload data is the data which has been formatted according to the measurement protocol. The payload data resembles a URL query string. The payload data is made up of multiple parameters. Each parameter is made up of a key-value pair.
Types of Payloads
There are basically two types of payloads:
- Single hit payload: The payload data in which only one hit is sent to the GA server.
- Multiple hits payload: The payload data in which multiple hits are sent to the GA server.
Transport defines where and how to send payload data.
A transport is made up of:
- GET/POST method: which defines how to send payload data.
- Location of the GA server: which defines where to send the payload data.
- URL endpoint: This is used to define whether a single hit or multiple hits should be sent to the GA server or whether to send the payload data to the measurement protocol validation server.
Measurement Protocol Rules
- Formatting the protocol request.
- Length and format of the payload data.
- Length and format of each parameter.
- Parameters that can be sent together and which can't be sent together.
- Parameters which are required for particular hit type.
- Parameters which can be sent for a particular hit type.
- Allowed key-value pairs.
- Valid keys.
- Valid hit types.
- Length and format of each value.
- Supported data types.
- The format of transport.
How to Use Measurement Protocol
- An application program that can pull data from the desired external source (like the point of purchase system, etc.)
- The application must convert the retrieved data into the payload data according to the measurement protocol.
- The application must make an HTTP GET/POST request to the endpoint (Google Analytics server) in order to send the payload data to the GA server. The HTTP request should be made of user agent, transport, and the payload data.
If Google analytics successfully processes the payload data then its server will send 2xx response code back to your application.
If GA is not successful in processing the payload data, then its server does not send any error codes back to your application.
Measurement Protocol Usage Policy
According to the measurement protocol usage policy set by Google, you should measurement protocol only when:
- You have the permission to use it, from the rightful owners.
- You are not going to collect any Personally Identifiable Information (PII) or any data that can help in identifying a particular user by his/her device.
- You have given your end users proper notice about the data you are collecting via the measurement protocol and how you will use the data, as well as the option to opt out from being tracked.
Measurement Protocol Supported Data Types
1. Integer - Used to represent a number.
2. Text - Used to represent a string.
3. Boolean - Used to represent a boolean value (true or false).
4. Currency - Used to represent the total value if a currency in up to 6 decimal points.
Required Parameters for Payload Data
- Measurement protocol version (v): is used to denote the measurement protocol version.
- Tracking ID (tid): tid is used to denote the tracking ID.
- Client ID (cid): cid is used to denote the client ID (this is unique to a particular device, or browser and unique to a particular visitor/user).
- Hit type (t): Used to denote the hit type. The value of this parameter can be one of the following: 'pageview', 'event'.
Sending Payload Data via the POST Method
Google recommends using the POST method, as larger payload data can be sent to the GA server. The location of the GA server is https://www.google-analytics.com. This is where we send the payload data. The payload data has to be URL encoded if a POST request is made to the GA server. The size of the payload data if an HTTP POST request is made can be a maximum of 8191 bytes. However, if an HTTP GET request is made then the size of the payload data cannot be more than 2000 bytes.
Write your application to make the following similar HTTP POST request to the GA server in order to send the physical data.
Sending Payload Data via the GET Method
If the data cannot be sent through a POST request, then the application can use a GET request to send the data to the GA server, in order to send the payload data:GET /collect?payoad_data HTTP/1.1
How to Prevent HTTP GET Requests From Being Cached
Another downside (the first downside is the inability to send a large set of payload data) of making an HTTP request to the GA server is that GET requests may be cached and, when cached, the request is no longer unique and subsequent requests are retrieved from the cache and not sent to Google Analytics.
To prevent HTTP requests from getting cached, we need to add the parameter, "Z," at the end of the payload data. We can assign any random number to this parameter. Here is an example.GET /collect?[payload_data&z=12345] HTTP/1.1
If a GET request is made to the GA server then the payload data needs to be in the form of URI escaped query parameters.
Sending a Single Hit in a Measurement Protocol Request
In order to send a single hit to GA via the measurement protocol, use the /collect URL end point in your transport.
The '/collect' URL endpoint is used to send a single hit in your HTTP request.
Send Multiple Hits in a Single Measurement Protocol Request
Use the '/batch' endpoint to send multiple hits in a single HTTP request.
- When sending multiple hits in a single HTTP request then specify each payload on its own line.
- The HTTP request which contains the /batch endpoint is called the Batch Request. A maximum of 20 hits at a time can be sent per batch request.
- The total size of the payload data in a batch request cannot be greater than 16 kilobytes.
Published at DZone with permission of Soumyajit Basu , DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.