What is ‘Measurement Protocol’?
Measurement protocol is a set of rules which the application must follow in order to send raw hit data directly to 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. Following is an example of the payload data.
The payload data resembles a URL query string. 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 an how to send payload data. Following is an example of transport.
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 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 code back to your application.
The diagram below illustrates the whole process of creating a measurement protocol hit:
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 Personal 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 present 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 I unique to a particular visitor/user).
- Hit type (t): It is used to denote the hit type. The value of this parameter can be any one of the following: ‘pageview’, ‘event’.
Sending payload data via post method
Google recommends using POST method as then 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 GET method
If the data cannot be sent through POST request then the application can use 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 large set of payload data) of making an HTTP request to the GA server is that, GET request may be cached and when it gets 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 have to 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 single hit in 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. For example
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 /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-kilo bytes.