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",
    "user_logged_in": true // indicates whether the user is logged when the event occurs. It's set explicitly in the pipe SDK.
},
"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,
"collect_timestamp": unix_timestamp,
"site_key": "deard00000000046" // "deard00000000046" for prod: "deard00000000045" for dev

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_hit",
    "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.
- previous_id: has to be set in start_mode auto_continue, also when the user skipped an item - this should trigger a media_stop event followed by a media_play event with the previous_id property correctly set. auto_continue and skipping is possible in playlists, the queue, when playing all episodes of a program set or a editorial collection.
- 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, the bookmarks, the history or downloads list, the context is {type: "playlist", id: "<playlist_id|bookmarks|downloads|history|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, also set this property after the user skipped an item. 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|bookmarks>",
      "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|bookmarks>",
      "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",
  }],
  ...
}

Event `unsubscribe`

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

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

Event `tracking_optout`

This event is sent, when a user decides, that she doesn't want to send tracking data to the given provider. For the provider peach this will be the last event received by the given user until she switches it on again with tracking_optin.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<user_id>",
    "type": "tracking_optout",
    "props": {
      "provider": "peach" // other values: "other" (for ati, ivw, nielsen, etc)
    }
  }],
  ...
}

Event `tracking_optin`

This event is sent, when a user decides, that sending trackin data to the given provider is fine for her.

{
  "client": {...},
  "events": [{
    "event_timestamp": unix_timestamp,
    "id": "<user_id>",
    "type": "tracking_optin",
    "props": {
      "provider": "peach" // other values: "other" (for ati, ivw, nielsen, etc)
    }
  }],
  ...
}

Pipe Tracking

Event unspecific payload

Recommendation Events

Event: recommendation_loaded

Event: recommendation_displayed

Event: recommendation_hit

Media Events

Event media_play

Event media_pause

Event media_stop

Event media_end

Event media_seek

List Events

Event media_queue_add

Event media_queue_remove

Event media_playlist_add

Event media_playlist_remove

Event media_download

Event media_audio_mode_changed

Event media_share

Event page_view

Event subscribe

Event unsubscribe

Event tracking_optout

Event tracking_optin