Measurement protocol is a set of rules which your application must follow in order to send raw hit data directly to Google Analytics server.

Measurement protocol is used and beneficial for implementing cross device tracking.

Through this protocol you can collect and send raw user interaction data (hits) directly to GA server from any device/system which can be connected to the internet. This device/system can be a smart phone, tablet PC, digital appliances (washing machine, coffee machine, slot machine), point of purchase systems etc.

However, you need to format your data according to the measurement protocol before you can send it to the Google Analytics server. So for example, if you want to send data from your washing machine to the Google Analytics server, then you first need to format the data according to the measurement protocol.

Similarly, if you want to send data from a cash counter machine, coffee machine or slot machine then you first need to format the data according to the measurement protocol. Without such formatting, you can’t send data to GA.

Through measurement protocol you can measure offline conversions in GA. Thus it helps in understanding the offline behaviour of the customers and help in fixing attribution modelling issues.

Note: You don’t need measurement protocol, if you just want to send hit data from a website or mobile app. Use the Google Analytics tracking code for website/mobile app for that purpose.

You can collect and send only hit data (pageviews, screenviews, events, transactions etc) via the measurement protocol. You can’t collect and send data in aggregated form (like tables) via measurement protocol.

 

Introduction to HTTP Requests and Responses

In order to understand the measurement protocol request, you first need to understand HTTP Requests and HTTP Responses.

All web browsers and web servers communicate with each other by sending HTTP requests and HTTP responses.

A web browser communicate with a web server by sending HTTP request for each requested resource (like html document, image, css etc).

The web server communicates back to the web browser by sending HTTP response for each HTTP request.

Here is how HTTP request looks like:

 Here is how HTTP response looks like:

To see HTTP requests and responses, follow the steps below:

Step-1: Open Google Chrome browser.

Step-2: Navigate to a web page.

Step-3: Right click on the page and then click on ‘Inspect’ from the drop down menu. This will open up the ‘Chrome Developers Tool’.

Step-4: Click on the ‘Network’ tab:

On the right hand side of the developers’ window, you can see all the HTTP request and response headers.

 

Measurement Protocol Request

In order to make an HTTP request to the GA server (for sending the raw hit data directly), you need to format your HTTP request according to the measurement protocol.

This formatted HTTP request is called the measurement protocol request.

Here is how the measurement protocol request looks like:

The measurement protocol request is made up of: user agent, transport and payload data:

To see the measurement protocol request, follow the steps below:

Step-1: Open Google Chrome browser.

Step-2: Navigate to the web page which has Google Analytics tracking code installed.

Step-3: Right click on the page and then click on ‘Inspect’ from the drop down menu. This will open up the ‘Chrome Developers Tool’.

Step-4: Click on the ‘Network‘ tab:

Step-5: To see the measurement protocol request, type ‘collect’ in the text box (shown below) and then press the enter key.

On the right hand side of the developers’ window, you can see the measurement protocol request:

 

Introduction to User Agent

User agent is a string that your web browser send to a web server, in order to identify itself.

Following is an example of User Agent:

Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/48.0.2564.116 Safari/537.36

You can see the user agent in a HTTP Request:

 

Introduction to Payload Data

Payload data is the data you send to Google Analytics server using the measurement protocol.

In other words, the payload data is the data which has been formatted according to Measurement Protocol.

Following is an example of payload data:

v=1&tid=UA-123456-2&cid=36009a59-2a05-49e7-b826-2b884d0f935b&t=pageview&dp=%2Fhome

The payload data resembles a URL query string (query string is the part of the URL which comes after the ‘?’ Character).

Payload data is made up of multiple parameters. Each parameter is made up of ‘key = value’ pairs.

 

Types of Payloads

There are two types of payloads:

#1 Single hit payload – the payload data in which only one hit is sent to the GA server.

#2 Multiple hits payload – the payload data in which multiple hits are sent to the GA server.

Note: The size of single hit payload cannot be greater than 8k bytes.

 

Introduction to Transport

Transport defines where and how to send the payload data. Following is an example of transport:

POST http://www.google-analytics.com/collect

A transport is made up of:

#1 GET/POST method – which defines how to send the payload data

#2 Location of the GA server – which defines where to send the payload data

#3 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 measurement protocol validation server.

 

Measurement protocol rules

Measurement protocol rules are the rules regarding:

• Formatting the protocol requests
• Length and format of the payload data
• Length and format of each parameter
• Parameters which 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 and value pairs
• Valid keys
• Valid hit types
• Length and format of each value
• Supported data types
• Format of transport

 

How to use measurement protocol?

To use the measurement protocol, you need to do following three things:

#1 Ask your developer to write an application (program) that can pull data from your desired external data source (like point of purchase system etc):

#2 Your application must convert the retrieved data into the payload data according to the measurement protocol:

#3 Your application must make a HTTP POST/GET request to the end point (Google Analytics server) in order to send the payload data to the GA server. The HTTP request should be made up of user agent, transport and payload data:

When GA receives the HTTP request from your application, it try to process the payload data in the HTTP request.

