Pipe Tracking

​ This document describes the different pipe collect events used in the ARD Audiothek.

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.ard.audiothek",
    "id": "00000000-0000-0000-0000-000000000000",
    "version": "?.?.?",
    "type": "<mobileapp|web>",
    "name": "ARD Audiothek"
},
"peach_schema_version": "1.0.3",
"peach_framework_version": "1.0.1-5",
"sent_timestamp": unix_timestamp,
"peach_implementation_version": "0",
"user_id": "<user-id>",
"session_start_timestamp": unix_timestamp

Recommendation Events

Event: recommendation_loaded

This event is sent when the items from a recommendation have been loaded, regardless if they are displayed or not. Currently every time an item detail view is opened. The items array contains the ids of all loaded items. ​

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

Event: recommendation_displayed

This event is sent when the rendered recommendation(s) are displayed to the user. It is triggered when recommended items come into the viewport of the user. The items array contains all item ids that are being displayed. ​

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

Event: recommendation_hit

This event is sent every time a user interacts with an item teaser that comes from a recommendation. The context contains the item id and a zero based hit_index to indicate the position of the recommended item.
As there are several possibilities to interact with a teaser in the audiothek, we trigger the recommendation_hit event before every specific interaction event, as there are:

  • open the detail view (without triggering a play) - hit + page view
  • start playing it inline (without changing view) - hit + play
  • add it to a playlist (default, one, different one, play next queue) - hit + add to playlist
  • download it - hit + download
  • share it - hit + share
  • subscribe to the corresponding program set (aka series) - hit + subscribe
{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<recommendation_id>",
    "type": "recommendation_displayed",
    "context": {
      "item_id": "<item_id>",
      "hit_index": 0
    }
  }],
  ...
}

Media Events

Media events share most of their key value pairs:

  • The id is the item id - for livestreams use the streamClipId of the stream node and change the format to live.
  • The props object
    • audio_mode is either "normal" or "muted" ("background" unused)
    • start_mode is "normal", "auto_play" or "auto_continue": when a user allows autoplay in the detail view of items this value will be auto_play; when a play is triggered automatically after another item the value is "auto_continue", otherwise "normal" is used. In start_mode auto_continue start_mode also set the property previous_id and the corresponding context of the event.
    • playback_position_s is the number of seconds elapsed at the moment the event is triggered for ondemand videos - 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 "audio"
    • format is "ondemand" or "live"
  • The context object has two keys (id and type):
    • if the media event is associated with an item that comes from a recommendation, the context is {type: "recommendation", id: "<recommendation_id>"}
    • if the media event comes from the play-next-queue, a user playlist or the bookmarks, the context is {type: "playlist", id: "<playlist_id|queue>"}
    • otherwise, no context object is sent.

Keep the context only for the listening session that directly follows the hit/play: i.e. when the detail view of a recommended item is opened and then it is played, paused and played again, try to keep the context. If it is added to a playlist and later played from within the playlist, the context changed. ​

Event media_play

This event is sent when an item starts playing. If the start_mode is "auto_continue" the properties object will contain the previous item 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 item. See common properties for media events for further information.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<item_id>",
    "props": {
      "audio_mode": "normal",
      "start_mode": "normal",
      "playback_position_s": 10.0,
      "previous_id": "<prev_item_id>", // obligatory for start_mode `auto_continue`, else optional
      "volume": 1
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_play",
    "context": { // optional, depends on the... context
      "id": "<recommendation_id>",
      "type": "recommendation"
    }
  }],
  ...
}

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": "<item_id>",
    "props": {
      "audio_mode": "normal",
      "start_mode": "normal",
      "playback_position_s": 100.0,
      "previous_playback_position_s": 10.0,
      "volume": 0.8
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_pause",
    "context": { // optional, depends on the... context
      "id": "<recommendation_id>",
      "type": "recommendation"
    }
  }],
  ...
}

Event media_stop

