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.
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:
privacyPolicyappStartappEndplaybackStartplaybackStopplaybackPauseplaybackSkipAheadplaybackSkipBackadWatchedadDeliverdadSkippedplaybackHeartbeatscheduleRecordingwatchplayback_metricsplayerErrorthirdPartyAppStartreturnToLauncherdeepLinkTriggereddownloadTriggeredrailViewrailSelection
These are explained in more detail in the (22.38_Q3) 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
accountIDuserId– must be set to""(empty string)deviceIdkey– 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– theappSessionIdis 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 InternetBlend– 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-edAn event recorded through NPVR
npvr-eventA live event
live-eventAn short-term catchup event live-stcu-eventA start-over event start-overDownload-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:
| ||||||||
scheduleRecording | 0.7 | Program ID | ||||||||
| 1 | One of the following, dependent on the content type being watched:
| ||||||||
deepLinkTriggered | 0.5 | Deep link ID | ||||||||
| 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.
For details of the fields that you need to provide in these requests, see the (22.38_Q3) Reporting activity and event metrics to UAV#Fields table below.
| 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 | The US privacy string (
| POST https://<server>/useractivityvault/v1/useractivity/privacyPolicy | |
| Standard | ||||||
appStart | Client session creation | When app starts up | appSessionId |
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 | |
appEnd | Client session tear down | When app is shut down or times out due to inactivity | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/appEnd | ||
playbackStart | Start of playback | appSessionId | Zero position event The
| POST https://<server>/useractivityvault/v1/useractivity/playbackStart "accountId": "60ab88ccb780b5233dfec9cd", } | ||
playbackStop | User stops playback either with stop action or browsing away from playout | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/playbackStop { | |||
playbackPause | User pauses playout | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/playbackPause | |||
| 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 |
| POST https://<server>/useractivityvault/v1/useractivity/playbackSkipAhead | |
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 |
| POST https://<server>/useractivityvault/v1/useractivity/playbackSkipBack | |
adWatched | Completion of viewing a delivered advert | For ad tracking, allows the client to capture data on the adverts watched by the user | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/adWatched | ||
adDelivered | Ad delivered in a stream | Capture adverts that are delivered, useful for reference if the user skips the ad | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/adDeliverd | ||
adSkipped | Skipping adverts where allowed. | Capture the action of skipping an ad where allowed. | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/adSkipped | ||
scheduleRecording | User triggers a recording to be created on OPF | appSessionId | Platform could provide this with a small impact. | POST https://<server>/useractivityvault/v1/useractivity/scheduleRecording | ||
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 | 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 | |
watch | Created when the user clicks the play option on content | Current activity that is reported on first playback | appSessionId | Keep for backward compatibility. | POST https://<server>/useractivityvault/v1/useractivity/watch | |
| 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 | POST https://<server>/useractivityvault/v1/useractivity/playback_metrics { | ||
playerError | Log client side errors as required | Where required, useful to capture basic error information that relates to the user experience | appSessionId | 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 | |
| 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 | Deep link provider is the provider of the deep-linked content (e.g., Disney, Prime, etc .). | POST https://<server>/useractivityvault/v1/useractivity/thirdPartyAppStart | |
returnToLauncher | To be created when the launcher becomes the active app | Launcher becomes active | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/returnToLauncher | ||
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 | 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 | |
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 | POST https://<server>/useractivityvault/v1/useractivity/downloadTriggered | ||
| Rails-specific | ||||||
railView | Created when the Rail is shown on the screen (user engagement measure) | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/railView | |||
railSelection | Created when a user selects a Rail item to open the media card/more detail | appSessionId | POST https://<server>/useractivityvault/v1/useractivity/railSelection | |||
Fields
| Field | Definition |
|---|---|
accountId | The account ID of the current signed-in account |
activityDateTime | Date and time in UTC that the event/action being logged occurred |
adID | Unique advertisement reference, VAST tag |
adSupplier | Name or unique ID of the advert supplier |
appName | Text name of the application reporting the metrics. This is used to easily identify the app in the database. Equivalent to tenant ID in the token. |
appReference | Reference for the application. This could be an ID or text value. To be deprecated. |
appSessionId | Unique ID to identify the current session of the application. Generated by the application upon start up and persisted until the next start up. 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. |
appVersion | Version number for the currently deployed application |
Available_Bitrate | Text value to indicate the bitrates available for the content being streamed, available from the player. Content available bitrates in bits per second (bps) |
avg_download_bitRate | The average value of the bitrate stream, available from the player. Average selected bitrate in bits per second (bps) (sampled and averaged within the reporting period) |
Bitrate_selected | Bitrate selected for viewing (streaming) available from the player |
Buffer_Duration | The current buffer duration in seconds at the time of reporting metrics, available from the player |
bytes_Downloaded | Total number of bytes downloaded at the time of reporting the metrics, available from the player |
clientLoggedDateTime | The date and time the event is logged as per the date and time set on the client device. (This may not be the same as the date and time set server side.) |
consentForTargettedAd | If the user has consented to targeted advertising, this value should be reported as true. |
Content_Type | Indicates the type of content being consumed. See content_Type in Mandatory arguments above. |
content_URI | URI of the video stream, available from the player. This URI points to the master playlist. |
contentQualityChanged | Current content quality (SD, HD, 4K, 8K, Unknown) |
contentSource | One of the following:
|
deeplinkId | Unique value assigned to the deep link being triggered. This will be found in the metadata supplied to the client. A deep link is a reference from some content to the same content in an external, third-party system. For example the same movie present in Netflix, Disney+, or Apple TV. |
deeplinkProviderId | Unique value assigned to the deep link provider. This will be found in the metadata supplied to the client. |
depth | Relevant for Rails interactions, the depth of the item interacted with by the user, click, media card or playout. Vertical position |
deviceId | Unique device ID as provided by the platform to the client. |
deviceType | Value as defined in First time and n-th time sign on |
Dropped_Frames | Number of frames dropped from the video stream, available from the player |
editorialID | Available in the metadata provided by the head end.
|
errorCode | Unique code that relates to an error. This can be a standard code or client application specific. |
errorMsg | The relevant error message related to the error |
hdepth | RAILS – the horizontal depth of the rail item being interacted with / reported on, starting at 0 and counted from the first item / leftmost item in the Rail incrementally |
metadata | Generic activity |
Position | The position in seconds that the current action relates to in the current content being streamed in seconds. This should be in relation to the content being viewed in totality, i.e., if the user is watching the 20th minute of a show, the value reported should be 1200. If the user starts playout from a bookmark at the 10th minute then the value reported should be 600. |
Playback_Progress | The position in seconds that the current action relates to in the current content being streamed in seconds. This should be in relation to the content being viewed in totality, i.e., if the user is watching the 20th minute of a show, the value reported should be 1200. If the user starts playout from a bookmark at the 10th minute then the value reported should be 600. |
playbackSessionId | To be generated by the client application. A unique playback session ID, this session is specific to the playout of content. Each time the content being played is changed either via a selection triggered by the user or due to the channel playout content changing, a new session ID should be generated and used when reporting playout session actions. The session ID (UUID) corresponds to the current session. For non-linear content such as VOD, a playback session occurs between the start of playing of a video until it stops (or aborts or crashes) not interrupted by pauses or seeks. |
playerTypeversion | Version number of the player being used/integrated into the client |
PlayoutURL | The URL of the content being streamed, the video stream URL, URI pointing to the master playlist |
policyConsentGiven | If the user has consented to the policy shown on screen this value should be reported as true, if not then false. |
policyRead | If the user has indicated they have read the policy this value should be reported as true, if not, then false. |
policyShown | If the client has shown the policy on screen to the end user this value should be reported as true, if not, then false. |
policyType | The type of policy shown/consented to, e.g., Data Retention |
programmeId | Identifier for a TV programme as provided by the platform in the metadata response (a live TV programme). It is shown on a specific service at a certain time. See /btv/programmes. |
railId | The unique ID of the Rail being interacted with or reported on, as supplied in the RAILS metadata response from the head end. |
SDKVersion | The video metrics SDK version installed on the client application |
selectedBitrateChanged | Bitrate in bps that was selected after bitrate changed event |
seriesId | The series ID as supplied in the metadata from the head end |
source | Broadcast source (DVB or OTT) for each channel, see Using metadata to select the broadcast source. |
Stream_Bitrate | The current bit rate being consumed, supplied by the player |
technicalId | This unique ID is specific to the content stream provided to the client, supplied in the response to the client. The technical part of the content (Playback URI, Device Type, etc). Usually hidden from the end-user, describes to the device if it is allowed to play content and where to get it. |
templateId | RAILS template ID that the client is rendering for the user to interact with, supplied in the response to the client |
timeToVideoStart | Time taken from setUrl to rendering of the first frame on the screen |
Total_Frames | Total frame count, available from the player |
trackingAssetId | A unique ID for tracking, as generated by the client |
Type | See Content_Type. |
userId | Unique ID to identify a specific user or user profile |
vdepth | RAILS – the vertical depth of the rail being interacted with / reported on starting at 0 and counted from the first/top rail incrementally |