Skip to content

PEACH

General guidelines

Peach Collect Format v1.0.3

Reference: pipe gitlab

Guidelines :

if the value of an element is null/undefined, do not send it
timestamps are in milliseconds (UTC based)
durations are in seconds

Payload main structure

(* mandatory, + optional, ► server injected)

Attribute	Description
peach_schema_version *	version of the schema used for the creation of the payload
peach_implementation_version +	implementation version of Peach in the app/site
session_start_timestamp +	timestamp of the start of the session. For web, it can be the non persistent cookie generation time (_pipe_st). On mobile, the time when the app was launched (or when it's opened after an inactive period).
site_key ►	SiteKey in which events will be grouped
collect_timestamp ►	timestamp when the request is received
sent_timestamp *	timestamp of the sending of the payload
user_id +	user unique identifier when user is logged in
client *	dictionary description of the client used by the user (device, app/browser)
events *	array of events

Client Dictionary

Attribute	Description
id *	Persistent cookie ID for web, Advertising ID for mobile (or any UUID stable across reboots)
type +	`mobileapp` or `web`
app_id *	Bundle identifier of the mobile application Path or module for web : `br.de/mediathek`, `cms 1.3.2+`...
name +	Display name for mobile application Browser name for web : `Firefox`, `Chrome`, `Safari`...
version +	Should follow "Major.Minor.hotfix" format : `1.5.3` Browser version for web
device +	Dictionary describing the device used
os +	Dictionary describing the OS running on the device

Device Dictionary

Attribute	Description
type *	`console`, `phone`, `tablet`, `desktop`, `hbbtv`, `tvbox`, `wearable`, `embedded`
vendor +	`Apple`, `Samsung`, `HTC`...
model +	`iPhone 3.1`, `Galaxy Nexus`...
screen_size +	`"1680x1050"`
language +	`"en-GB"`, `"fr-FR"`...
timezone +	hour difference to UTC : `-1`, `3`...

OS Dictionary

Attribute	Description
name +	`ios`, `android`, `macOS`...
version +	Should follow "Major.Minor.hotfix" format : `1.5.3`

What it looks like

{
    "peach_schema_version": "1.0.3",
    "peach_implementation_version": "A.B.3",
    "site_key": "chrts00000000031", // com
    "session_start_timestamp": 1511802218359,
    "sent_timestamp": 1511802219043,
    "collect_timestamp": 1511804006063,
    "user_id": "123e4567-e89b-12d3-a456-426655440000",
    "client": {
        "id": "636c84b8",
        "type": "mobileapp",
        "app_id": "ch.rts.play.playrts",
        "name": "Play RTS",
        "version": "Major.Minor.hotfix",
        "device": {
            "type":"phone",
            "vendor": "Apple",
            "model": "iPhone 3.1",
            "screen_size": "1680x1050",
            "language": "en-GB",
            "timezone": -1
        },
        "os": {
            "name": "ios",
            "version": "12.2"
        }
    },
    "events": [...]
}

Events


recommendation	`recommendation_displayed`, `recommendation_hit`, `recommendation_loaded`
media	`media_play`, `media_pause`, `media_seek`, `media_stop`, `media_end`, `media_heartbeat` `media_video_mode_changed`, `media_audio_mode_changed`, `media_audio_changed` `media_like`, `media_share`
page	`article_start`, `article_end`, `read_more`, `page_view`

Event dictionary structure

Attribute	Description
type *	see list of possible event types
id *	unique identifier of the related element (recommendation, media, page...)
event_timestamp *	timestamp when the event happened
context +	dictionary representation of the context in which the event happened
props +	dictionary representation of the properties (used for media events)
metadata +	metadata of the related element (used for media events) should be kept as small as possible as it is only meant for data filtering

Recommendation events

Recommendations events only need a context, no properties or metadata.

Event type	Description
`recommendation_loaded`	Sent when a recommendation has been loaded (when the API call to the recommendation endpoint is done).
`recommendation_displayed`	Sent when one or multiple items from the recommendation appear on screen. On mobile, this event should be fired when the scroll view stops scrolling and when an item is fully visible (or at leat enough to be tappable). This even should be fired only once when user is scrolling in the same view
`recommendation_hit`	Sent when the user taps/clicks on an item

Context element

Attribute	Description
items *	list of items (generally medias or articles) used in `recommendation_loaded` and `recommendation_displayed`
item_id *	unique identifier of the item hit used in `recommendation_hit`
hit_index *	position of the item hit in the list of displayed items used in `recommendation_hit`
page_uri +	unique identifier of app section where the recommendation is displayed
source +	identifier of the UI element in which the recommendation is displayed (the module, view or popup)
component +	dictionary description of the element in which the recommendation is displayed

What it looks like

{
    "type": "recommendation_loaded",
    "id": "reco18",
    "event_timestamp": 1511804006061,
    "context" : {
        "items" : ["URN:XXW", "URN:XXX", "URN:XXY", "URN:XXZ"]
        "page_uri" : "example.org/section1/path",
        "source" : "main-section.news.reco3",
                "component" : {
                  "type": "carousel",
                  "name": "SuperCarousel",
                  "version": "2.3.4"
            }
    }              
}

{
    "type": "recommendation_displayed",
    "id": "reco18",
    "event_timestamp": 1511804006061,
    "context" : {
        "items" : [ "URN:XXY", "URN:XXZ"],
        "page_uri" : "example.org/section1/path",
        "source" : "main-section.news.reco3",
                "component" : {
                  "type": "carousel",
                  "name": "SuperCarousel",
                  "version": "2.3.4"
            }
    }              
}

{
    "type": "recommendation_hit",
    "id": "reco18",
    "event_timestamp": 1511804006061,
    "context" : {
        "item_id" : "URN:XXY",
        "hit_index" : 0,
        "page_uri" : "example.org/section1/path",
        "source" : "main-section.news.reco3",
                "component" : {
                  "type": "carousel",
                  "name": "SuperCarousel",
                  "version": "2.3.4"
            }
    }              
}

Media events

Event type	Description
`media_play`	Sent when the playback starts/resumes
`media_pause`	Sent when the users manually pauses the playback
`media_stop`	Sent when the playback is interrupted (either by the user going to another view/page or if the media is buffering)
`media_end`	Sent when the playback has reached the end without being interrupted
`media_heartbeat`	Sent at regular interval during the playback
`media_video_mode_changed`	Sent when the user goes from `fullscreen` to `normal` for example
`media_audio_mode_changed`	Sent when the user continue navigation and the player is minified or when the app is sent to background
`media_audio_changed`	Sent when the user switches the audio track (changing language for example)
`media_share`	Sent when the media is shared
`media_like`	Sent when the like button is pressed

Context element

Attribute	Description
id *	unique identifier in data source (recommendationID, listProviderID...)
type +	type of the element referenced by the id (`recommendation`, `playlist`...)
referrer +	For web, URL from where the user came to this page (can be external website)
page_uri +	identifier of app section (or webpage) where the player is displayed
source +	identifier of the UI element in which the player is displayed (the module, view or popup)
component +	dictionary description of the element in which the recommendation is displayed

Properties element

Attribute	Description
time_spent_s +	total time (in seconds) spent by the user watching this media in current session
playback_position_s +	playback position in seconds. for live playback : `0.0` and time-shift in the past result in negative value used for `media_play`, `media_pause`, `media_stop`, `media_end` and `media_heartbeat` events
previous_playback_position_s +	seconds. live: `0.0`. time-shift in past result in negative value
is_playing +	boolean describing if the media is playing when the event is fired optionnal, used for `media_seek` events as it can happen while playing or when the media is paused
video_mode +	`bar`, `mini`, `normal`, `wide`, `pip`, `fullscreen`, `cast`, `preview`
audio_mode +	`normal`, `background`, `muted`
start_mode +	`normal`, `auto_play`, `auto_continue`
previous_id +	in case of auto_continue start mode, unique identifier of the previous media
playback_rate +	relative speed to normal : 0.5 for 2x slow motion
volume +	decimal value from 0.0 (muted) to 1.0

What it looks like

{                                             
    "type": "media_play",
    "id": "URN:XXX",
    "event_timestamp": 1511804006061,
    "context": {
        "id": "reco18",
        "referrer": "http://facebook.com/...",
        "page_uri": "example.org/section1/path",
        "source": "main-section.news.reco3",
        "component": {
            "type": "player",
            "name": "ExoPlayer",
            "version": "1.2.1"
        }
    },
    "props": {
        "time_spent_s": 123.3,
        "playback_position_s": 12.9,
        "previous_playback_position_s": 2.9,
        "video_mode": "normal",
        "audio_mode": "normal",
        "start_mode": "normal",
        "previous_id": "URN:xxx",
        "playback_rate": 1.0,
        "volume": 0.5,
    },
    "metadata": {
        "type": "video",
        "format": "ondemand",
        "episode_id": "URN:XXX",
        "show_id": "URN:XXX",
        "duration": 1779.8
    }
}

{                                             
    "type": "media_pause",
    "id": "URN:XXX",
    "context": {
        "id": "reco18",
        "referrer": "http://facebook.com/...",
        "page_uri": "example.org/section1/path",
    },
    "props": {
        "time_spent_s": 123.3,
        "playback_position_s": 45.0,
        "playback_rate": 0,
        "volume": 0.5,
    },
    "metadata": {
        "type": "video",
        "format": "ondemand",
        "episode_id": "URN:XXX",
        "show_id": "URN:XXX",
        "duration": 1779.8
    }
}

{                                             
    "type": "media_seek",
    "id": "URN:XXX",
    "context": {
        "id": "reco18",
        "referrer": "http://facebook.com/...",
        "page_uri": "example.org/section1/path",
    },
    "props": {
        "time_spent_s": 123.3,
        "playback_position_s": 45.0,
        "previous_playback_position_s": 2.9,
        "playback_rate": 1.0,
        "volume": 0.5,
    },
    "metadata": {
        "type": "video",
        "format": "ondemand",
        "episode_id": "URN:XXX",
        "show_id": "URN:XXX",
        "duration": 1779.8
    }
}

{                                             
    "type": "media_heartbeat",
    "id": "URN:XXX",
    "context": {
        "id": "reco18",
        "referrer": "http://facebook.com/...",
        "page_uri": "example.org/section1/path",
    },
    "props": {
        "time_spent_s": 123.3,
        "playback_position_s": 12.9,
        "playback_rate": 1.0,
        "volume": 0.5,
    },
    "metadata": {
        "type": "video",
        "format": "ondemand",
        "episode_id": "URN:XXX",
        "show_id": "URN:XXX",
        "duration": 1779.8
    }
}

Other events

Event type	Description
`article_start`	Sent when a user stars reading an article
`article_end`	Sent when a user reaches the end of an article (not necessarily the end of the page/view)
`read_more`	Sent when user taps on the "Read more" button is pressed
`page_view`	Sent when a user displays a page (or a view on mobile)

// TODO : provide JSON samples events