Add custom analytics label support?

[defagos]

As a developer Integrating Pillarbox I need to be able to send custom labels globally, in page views, events or streaming events, depending on what data analysts require.

As a Play developer I namely am currently sending:

• pac_page_id in page view events, providing the identifier of the PAC page associated with a view event.
• source_id in media events, providing the identifier of the list some content was played from.
• user_id and user_is_logged to provide login status information, for Play RTS / maRTS only.

Acceptance criteria

• Discuss with teams integrating Pillarbox whether this is an actual need.
• Identified needs for custom labels (like e.g. those mentioned above) are supported.

Tasks

• [x] Discuss API considerations (single tracking API with service-specific data vs. service-specific tracking APIs, e.g.).
• [x] Create tasks to add custom labels support in dedicated repositories (if needed). These includes global labels, page views, events or streaming events.

[defagos]

This topic was discussed with @waliid and @StaehliJ. A few outputs:

• Our APIs currently provide common methods that transparently forward information to comScore and Commanders Act. If we want to introduce custom fields we can either implement an approach like the one we had in SRG Analytics (custom labels per service), thus exposing the services behind these common APIs in a way. In this case we also probably only need custom labels for Commanders Act as those will never be required for Mediapulse whose specifications we cannot tweak.
• Another approach would be to have a tracking API for each service (with corresponding initialization). This would avoid tensions between hiding services while still exposing parts of them (since we would expose everything), provide APIs which are specific to each service (e.g. clearly separated configurations) but the downside is that integration is then trickier.

For the moment the best is maybe to not implement anything until the needs describe above are encountered again (because when apps really start integrating Pillarbox these needs might not actually exist anymore).

[defagos]

As discussed again with @waliid and @StaehliJ following recent developments:

• We have received enhanced specs from Mediapulse with additional specific fields (e.g. taxonomy) which we should include. These fields have no Commanders Act counterpart.
• Conversely we have new field requirements for Commanders Act (e.g. type) which have no comScore counterpart. We also should support official mandatory fields which, to the best of our current knowledge, can be retrieved from an internal wiki page.

We also learned from @pyby85 that several SRG SSR apps use some of the optional fields listed on this page. Therefore:

• We will reintroduce a custom page view label API.
• We will extend the page view API to provide official symbols for mandatory fields.

No such requirements exist for stream events. We are already sending mandatory labels listed on this page, either directly (generated by the player, e.g. position) or indirectly (received from the IL, e.g. URN).

Regarding the shape of the API itself, and given the fact that data for both services diverges, we will likely adopt an approach with custom data structures, one for comScore, the other for Commanders Act.

[defagos]

Done in https://github.com/SRGSSR/pillarbox-documentation/issues/31 and https://github.com/SRGSSR/pillarbox-android/issues/182.