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.

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
playbackSkipAhead
playbackSkipBack
adWatched
adDeliverd
adSkipped
playbackHeartbeat
scheduleRecording
watch
playback_metrics
playerError
thirdPartyAppStart
returnToLauncher
deepLinkTriggered
downloadTriggered
railView
railSelection

These are explained in more detail in the (22.24_Q2) Reporting activity and event metrics to UAV#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	`vod-ed`
An event recorded through NPVR	`npvr-event`
A live event	`live-event`
An short-term catchup event	`live-stcu-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`

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 activitytable 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.

Activities used for recommendations

Default scoring (from -1 (worst) to 1 (best))

Required data

playbackStart

0.7

One of the following, dependent on the content type being watched:

Type	Required value
VOD	Technical ID
BTV	Program ID
Series or season	Series ID

scheduleRecording 0.7 Program ID

watch

1

One of the following, dependent on the content type being watched:

Type	Required Value
VOD	Technical ID
BTV	Program ID
Series or season	Series ID

deepLinkTriggered 0.5 Deep link ID

downloadTriggered

0.7

Technical ID

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.

Category	Activity name	Trigger	Description	Message metadata keys	Notes	Examples
Privacy
	`privacyPolicy`	User consent or non-consent	Allows the client to capture the user's consent and related information in relation to any local or global policy.	deviceId accountId consentForTargettedAd policyConsentGiven policyType policyShown policyRead policyString dateTimeDevice	The US privacy string (`policyString`) consists of the following components: Specification version: a number that represents the version of the string specification Explicit notice: An enum that represents whether the explicit notice has been provided (N = no, Y = yes, – = not applicable) Opt-out sale: an enum that represents whether the user has opted out of the sale of their data (N = no, Y = yes, – = not applicable) `policyType` – one of the following: CCPA GDPR PDPA	POST https://<server>/useractivityvault/v1/useractivity/privacyPolicy { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "privacyPolicy", "deviceId": "60acc1efba91e2032c508e50", "key":"", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "consentForTargettedAd" : "", "policyConsentGiven" : "", "policyType" : "", "policyShown" : "", "policyRead" : "", "policyString" : "1YN" } }