If GA 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 illustrate the whole process of creating a measurement protocol hit:

 

Measurement Protocol Usage Policy

According to measurement protocol usage policy set by Google, you should use measurement protocol only when:

#1 You have the permission to use it, from the rightful owners.

#2 You are not going to collect any personally identifiable information (names, email addresses) or any data that can help in identifying a particular user by his/her device.

#3 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 Parameters

Payload data is made up of multiple parameters.

Each parameter is separated from another parameter via & character.

Since each parameter is made up of ‘key = value‘ pairs, so each ‘key=value’ pair is separated by ‘&’ character.

Syntax of payload data:

parameter1&parameter2&parameter3

or

key1=value1&key2=value2&key3=value3

 

Example of payload data:

v=1&tid=UA-123456-2&cid=36009a59-2a05-49e7-b826-2b884d0f935b&t=pageview&dp=%2Fhome

Here v, tid, cid, t and dp are called the keys.

‘1’, ‘UA-123456-2’, ‘36009a59-2a05-49e7-b826-2b884d0f935b’, ‘pageview’ and ‘%2Fhome’ are called the values.

All values you sent via measurement protocol to GA, must be both UTF-8 encoded and URL encoded.

For example, / is encoded to %2F

If the values are not encoded correctly then they will be replaced with unicode replacement character xFFFD

Note (1): You can learn more about URL encoding from here: http://www.w3schools.com/tags/ref_urlencode.asp

Note (2): All protocol parameters must be set on the same line. They should not have any spaces between them. Comments are not allowed in protocol parameters.

 

Measurement Protocol supported data types

The measurement protocol supports following data types for the values in the ‘key = value’ pairs of the payload data:

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 of a currency in up to 6 decimal points.

 

Required parameters for Payload data

Each payload data must contain following parameters:

#1 Measurement Protocol Version

‘v’ is used to denote the measurement protocol version.

The value of this parameter should be 1.

For example: v=1 as in:

v=1&tid=UA-123456-2&cid=36009a59-2a05-49e7-b826-2b884d0f935b&t=pageview&dp=%2Fhome

 

#2 Tracking ID

‘tid’ is used to denote the tracking ID.

The value of this parameter should be the property ID of your Google Analytics property, where you want to send the payload data.

For example: tid=UA-123456-2 as in:

v=1&tid=UA-123456-2&cid=36009a59-2a05-49e7-b826-2b884d0f935b&t=pageview&dp=%2Fhome

 

#3 Client ID

‘cid’ is used to denote the client ID (ID which anonymously identifies a particular device, or browser and is unique to a particular visitor/user).

For example: cid = 36009a59-2a05-49e7-b826-2b884d0f935b as in:

v=1&tid=UA-123456-2&cid=36009a59-2a05-49e7-b826-2b884d0f935b&t=pageview&dp=%2Fhome

 

#4 Hit Type

‘t’ is used to denote the hit type.

The value of this parameter can be be anyone of the following: ‘pageview’, ‘event’, ‘social’, ‘transaction’, ‘item’, ‘exception’,’appview’ or ‘timing’.

For example: t= pageview as in:

v=1&tid=UA-123456-2&cid=36009a59-2a05-49e7-b826-2b884d0f935b&t=pageview&dp=%2Fhome

 

Rules for using protocol parameters

There are rules regarding which parameters can be sent together and which parameters can’t be sent together. There are rules regarding the length and format of parameters.

Each parameter has specific type that requires a particular format.

Each payload data must contain a valid hit type. Each hit type must have its own set of required parameters set.

For more details, regarding these rules, refer to:

Measurement Protocol Parameter Reference: https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters?hl=en

 

List of Parameters which are commonly used in payload data

	Parameter	Description	Value	Example
