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 the recommendation list is downloaded
`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). An item can be displayed multiple times (if the user scrolls backward)
`recommendation_hit`	Sent when the user taps 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
`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
playlist_id +	playlist identifier of the playlist the media is added to or removed from used for `media_seek` events
insert_position +	The position of the item in the playlist referenced by `playlistID`
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
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
    }
}

// TODO : provide JSON samples for all media event types

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