Standard
	`appStart`	Client session creation	When app starts up	appSessionId deviceId activityDateTime accountID userId	`appSessionID` is created when application is started, persisted until application closed by user or due to inactivity. In mobile, a session begins when the app is opened (in the foreground) and ends when it goes into the background and no events occur within a predetermined time window, dependent on the measurement provider. Note that because of the typical multitasking nature of mobile users, events that occur within the predetermined window count towards the current session.	POST https://<server>/useractivityvault/v1/useractivity/appStart { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "appStart", "deviceId": "60acc1efba91e2032c508e50", "key":"", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "appSessionId" : "<UUID>", "activity`DateTime`": "2020-03-20T10:53:19Z" } }
	`appEnd`	Client session tear down	When app is shut down or times out due to inactivity	appSessionId deviceId accountId userId activityDateTime		POST https://<server>/useractivityvault/v1/useractivity/appEnd { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "appEnd", "deviceId": "60acc1efba91e2032c508e50", "key":"", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "appSessionId" : "<UUID>" "activity`DateTime`": "2020-03-20T10:53:19Z" } }
	`playbackStart`	Start of playback		appSessionId playbackSessionId editorialID deviceId accountId userId contentSource Type railId Depth templateId technicalId programmeId seresId editorialID deeplinkId deviceType	Zero position event The `playbackSession` needs to be associated with the playback event. `playbackSessionId` – generated when playback starts.	POST https://<server>/useractivityvault/v1/useractivity/playbackStart { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "playbackStart", "key": "", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "railId" : "<UUID>", "depth" : 77, "templateId" : "<UUID>", "editorialID" : "GLOBAL_20711" } }
	`playbackStop`	User stops playback either with stop action or browsing away from playout		appSessionId playbackSessionId Position editorialID contentSource Type deviceId accountId userId		POST https://<server>/useractivityvault/v1/useractivity/playbackStop { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "playbackStop", "key": "", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "position" : 34, "editorialID" : "GLOBAL_20711" } }
	`playbackPause`	User pauses playout		appSessionId playbackSessionId Position editorialID contentSource contentType deviceId accountId userId		POST https://<server>/useractivityvault/v1/useractivity/playbackPause { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "playbackPause", "key": "", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "position" : 34, "editorialID" : "GLOBAL_20711" } }
	`playbackSkipAhead`	Fast forward or drag timeline forward	Covering fast forward or skip, allowing the tracking of the start point and the endpoint when playback resumes	appSessionId playbackSessionId startPosition stopPosistion editorialID contentSource contentType deviceId accountId userId	`startPosition` – when the skip is triggered `stopPosition` – when playback is resumed	POST https://<server>/useractivityvault/v1/useractivity/playbackSkipAhead { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "playbackSkipAhead", "key": "", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "startPosition" : 34, "stopPosition" : 50, "editorialID" : "GLOBAL_20711" } }
	`playbackSkipBack`	Rewind or drag timeline backward	Covering rewind or skip back, allowing the tracking of the start point and the endpoint when playback resumes	appSessionId playbackSessionId startPosition stopPosistion editorialID contentSource contentType deviceId accountId userId	`startPosition` – when the skip is triggered `stopPosition` – when playback is resumed	POST https://<server>/useractivityvault/v1/useractivity/playbackSkipBack { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "playbackSkipBack", "key": "", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "startPosition" : 50, "stopPosition" : 24, "editorialID" : "GLOBAL_20711" } }
	`adWatched`	Completion of viewing a delivered advert	For ad tracking, allows the client to capture data on the adverts watched by the user	appSessionId playbackSessionId adID trackingAssetId adSupplier deviceId accountId userId		POST https://<server>/useractivityvault/v1/useractivity/adWatched { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "adWatched", "key": "GLOBAL_20711", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "adID" : "<UUID>", "trackingAssetId" : "<UUID>", "adSupplier": "<name>" } }
	adDelivered	Ad delivered in a stream	Capture adverts that are delivered, useful for reference if the user skips the ad	appSessionId playbackSessionId adID trackingAssetId adSupplier deviceId accountId userId		POST https://<server>/useractivityvault/v1/useractivity/adDeliverd { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "adDelivered", "key": "GLOBAL_20711", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "adID" : "<UUID>", "trackingAssetId" : "<UUID>", "adSupplier": "<name>" } }
	adSkipped	Skipping adverts where allowed.	Capture the action of skipping an ad where allowed.	appSessionId playbackSessionId adID trackingAssetId adSupplier deviceId accountId userId		POST https://<server>/useractivityvault/v1/useractivity/adSkipped { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "adSkipped", "key": "GLOBAL_20711", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "adID" : "<UUID>", "trackingAssetId" : "<UUID>", "adSupplier": "<name>" } }
	scheduleRecording	User triggers a recording to be created on OPF		appSessionId playbackSessionId editorialID Series_Link Series_Id deviceId accountId userId technicalId programmeId seriesId deeplinkId deviceType	Platform could provide this with a small impact.	POST https://<server>/useractivityvault/v1/useractivity/scheduleRecording { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "scheduleRecording", "key": "", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "seriesLink" : "<UUID>", "seriesId" : "<UUID>", "editorialID" : "GLOBAL_20711", "technicalId" : "jkn193887", "programmeId" : "010928", "seriesId" : "298940", "deeplinkId" : "DeepL_20711", "deviceType" : "ios" } }
	playbackHeartbeat	Created regularly to indicate that the user is watching a stream of content without interacting with the client. we recommend recording this activity every *60 seconds*.	Heartbeat/playout time Used to track playout at a granular level. This data is not recorded for operational use only used for reporting.	appSessionId playbackSessionId Position editorialID Type deviceId accountId userId	If the player metrics are reported regularly with a matching session ID, we can use those for the streaming indicator.	POST https://<server>/useractivityvault/v1/useractivity/playbackHeartbeat { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "playbackHeartbeat", "key": "", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "position" : 78, "editorialID" : "GLOBAL_20711" } }
	watch	Created when the user clicks the play option on content	Current activity that is reported on first playback	appSessionId playbackSessionId Position editorialID Type railId templateId deviceId accountId userId	Keep for backward compatibility.	POST https://<server>/useractivityvault/v1/useractivity/watch { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "key": "", "deviceId": "60acc1efba91e2032c508e50", "name": "watch", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "recordingId": "ABC_1234", "playbackSessionId" : "<UUID>", "appSessionId" : "<UUID>", "position" : 789, "railId" : "<UUID>", "templateId" : "<UUID>", "contentId" : "GLOBAL_20711" } }
QOE/QOS
	Playback_Metrics	To be reported back at a consistent interval, this can be configured by clients. we recommend recording this activity every 60 seconds.	Metrics as supplied by the player and reported back via the client.	appSessionId playbackSessionId Playback_Progress Bitrate_selected Content_Type Available_Bitrate bytes_Downloaded avg_download_bitRate Buffer_Duration Stream_Bitrate Dropped_Frames Total_Frames content_URI		POST https://<server>/useractivityvault/v1/useractivity/playback_metrics { "accountId": "5fdc9fba4b2a7952d931019f", "userId": "", "deviceId": "604897f1695d7c6f961d6f23", "name": "playback_metrics", "key": "", "timestamp": 1615370562718, "metadata": { "playbackSessionId" : "<UUID>", "appSessionId" : "<UUID>", "editorialId" : "GLOBAL_89714_20210310090000", "playbackProgress" : "56", "contentSource": "IPTV", "contentType": "live-stcu-event", "selectedBitrate": "2000000", "availableBitrates": "[90000, 500000, 750000, 1100000, 2000000]", "bytesDownloaded": "1011433", "downloadBitrate": "7698824", "downloadBitrateAverage": "6593692", "uri": https://origin-nagravision-a-01.vos360.video/Content/DASH/Live/channel(HEVC_Test_Channel)/manifest.mpd, "bufferedDuration": "3", "streamBitrate": "2000000", "droppedVideoFrames": "0", "totalVideoFrames": "50" } }
	playerError	Log client side errors as required	Where required, useful to capture basic error information that relates to the user experience	appSessionId playbackSessionId editorialID errorCode errorMsg playerTypeversion deviceId accountId userId	Not to be used for logging or debugging. Use sparingly where the error will have impacted the user and would provide value for reporting.	POST https://<server>/useractivityvault/v1/useractivity/playerError { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "name": "playerError", "key": "", "deviceId": "60acc1efba91e2032c508e50", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "appSessionId" : "<UUID>", "playbackSessionId" : "<UUID>", "errorCode" : "", "errorMsg" : "", "playerTypeVersion" : "", "editorialID" : "GLOBAL_20711" } }
