Reporting activity and event metrics to UAV

Overview

To enable the wide range of reports that OPF delivers out-of-the-box and to empower operators to create their own reports, the client must send certain data to the OPF platform for processing and storage.

The reported data is used to generate analytics reports that are available through TV Analytics.

The reported data is not available for querying by the client application.

You should follow the guidance below to report the relevant activities and to structure and provide the right data for those activities.

There are specific endpoints for handling bookmarks and favourites (which are not covered here). See Personalisation.

In addition, the following activities are reported directly from the back end and do not need to be reported by client applications:

• Purchase

• Cancel purchase

• Favourite

• Unfavourite

Any value within the metadata section can be left blank, but you need to understand that this data will not be available for processing or reporting. In addition, the client can add additional values in the metadata section in the key-value pair format as required – these additional values will be stored and available for custom reporting.

Prior to release 21.38, clients were required to report such activity and metrics separately so the recommendation engine used could provide personalised recommendations.

Since release 21.38, clients can report activity and metrics as described below and they will be passed on to the recommendation engine automatically without the client having to report them separately.

Request

To report metrics, make the following POST request:

http://<host>:<port>/useractivityvault/v1/useractivity/{activityName}

where activityName is the name of the activity you are reporting. You can use any name that you want, but the following are activity names that Platform understands and associates with regular (non-custom) reports:

• privacyPolicy 

• appStart 

• appEnd 

• playbackStart 

• playbackStop 

• playbackPause 

• playbackResume

• playbackSkipAhead 

• playbackSkipBack 

• adWatched 

• adDelivered 

• adSkipped 

• playbackHeartbeat 

• scheduleRecording

• unscheduleRecording

• watch 

• playback_metrics 

• playerError 

• appError

• thirdPartyAppStart 

• returnToLauncher 

• deepLinkTriggered 

• downloadTriggered  

• railView 

• railSelection

These are explained in more detail in the Activities section below.

This API allows the client to report any activity or action that the operator feels is important or of value for capture. The documented activities below are the suggested actions for capture.

Headers

• Content-Type: application/json

• Authorisation

Mandatory arguments

• accountId

• userId – must be set to "" (empty string)

• deviceId 

• key – must be set to "" (empty string)

The following arguments are not strictly mandatory (that is, omitting them will not cause the request to fail), but are required for full and correct reporting. They are all specified as key/value pairs in the metadata block:

• appSessionId – the appSessionId is used to indicate a period of time wherein a user interacts with the app. Usually triggered by the opening of an app, a session records the length and frequency of app use to show developers, marketers and product managers how much time users spend within an app. An app session id should be generated/starts when a user opens an application and ends when they exit it.

• playbackSessionId – playback session ID, this session is specific to the playout of content, each time the content being played out is changed a new session ID should be generated and used when reporting playout session actions. 

• editorialId – the ID of the editorial, which provides a unique content reference, 

• contentSource – one of the following:

  • IPTV – TV content is delivered over an IP network (not the open Internet)

  • OTT – TV content is deliver over-the-top (OTT), that is, via the Internet

  • Blend – a mixture of IPTV and OTT

• contentType – indicates the type of content being consumed: see the table below for expected values. 

Description of Possible Content Types	Corresponding Content-Type Value to use
VOD content or long-term catchup event	vod-ed
An event recorded through NPVR	npvr-event
A live event	live-event
An short-term catchup event	live-stcu-event
Long-term catchup content	vod-ltcu-event
A start-over event	start-over
Download-to-go (D2G) content Note: any content that is being played back from local storage is considered D2G.	D2G
Deep link triggered	DLT
Third-party app start	TPAS
Return to launcher	RTL

Note on metadata

Clients are free to report any additional metadata in the standard key-value pair format. Any metadata that does not map directly to the definitions in the activities section below will still be stored in the Data Warehouse and be available for custom reporting.

It will be stored in a generic metadata table that can be joined via the activity ID. This allows the client to report any new data or additional data as required without having to make any changes to the Data Warehouse schema. 

Recommendations

In addition to being used for analytics and reporting, activities reported via this interface will also be used to drive recommendations via the partner recommendations engine. This requires specific data to be included in the activity object. For existing integrations, this data is already being supplied within the CDG call, but if the client is updated to include the following activities then the additional calls to CDG can be removed as they will no longer be required. 

The following table shows the default scoring (weighting) that OPF applies to each activity that is related to recommendations. For example, by default, a playbackStart event generates a message to the recommendation engine with a positive score of 0.7. The recommendation engine uses these scores to generate more accurate recommendations for users based on past activities. 

Note that not all of these activities are reported by the client application – some are reported from the relevant platform service.

Activities

We recommend your client app report the following types of activity with the aim of providing at least the listed metadata. In some cases, not all of the metadata will be available. 

For details of the fields that you need to provide in these requests, see Fields for metrics reporting.

The activities are described in the following pages:

• Standard metrics

• App action metrics

• Rails-specific metrics

• QOE/QOS metrics

• Privacy metrics