1	dr	Document Referrer. It is the referral source which sent traffic to your website.	The value of this parameter should be a URL (URL encoded)	dr=http%3A%2F%2Fabc.com All values of the parameters must be URL encoded before they are sent to the Google Analytics server. For this reason the URL https://abc.com was first encoded to http%3A%2F%2Fabc.com before it is passed as a value to the ‘dr’ parameter.
2	cn	campaign name	The value of this parameter should be a URL encoded text string.	cn=attribution
3	cs	campaign source	URL encoded text string.	cs=%28direct%29 Here the campaign source is ‘(direct)’. But when the text string is URL encoded the opening parenthesis ‘(‘ is replaced by ‘%28’ and the closing parenthesis is replaced by ‘%29’
4	cm	campaign medium	URL encoded text string.	cm=organic
5	ck	campaign keyword	URL encoded text string	ck=event%20education
6	cc	campaign content	URL encoded text string	cc=top%20left
7	dl	document location, the full URL of the page which contains the contents.	URL (URL encoded)	dl=http%3A%2F%2Fexample.com%2Fhangers%3Fprod%3D231 Here the original value (before URL encoding) was: https://example.com/hangers?prod=231
8	dh	document hostname, the host where the contents are hosted.	Hostname	dh=example.com
9	dp	document path	The value of this parameter should begin with /	dp=%2Fhangers%3Fprod%3D231 Here the original value (before URL encoding) was: /hangers?prod=231
10	dt	document title	URL encoded text string	dt=event%20education%20courses Here the original value (before URL encoding) was: event education courses
11	ec	Event category	URL encoded text string	ec=videos
12	ea	Event Action	URL encoded text string	ea=play
13	el	Event Label	URL encoded text string	el=spider%20man
14	ev	Event Value	Integer value	ev=100
15	ti	e-commerce transaction ID	URL encoded text string	ti=4567DT

Note (1): All text values have size limit which is expressed in bytes.

Note (2): You can get complete list of all of the measurement protocols form here: https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters

 

Sending Payload data via POST method

You can send payload data by either using the GET method or POST method.

Google recommends using POST method, as then you can send larger payload data to 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 need to be URL encoded if you are making HTTP POST request to the GA server.

The size of Payload data, if you are making HTTP POST request to the GA server can be maximum of 8191 Bytes.

However, if you make HTTP GET request to the GA server, then the size of 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 payload data:

User-Agent: user_agent_string

POST https://www.google-analytics.com/collect?payload_data

 

Sending Payload data via GET method

If you can’t send payload data via HTTP POST request then write your application to make the following similar HTTP GET requests to the GA server, in order to send the payload data:

GET /collect?payload_data HTTP/1.1

Host: https://www.google-analytics.com

User-Agent: user_agent_string

 

How to prevent HTTP GET requests from being cached?

Another downside (the first downside is the inability to send large payload data) of making an HTTP GET request to the GA server is that, GET request may get cached and when it get cached, the request is no longer unique and hence subsequent requests are retrieved from the cache and not sent to GA.

To prevent HTTP GET requests from being cached, add the parameter called ‘Z’ at the end of the payload data.

Assign a random number to this parameter.

For example:

GET /collect?[payload_data&z=12345] HTTP/1.1

Host: https://www.google-analytics.com

User-Agent: user_agent_string

For example:

https://www.google-analytics.com/collect?v=1&t=pageview&tid=UA-1029844-34&
cid=c461d1ba-d341-499f-bc9e-673b67f2aa18&dh=mydemo.com&
dp=%2Fhome&dt=testing%20page1111111%20tracking&z=12345

Note: If you are making HTTP GET request 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 Google Analytics server via the measurement protocol, use the ‘/collect’ URL endpoint in your transport:

The ‘/collect’ URL endpoint is used to send a single hit in your HTTP request. For example:

User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/30.0.1599.69 Safari/537.36

POST https://www.google-analytics.com/collect?v=1&t=pageview&tid=UA-1500844-34&
cid=d0abe39e-ba31-4d6a-a70e-65e8345a4bce

 

Sending multiple hits in a single measurement protocol request

Use the ‘/batch’ endpoint to send multiple hits in a single HTTP request.

For example:

User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/30.0.1599.69 Safari/537.36

POST https://www.google-analytics.com/batch?

v=1&t=event&tid=UA-1500844-18&cid=98880ed4-c224-4b3c-b2e2-35a491373751&ec=videos-1&ea=play&el=spider%2520man1&ev=100

v=1&t=event&tid=UA-1500844-18&cid=98880ed4-c224-4b3c-b2e2-35a491373751&ec=videos-2&ea=play&el=spider%2520man2&ev=100

v=1&t=event&tid=UA-1500844-18&cid=98880ed4-c224-4b3c-b2e2-35a491373751&ec=videos-3&ea=play&el=spider%2520man3&ev=100

Note (1): when you are sending multiple hits in a single HTTP request then specify each payload on its own line.

Note (2): The HTTP request which contains /batch end point is called the Batch request. You can send maximum of 20 hits at a time per batch request.

Note (3): The total size of the payload data in a batch request cannot be greater than 16k bytes.

 

Sending hit to measurement protocol validation server

You can validate protocol hits by sending them to the measurement protocol validation server.

To learn more, read this article: Understanding measurement protocol validation server

 

Validating measurement protocol hits

You can use validate measurement protocol hits via:

#1 Chrome developer tool – You can use the ‘console’ or ‘network’ tab of the chrome developer tool, to see the details of the measurement protocol hits, as explained earlier.

#2 Measurement protocol hit builder – Through hit builder you can create and validate protocol hits. To learn more, read this article: Using Google Analytics Measurement Protocol Hit Builder

Note: GA hit builder use only one URL end point, /collect

#3 Postman chrome extension – Through this extension, you can send payload data via GET or POST method. The GA hit builder allows you to send payload data only via POST method. Through postman extension you can also:

# test sending payload data over secure connection.

# send payload data by using a different URL end point (/debug/collect or /batch)

For more details, read this article: Creating and validating measurement protocol requests through postman

 

Sending different types of data via measurement protocol

1. Sending pageview data via measurement protocol in Google Analytics
2. Sending campaign data via measurement protocol in Google Analytics
3. Sending event data via measurement protocol in Google Analytics
4. Sending ecommerce data via measurement protocol in Google Analytics
5. Sending social interactions via measurement protocol in Google Analytics