How to Implement Media Tracking in Intelligence
Media Tracking helps to analyze your visitor's interactions with media files. Each media session offers various insights into user behaviors. These include retrievals, actions such as play, pause, or stop (depending on the integrated medium), play time, bandwidth, volume, and mute. Our Media Tracking API works with various of our tracking products, e.g.:
- Web
- Mobile
- AMP
To successfully track user behavior on your media streams, it is important to use the API correctly. This documentation explains the various parameters needed for media tracking and the logic of our API.
Please note that a media session can handle up to 100,000 requests per session.
Media Tracking Parameters
Mandatory GET parameter for media requests
The following parameters need to be sent in every media request:
| Parameter | Description | Where to Configure | Where to Analyse | Default value | Example |
|---|---|---|---|---|---|
| mi | Media name. Name of the video as displayed in your analyses. | - | Navigation > Media > Media | --- | de. video |
| mk | Media action. The current action of the Media Player. The actions are our standard values, but it is possible to add custom actions as well.
| - | Navigation > Media > Media Player Actions | --- | play |
| mt1 | Current position of the video. Entered as a whole number, in terms of seconds. | - | Navigation > Media > Media Run Time | 0 | |
| mt2 | Total Play Duration of the video. Entered as a whole number, in terms of seconds. Is used to calculate the media run time. | - | - | 0 |
Optional GET parameter for media requests
The following parameters can be added to requests as needed:
| Parameter | Description / Note | Where to Configure | Where to Analyze | Default value | Example |
|---|---|---|---|---|---|
| mg<<1 - 499>> | Custom media categories. The media categories must be created in your Mapp Intelligence account. The IDs as given in the account need to be added to the mg prefix. The parameter "mg1" sends the value for the Media Category 1, "mg2" for Media Category 2, etc. | Mapp Q3 > Configuration > Categories > Media Categories | Datatype Text: Navigation > Media Categories > [Name of media category] Datatype Figure: metric | --- | en |
| mut | Mute. "1" means mute is active (volume off), "0" for volume on. Only the last value sent in a Media session is saved and displayed in Intelligence analysis. It is not possible to analyze switching between mute and unmute in one session. | - | Navigation > Media > Media Player Mute | 0 | 1 |
| vol | Values between 0 and 255 are accepted. It is recommended to use 0 to 100 to analyze the volume in terms of percent in the tool. The spectrum from 0 to 255 is accepted here due to compatibility reasons. Only the last value sent in a Media session is saved and displayed in Intelligence analyses. It is not possible to analyze switching between volumes in one session. | - | Navigation > Media > Media Player Volume | 0 | 100 |
| bw | Bandwidth in bits/second. Entered as a whole number. Only the last value sent in a Media session is saved and displayed in Intelligence analyses. It is not possible to analyze switching between bandwidths in one session. | - | Navigation > Media > Media Bandwidth | 0 | 64000 |
Starting a Media Session
To analyze a media session in Intelligence, you need to initialize a media session in the first request.
Please note that media sessions are independent of normal website visits.
The following values can be used to initialize the media session:
- mk = init: init only initializes the session, no other action is tracked at this point.
- mk = play: play initializes the session with "play" as the first action.
It is very important to forward the total play duration of the video in the first request. Otherwise, the total length is set to 0 for the entire video in that session, which will affect the media runtime (see also why is the media run time 0 and media run time).
In the case of a Livestream, use the value 0 as the total play duration.
Tracking Media Chapters
A request with the media action "pos" should be sent at an interval of 30 seconds while the video is in play mode. This tracks the viewed chapters and the last position of the video, in case the user ends the video by closing the app, window, or tab. The parameter and value mark a position request:
- mk = pos
Please note:
- Media with a specified total play duration can send the media player action "pos" up to 60 times during one media session and must have at least 10 seconds in between requests.
- If a live stream is tracked, the position can be sent every 60 seconds.
Tracking Seek Actions
When the user seeks through the media, the following action needs to be sent:
- mk = seek
You must send a pause or play request with the current media position once the user completes a seek action. Each seek action must be followed by either a play or pause action, depending on the state the media was in before the user started to seek. The current position of the media needs to be adjusted accordingly in the preceding play or pause action request.
Stopping the Media
Stopping the media results in a restart. Therefore, set the current position of the media (mt1) back to 0 when the user stops the media.
Ending the Media Session
When a user leaves the video, the media session needs to end. The following parameter and value are used for this:
- mk = eof
Ending the session is necessary to analyze the session duration correctly. It must be sent when the end of the media file is reached. Hence, the current position of the media must be identical to the total length of the media in an end-of-session request.
Implementation
Find more information here