Pipe Tracking

This document describes the different pipe collect events used on the BR Mediathek.

Event unspecific payload

The framework sends the following information for every request (including one event or a batch of events).

"client": {
    "device": {
        "screen_size": "414x736",
        "vendor": "Apple",
        "model": "x86_64",
        "language": "en-US",
        "type": "phone",
        "timezone": 60
    },
    "os": {
        "name": "iOS",
        "version": "13.1"
    },
    "app_id": "de.br.brmediathek",
    "id": "00000000-0000-0000-0000-000000000000",
    "version": "3.1.6",
    "type": "mobileapp",
    "name": "Mango"
},
"peach_schema_version": "1.0.3",
"peach_framework_version": "1.0.1-5",
"sent_timestamp": unix_timestamp,
"peach_implementation_version": "0",
"user_id": "u:000000000000000000000000",
"session_start_timestamp": unix_timestamp

Event: `recommendation_loaded`

This event is sent when the clips from a recommendation have been loaded. In our case this happens in the recommendations tab of the profile area ("Meins") and for the content sliders rendering personal and clip-based recommendations on the detail page. The items array contains all clip ids regardless of how many are initially displayed.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<recommendation_id>",
    "type": "recommendation_loaded",
    "context": {
      "items": ["<clip_id1>", "<clip_id2>", ...]
    }
  }],
  ...
}

Event: `recommendation_displayed`

This event is sent when the rendered recommendation(s) are displayed to the user and is triggered when the user paginates through the content slider oder finished scrolling. The items array contains all clip ids that are being displayed. If the user reloads the recommendations tab of the profile area ("Meins") all displayed recommendations are tracked again. items can contain multiple clip ids.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<recommendation_id>",
    "type": "recommendation_displayed",
    "context": {
      "items": ["<clip_id1>", "<clip_id2>", ...]
    }
  }],
  ...
}

Event: `recommendation_hit`

This event is sent once a clip teaser that comes from a recommendation is selected by the user. The information in the context contains the selected clip's id for the item_id key and a zero based hit_index to indicate the position of the recommended clip.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<recommendation_id>",
    "type": "recommendation_displayed",
    "context": {
      "item_id": "<clip_id>",
            "hit_index": 0
    }
  }],
  ...
}

Event: `page_view`

This event is sent a clip detail page is opened. Note: The recommendation id is sent in the context and the id is the clip id.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
        "id": "<clip_id>",
        "type": "page_view",
        "context": {
            "id": "<recommendation_id>"
        }
  }],
  ...
}

Media Events

Media events share most of their key value pairs:

