Using the Measurement Protocol

The Measurement Protocol is an API for sending data about user interactions directly to Yandex Metrica servers via HTTP requests. It expands the capabilities offered by standard web tags, making it possible to transmit additional data about user sessions and actions.

Usage

Merging data

Add information about interactions that can't be tracked by a web tag (such as server-side data) to your Yandex Metrica tag data.

Sending server data

Pass data from the server side when client-side collection is restricted (for example, by an ad blocker).

Transmitting E-commerce data

Pass data about E-commerce events (purchases, cart actions) directly if client-side collection isn't available.

What data is passed via the API:

• Pageviews
• JavaScript events
• E-commerce events

Limitations

Creating new sessions using the opening event pageview

To create new sessions using the Measurement Protocol, send a request with the pageview interaction type. If you pass events (such as E-commerce events or JavaScript goal conversions) that can't be attributed to an existing session because they exceed the 12-hour timeout after the session ended, or because there is no session matching the transmitted ClientID, that data won't be recorded. To avoid this issue, first pass a pageview to create a new session, then add the desired events to that session.

Time limit for updating sessions

You can update sessions only within a 12-hour window after their completion. To do this, pass an event that falls within the session timeout specified in the tag settings. If you need to pass data for an older session, use offline data transmission. The only way to record data for sessions that ended more than 12 hours ago using the Measurement Protocol is by creating a new session with the desired ClientID and adding the events that you want to associate with the user to that new session.

Gradual ClientID availability for expanding user history

After you enable the Measurement Protocol feature, Yandex Metrica starts tracking the history of site users by their ClientIDs, continuously expanding it with new sessions via the Measurement Protocol. This is a gradual process: initially, the service stores ClientIDs for one day after the feature's activation, then for two days, three, and so on, until it reaches 21 days. After that, the oldest data is deleted, and the service updates ClientIDs with the most recent information for the last 21 days. If a user's session occurred more than 21 days ago, their history can't be updated further, so a new user with a new session is created instead.

Setting up data transfer

1. Activate the Measurement Protocol in the settings.

   Enable the corresponding option in the Yandex Metrica interface or API and get an access token. Learn more about managing the option and tokens via the API.

2. Save the ClientID.

   Save the ClientID to your server for future data sending.

3. Send the request.

   Send a POST or GET request with the necessary parameters and token to https://mc.yandex.ru/collect. Learn more about uploading data.