Guidelines for the implementation of the PEACH data collection at RTS

  1. General description
  2. Implementation of media event data collection
  3. Implementation of recommendation data collection
  4. Data Validation API

1. General description

The data format proposed by PEACH has a core set of attributes that are common to all the data (we call this the event wrapper), and an a set of attributes that vary for each use case (under the event attribute).

The event wrapper to be used varies depending on the client:

1.1 Mobile clients

Valid for both Mobile player and apps.

Sample of event wrapper:

{
    "client": {
        "app_id": "ch.rts.rtsplayer",
        "device": {
            "language": "fr-CH",
            "model": "iPad4:2C1",
            "screen_size": "1024x768",
            "type": "tablet",
            "vendor": "Apple"
        },
        "id": "33890007-724E-4FC5-83B6-A35A37FAF22F",
        "name": "Play_RTS",
        "os": {
            "name": "ios",
            "version": "12.1.1"
        },
        "type": "mobileapp",
        "version": "2.9"
    },
    "event": {} // see event format depending on event type
    "peach_implementation_version": "0.9.6",
    "peach_schema_version": "1.0.0",
    "sent_timestamp": 1554177597297,
    "session_start_timestamp": 1554160590000,
    "user_id": "unknown"
}

Description of attributes:

Attribute Description
client.app_id App Bundle identifier
client.device.language Google ads format. ex: "en-US"
client.device.model Device model
client.device.screen_size "width x height"
client.device.type "phone" | "tablet" | "tvbox"
client.device.vendor Vendor name
client.id Globaly unique id. Tag Commander unique id
client.name Pretty app name
client.os ios / android
client.os.name Mobile OS
client.os.version Mobile OS version
client.type "mobileapp", hardcoded
client.version Major.Minor.hotfix
peach_implementation_version client-specific version number
peach_schema_version 1.0.0, hardcoded
sent_timestamp Number. Timestamp in milliseconds
session_start_timestamp Number. Timestamp in milliseconds
user_id MaRTS user id. "unknown" for not logged user
  • client.device.timezone was not included as it was not available in Tag Commander.

!! IMPORTANT !!:

  • peach_implementation_version needs to be maintained by the development team and increased every time a change in the format version is made.

1.2. Web clients

Valid for both Web Player, Play HP and RTS.ch.

Sample of event wrapper:

{
    "client": {
        "device": {
            "language": "en-GB",
            "screen_size": "1920x1080",
            "timezone": -2,
            "type": "desktop"
        },
        "id": "425ad381-835f-b1be-d5a1-e292c0caa759",
        "type": "web"
    },
    "event": {} // see event format depending on event type
    "peach_implementation_version": "1.0.5",
    "peach_schema_version": "1.0.0",
    "sent_timestamp": 1554216039403,
    "session_start_timestamp": 1554215926477,
    "user_id": "205894"
}

Description of attributes:

Attribute Description
client.device.language Google ads format. ex: "en-US"
client.device.screen_size "width x height"
client.device.timezone Number. With respect to UTC
client.device.type "desktop" | "phone" | "tablet" | "tvbox"
client.id cookie id
client.type "web", hardcoded
peach_implementation_version client-specific version number
peach_schema_version 1.0.0, hardcoded
sent_timestamp Number. Timestamp in milliseconds
session_start_timestamp Number. Timestamp in milliseconds
user_id MaRTS user id. "unknown" for not logged user

!! IMPORTANT !!:

  • The event wrapper is created directly by pipe.js if initialized properly.
  • Specifically, peach_implementation_version needs to be maintained by the development team and increased every time a change in the format version is made. peach_implementation_version is set by lib user see doc below from https://git.ebu.io/pipe/pipe-js.
Set your data format version
You shall use the peach_implementation_version. You may use version strings that fit your needs.
_pipe('setPeachImplVersion', 'some-version-string');

2. Implementation of media event data collection

Mobile client(TODO)

Web client (TODO)

3. Implementation of recommendation data collection

3.1. General guidelines