The id is the clip id
The props object
- video_mode is either "normal", "pip", "fullscreen" or "cast" ("bar, "mini", "wide" and "preview" are possible values in the framework but currently not used in the iOS client)
- audio_mode is either "normal" or "muted" ("background" unused)
- start_mode is "normal", "auto_play" or "auto_continue": when a user allows autoplay this value will be auto_play, when a user allows recommendation autoplay and the countdown after a video has expired the value is "auto_continue", otherwise "normal" is used
- playback_position_s is the number of seconds elapsed for "ondemand" videos and a negative value for livestreams represents the timeshift (0.0 is live)
- previous_playback_position_s:
  - for events which interrupt the playback of an item (media_pause, media_stop and media_end) this value reflects the playback_position_s of their corresponding previous media_play event. Once an interrupting event is sent, the previous position is removed from the current player state. So all following interrupting events without any play inbetween will have a previous_playback_position_s equal to playback_position_s. Only a new media_play event will push a new previous_playback_position_s value to the player state.
  - for media_seek events the previous_playback_position_s value has a different meaning: it has nothing to do with the previous_playback_position_s of the interrupting events. It's bound to the seek event only and reflects the starting point of the seek, whereas playback_position_s reflects the destination of the seek.
- volume is a value between 0.0 and 1.0 (0.0 means audio_mode is "muted")
The metadata object
- type is always "video" ("audio", "article" and "page" unused)
- format is "ondemand" or "live" ("dvr" unused)
The context object has one key (id) with the recommendation id if the media event is associated with a clip that comes from a recommendation. Otherwise, no context object is sent.

Media Event: `media_play`

This event is sent when a clip starts playing. If the start_mode is "auto_continue" the properties object will contain the previous clip id in the previous_id property. Furthermore the recommendation_id in the context has to be set to the recommendation that provided the auto_continue clip. See common properties for media events for further information.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": {
      "video_mode": "normal",
      "audio_mode": "normal",
      "start_mode": "auto_play",
      "playback_position_s": 10.0,
      "previous_id": "<prev_clip_id>", // obligatory for start_mode: "auto_continue"; optional else
      "volume": 1
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_play",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_pause`

This event is sent when the playback pauses (user initiated or caused by buffering). The value of previous_playback_position_s reflects the playback_position_s value of the last play event.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": {
      "video_mode": "normal",
      "audio_mode": "normal",
      "start_mode": "auto_play",
      "playback_position_s": 120.0,
      "previous_playback_position_s": 100.0,
      "volume": 1
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_pause",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_stop`

This event is sent when the user leaves a detail page. The value of previous_playback_position_s reflects the playback_position_s value of the last play event.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": {
      "video_mode": "normal",
      "audio_mode": "normal",
      "start_mode": "auto_play",
      "playback_position_s": 123.4,
      "previous_playback_position_s": 100.0,
      "volume": 1
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_stop",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_seek`

This event is sent when the user seeked. The previous_playback_position_s key represents where the clip was playing when the user started seeking and playback_position_s represents where the user seeked to. The is_playing key tells us if the seek event happened while the player was playing or paused - this is important for the way the watch duration is calculated.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": {
      "video_mode": "normal",
      "audio_mode": "normal",
      "start_mode": "auto_play",
      "playback_position_s": 100.0, // the position the user seeked to
      "previous_playback_position_s": 10.0, // the starting position of the seek event.
      "is_playing": false,
      "volume": 1
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_seek",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_end`

This event is sent when the clip played until the end. The value of previous_playback_position_s reflects the playback_position_s value of the last play event.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": {
      "video_mode": "normal",
      "audio_mode": "normal",
      "start_mode": "auto_play",
      "playback_position_s": 123.4, // clip duration
      "previous_playback_position_s": 100.0,
      "volume": 1
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_end",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_like`

This event is sent when a clip is liked by the user. The property playback_position_s is included, when the media is played back during the like event, else it is omitted.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": { // optional
      "playback_position_s": 10.0
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_like",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_dislike`

This event is sent when a clip is disliked by the user. The property playback_position_s is included, when the media is played back during the event, else it is omitted.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": { // optional
      "playback_position_s": 10.0
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_dislike",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_unlike`

This event is sent when a clip is unliked (remove a previous like or dislike) by the user. The property playback_position_s is included, when the media is played back during the event, else it is omitted.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": { // optional
      "playback_position_s": 10.0 
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_unlike",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_bookmark`

This event is sent when a clip is bookmarked by the user. The property playback_position_s is included, when the media is played back during the event, else it is omitted.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": { // optional
      "playback_position_s": 10.0 
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_bookmark",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_unbookmark`

This event is sent when a clip is removed from the bookmarks of the user. The property playback_position_s is included, when the media is played back during the event, else it is omitted.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": { // optional
      "playback_position_s": 10.0 
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_unbookmark",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_video_mode_changed`

This event is sent when the user changes the video mode.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": {
      "video_mode": "fullscreen", // changed
      "audio_mode": "normal",
      "start_mode": "auto_play",
      "playback_position_s": 123.4,
      "volume": 1
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_video_mode_changed",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Media Event: `media_audio_mode_changed`

This event is sent when the user changes the volume.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<clip_id>",
    "props": {
      "video_mode": "normal",
      "audio_mode": "normal", // might change to "muted"
      "start_mode": "auto_play",
      "playback_position_s": 123.4,
      "volume": 0.5 // changed
    },
    "metadata": {
      "type": "video",
      "format": "ondemand"
    },
    "type": "media_audio_mode_changed",
    "context": { // optional
      "id": "<recommendation_id>"
    }
  }],
  ...
}

Pipe Tracking

Event unspecific payload

Event: recommendation_loaded

Event: recommendation_displayed

Event: recommendation_hit

Event: page_view

​

Media Events

Media Event: media_play

Media Event: media_pause

Media Event: media_stop

Media Event: media_seek

Media Event: media_end

Media Event: media_like

Media Event: media_dislike

Media Event: media_unlike

Media Event: media_bookmark

Media Event: media_unbookmark

Media Event: media_video_mode_changed

Media Event: media_audio_mode_changed