This event is sent when the playback of an item is stopped by either another items play event or because she 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": "<item_id>",
    "props": {
      "audio_mode": "normal",
      "start_mode": "normal",
      "playback_position_s": 100.0,
      "previous_playback_position_s": 10.0,
      "volume": 0.8
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_stop",
    "context": { // optional, depends on the... context
      "id": "<recommendation_id>",
      "type": "recommendation"
    }
  }],
  ...
}

Event media_end

This event is sent when an item 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": "<item_id>",
    "props": {
      "audio_mode": "normal",
      "start_mode": "normal",
      "playback_position_s": 100.0,
      "previous_playback_position_s": 10.0,
      "volume": 0.8
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_end",
    "context": { // optional, depends on the... context
      "id": "<recommendation_id>",
      "type": "recommendation"
    }
  }],
  ...
}

Event media_seek

This event is sent when the user seeked. The previous_playback_position_s key represents where the item 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 listening duration is calculated.

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

List Events

In the Audiothek there are 3 different kinds of lists, where the user can add items to: - Bookmarks (Merkliste) - Playlists - Queue (Warteschlange)

We track manipulation to bookmarks and playlists with media_playlist_add and media_playlist_remove. The queue behaves different than a normal playlist: when the currently playing item ends, the first item of the queue starts playing and it is automatically removed from the queue. So we need specific events for it:

Event media_queue_add

This event is sent when the user adds an item to the queue.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<item_id>",
    "props": {
      "insert_position": "top", // "top" for play next; "end" for append to end of queue.
      "current_item_id": "<current_item_id>" // id of the item currently loaded into the player
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_queue_add",
    "context": { // optional, depends on the... context
      "id": "<recommendation_id>",
      "type": "recommendation"
    }
  }],
  ...
}

Event media_queue_remove

This event is sent when the user explicitly removes an item from the queue.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<item_id>",
    "props": {
      "current_item_id": "<current_item_id>" // id of the item currently loaded into the player
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_queue_remove"
  }],
  ...
}

Event media_playlist_add

This event is sent when the user adds an item to a playlist.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<item_id>",
    "props": {
      "playlist_id": "<playlist_id>",
      "playback_position_s": 100.0, // optional; add it when the same item is played back at the moment of this event
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_playlist_add",
    "context": { // optional, depends on the... context
      "id": "<recommendation_id>",,
      "type": "recommendation"
    }
  }],
  ...
}

Event media_playlist_remove

This event is sent when the user removes an item from a playlist.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<item_id>",
    "props": {
      "playlist_id": "<playlist_id>",
      "playback_position_s": 100.0, // optional; add it when the same item is played back at the moment of this event
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_playlist_remove"
  }],
  ...
}

Event media_download

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<item_id>",
    "props": {
      "audio_mode": "normal", // optional; add it when the same item is played back at the moment of this event
      "start_mode": "auto_play", // optional; add it when the same item is played back at the moment of this event
      "playback_position_s": 10.0, // optional; add it when the same item is played back at the moment of this event
      "volume": 1 // optional; add it when the same item is played back at the moment of this event
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_download",
    "context": { // optional, depends on the... context
      "id": "<recommendation_id>",
      "type": "recommendation"
    }
  }],
  ...
}

Event media_audio_mode_changed

This event is sent when the user changes the volume.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<item_id>",
    "props": {
      "audio_mode": "normal", // might change to "muted"
      "start_mode": "auto_play",
      "playback_position_s": 123.4, // item position when volume is changed
      "volume": 0.5 // changed
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_audio_mode_changed",
    "context": { // optional
      "id": "<recommendation_id>",
      "type": "recommendation"
    }
  }],
  ...
}

Event media_share

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<item_id>",
    "props": {
      "playback_position_s": 10.0, // optional; add it when the same item is played back at the moment of this event
    },
    "metadata": {
      "type": "audio",
      "format": "ondemand"
    },
    "type": "media_share",
    "context": { // optional
      "id": "<recommendation_id>",
      "type": "recommendation"
    }
  }],
  ...
}

Event: page_view

This event is sent, when an item detail view/page is opened. Note: The recommendation id is sent in the context and the id is the item id. ​

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

Event subscribe

This event is sent, when a podcast is subscribed by the user.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<program_set_id>",
    "type": "subscribe",
  }],
  ...
}