App Actions
	thirdPartyAppStart	To be created when a third-party application is triggered/opened on the launcher	Capture the act of starting a third-party application due to a deep link or the client acting as a launcher (Netflix, Prime, etc.).	appSessionId playbackSessionId appName appReference deeplinkProviderId railId templateId deviceId accountId userId	Deep link provider is the provider of the deep-linked content (e.g., Disney, Prime, etc .).	POST https://<server>/useractivityvault/v1/useractivity/thirdPartyAppStart { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "key": "GLOBAL_20711", "deviceId": "60acc1efba91e2032c508e50", "name": "thirdPartyAppStart", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "playbackSessionId" : "<UUID>", "appSessionId" : "<UUID>", "appName" : "", "appReference" : "", "railId" : "<UUID>", "templateId" : "<UUID>" } }
	returnToLauncher	To be created when the launcher becomes the active app	Launcher becomes active	appSessionId playbackSessionId app_name deviceId accountId userId		POST https://<server>/useractivityvault/v1/useractivity/returnToLauncher { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "key": "GLOBAL_20711", "deviceId": "60acc1efba91e2032c508e50", "name": "returnToLauncher", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "live-stcu-event", "playbackSessionId" : "<UUID>", "appSessionId" : "<UUID>", "appName" : "" } }
	deepLinkTriggered	To be created when a deep linked asset is selected via the client	Clicking through to watch content from a Rail or other client source on a deep link provider	appSessionId playbackSessionId deeplinkProviderId Source editorialID providerResourceId railId templateId deviceId accountId userId	Provider ID is the content ID as provided in the deep link data. Deep link provider is the provider of the deep-linked content (Disney, Prime, etc.).	POST https://<server>/useractivityvault/v1/useractivity/deepLinkTriggered { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "key": "GLOBAL_20711", "deviceId": "60acc1efba91e2032c508e50", "name": "deepLinkTriggered", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentSource": "IPTV", "contentType": "deeplinktriggered", "playbackSessionId" : "<UUID>", "appSessionId" : "<UUID>", "deeplinkProviderId" : "", "source" : "", "providerResourceId" : "", "deepLinkid" : "<UUID>", "railId" : "<UUID>", "templateId" : "<UUID>", "editorialID" : "GLOBAL_20711" } }
	downloadTriggered	To be created when content is downloaded for watching off line, aka D2G.	Download to go Capture the action when a user triggers the download of content	appSessionId playbackSessionId editorialID railId templateId deviceId accountId userId		POST https://<server>/useractivityvault/v1/useractivity/downloadTriggered { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "key": "", "deviceId": "60acc1efba91e2032c508e50", "name": "downloadTriggered", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentType": "live-stcu-event", "playbackSessionId" : "<UUID>", "appSessionId" : "<UUID>", "railId" : "<UUID>", "templateId" : "<UUID>", "editorialID" : "GLOBAL_20711" } }
Rails-specific
	railView	Created when the Rail is shown on the screen (user engagement measure)		appSessionId playbackSessionId templateId railId depth deviceId accountId userId		POST https://<server>/useractivityvault/v1/useractivity/railView { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "key": "GLOBAL_20711", "deviceId": "60acc1efba91e2032c508e50", "name": "railView", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentType": "live-stcu-event", "playbackSessionId" : "<UUID>", "appSessionId" : "<UUID>", "depth" : "", "railId" : "<UUID>", "templateId" : "<UUID>" } }
	railSelection	Created when a user selects a Rail item to open the media card/more detail		appSessionId playbackSessionId templateId railId sectionId editorialID Type deviceId accountId userId deeplinkProviderId providerResourceId		POST https://<server>/useractivityvault/v1/useractivity/railSelection { "accountId": "60ab88ccb780b5233dfec9cd", "userId": "", "key": "", "deviceId": "60acc1efba91e2032c508e50", "name": "railSelection", "timestamp": "2020-03-20T10:53:19Z", "metadata": { "contentType": "live-stcu-event", "playbackSessionId" : "<UUID>", "appSessionId" : "<UUID>", "sectionId" : "", "railId" : "<UUID>", "editorialID" : "GLOBAL_20711", "providerResourceId" : "", "deeplinkProviderId" : "", "templateId" : "<UUID>" } }