Must follow steps:

  1. Send an event recommendation_displayed every time a set of recommended content is displayed to the user. This data is necessary to track all the content proposed to users independently of whether users clicked on it or not.
  2. Send an event recommendation_hit every time a user clicks on a recommended video. This data is necessary to track all the content that has been clicked by users.
  3. Include a recommendation id in every media event (media_play, media_pause, etc) sent for any media played out of a recommendation (i.e. following a recommendation hit). This data is necessary to link recommended and consumed content (for example to compute the time spent watching a recommended media to assess the performance of the recommendation). [Optional] If implementation allows, media_heartbeat can be exempt of the including recommendation id (this allows to reduce the amount of data sent).

What is the recommendation id?

The recommendation id helps identify where does the recommendation come from. For ALL data coming form the PEACH API, this should be equal to "io.ebu.peach:ID_from_rec_API", where io.ebu.peach indicates that content comes from PEACH and ID_from_rec_API is the ID included in the response of the PEACH API. The ID_from_rec_API tells us what algorithm is behind the recommendation.

Example of recommendation id:

"io.ebu.peach:5dZprKKrT+G418Jr4c6HSfUBMOTlVa09T1RuLAVsnolITOAwPzUHMfHEzhUSfDNoq3THYQwW6bpjNTYRKVr/SScsP4byyxn0oVhcQmjBV1lizU15eFahRlE2jN0v8PlalH9qxazR7HQZ9h1vGb1tiBpDa/5cS1tq+Ia8uhO/RSlWB5Mz5IuK41XsysDNRNSR"

Client-specific implementations:

3.2 Mobile client

3.2.1 Mobile Player

TODO

3.2.2 Mobile apps

TODO

3.3 Web clients

3.3.1 Web Player

TODO

3.3.2 Play HP and RTS HP

How to integrate recommendation_displayed events in Play HP and RTS HP

Sample:

{
    "context": {
        "items": [
            "urn:rts:video:10291316",
            "urn:rts:video:10308130",
            "urn:rts:video:10318833"
        ],
        "items_displayed": 3,
        "page_uri": "https://www.rts.ch/play/tv",
        "source": "teaserModule"
    },
    "event_timestamp": 1553854193564,
    "id": "io.ebu.peach:5dZprKKrT+G418Jr4c6HSfUBMOTlVa09T1RuLAVsnolITOAwPzUHMfHEzhUSfDNoq3THYQwW6bpjNTYRKVr/SScsP4byyxn0oVhcQmjBV1lizU15eFahRlE2jN0v8PlalH9qxazR7HQZ9h1vGb1tiBpDa/5cS1tq+Ia8uhO/RSlWB5Mz5IuK41XsysDNRNSR",
    "type": "recommendation_displayed"
}

Description of attributes:

Attribute Description
context.items array of URNs with ALL the items ever displayed to the user. For current implementation in Play HP, must send a recommendation_displayed with the four items shown by default to the user. Then, once the user clicks on “Afficher plus”, must send another recommendation_displayed with ALL the items from the recommendation.
context.items_displayed Number. length of context.items
context.page_uri URL of the current page (protocol + domain name + path). Avoid sending the parameters of the URL like in "https://player.rts.ch/p/rts/portal-detail?urn=urn:rts:video:10318524&autoplay=true&start=0". Limit to "https://player.rts.ch/p/rts/portal-detail"
context.source unique UI element in page that integrates recommendation (e.g. teaserModule, recoRow1, recoRow2)
event_timestamp Number. UTC timestamp in milliseconds of when then event was fired
id "io.ebu.peach:ID_from_rec_API", see What is a recommendation id.
type "recommendation_displayed", hardcoded

Note for datalab only:

For the purpose of calculating CTRs, we will need to discard consecutive recommendation_displayed with the same recommendation context.id (i.e. same recommendation with different numbers of items displayed). To do so, the simplest is to keep the latest event. (Note that CTR cannot be computed form the recommendation_hit alone, because we need to include all the recommendations displayed independently of whether they were clicked or not).

How to integrate recommendation_hit events in Play HP and RTS HP

Sample:

{
    "context": {
        "hit_index": 0,
        "items": [
            "urn:rts:video:10291316",
            "urn:rts:video:10308130",
            "urn:rts:video:10318833"
        ],
        "items_displayed": 3,
        "page_uri": "https://www.rts.ch/play/tv",
        "source": "teaserModule"
    },
    "event_timestamp": 1553854193564,
    "id": "io.ebu.peach:5dZprKKrT+G418Jr4c6HSfUBMOTlVa09T1RuLAVsnolITOAwPzUHMfHEzhUSfDNoq3THYQwW6bpjNTYRKVr/SScsP4byyxn0oVhcQmjBV1lizU15eFahRlE2jN0v8PlalH9qxazR7HQZ9h1vGb1tiBpDa/5cS1tq+Ia8uhO/RSlWB5Mz5IuK41XsysDNRNSR",
    "type": "recommendation_hit"
}

Description of attributes:

Attributes are the same than for the recommendation_displayed, except the following:

Attribute Description
context.hit_index Numnber. Index in context.items for the item that was clicked [0..items - 1].
type "recommendation_hit", hardcoded

How to include a recommendation id in every media event played out of a recommendation

An recommendation id must be added under context, for each media_event sent (media_play, media_pause, etc) for a media played out of a recommendation.

Note:

  • This requires to pass the recommendation id to the player so it includes the id in all events sent from the player.
  • Remember to format context.id as explained here.
  • [Optional] If implementation allows, media_heartbeat can be exempt of the including recommendation id (this allows to reduce the amount of data sent).

Sample of media_play with a recommendation id:

{
    "context": {
        "component": {
            "name": "SRG Technical Player",
            "type": "player",
            "version": "1.13.131"
        },
        "id": "io.ebu.peach:nH3KbMFOb4xd6mwvaCB3LOMcrUJ0JcVtA9APqs4f6mKJk0z6lptDQiErRyUj0muxYABhoyP6QGW7T+ERU+2gIqur0WRDOrx7Z/I4SA9vC1CRj76cc7DdWJB5E8f69JjRAb1Vw5qSovE8A+cqCV83vaMsWpUol+N6fn5tfjYpJBfGnoHubYvq3LfY+fhn7tno",
        "page_uri": "https://player.rts.ch/p/rts/portal-detail",
        "referrer": "https://www.rts.ch/play/tv/temps-present/video/ne-circulez-plus-vous-etes-trop-vieux--ukraine-les-combattantes-du-donbass"
    },
    "event_timestamp": 1553876316782,
    "id": "urn:rts:video:10050203",
    "metadata": {
        "duration": 3312.92,
        "format": "ondemand",
        "type": "video"
    },
    "props": {
        "playback_position_s": 0
    },
    "type": "media_play"
}

4. Data validation API

There is a Data Validation API hosted in AWS that can be used by the development teams for unit testing.

A GET request to /v1/api/data_format/ gives the format required for a given client and event:

http://ec2-18-195-138-55.eu-central-1.compute.amazonaws.com:2627/v1/api/data_format?client=play_hp&event=recommendation_hit

A POST request to /v1/api/validate_data/ validates the data for a given client and event:

http://ec2-18-195-138-55.eu-central-1.compute.amazonaws.com:2627/v1/api/

The data object should include three attributes: json_data the full object to be sent to PEACH, client (e.g. "rts_hp", "play_hp"), event (e.g. "recommendation_hit", "recommendation_displayed", etc).

Sample call:

curl -XPOST "http://ec2-18-195-138-55.eu-central-1.compute.amazonaws.com:2627/v1/api/validate_data" -H "Content-Type: application/json"  -d '{"json_data":{"client":{"device":{"language":"en-GB","screen_size":"1920x1080","timezone":-2,"type":"desktop"},"id":"425ad381-835f-b1be-d5a1-e292c0caa759","type":"web"},"event":{"context":{"hit_index":0,"items":["urn:rts:video:10291316","urn:rts:video:10308130","urn:rts:video:10318833"],"items_displayed":3,"page_uri":"https://www.rts.ch/play/tv","source":"teaserModule"},"event_timestamp":1553854193564,"id":"io.ebu.peach:5dZprKKrT+G418Jr4c6HSfUBMOTlVa0HEzhUSf","type":"recommendation_hit"},"peach_implementation_version":"1.0.5","peach_schema_version":"1.0.0","sent_timestamp":1554216039403,"session_start_timestamp":1554215926477,"user_id":"205894"},"client":"rts_hp","event":"recommendation_hit"}'