1. REVISION HISTORY
The Vewd software stack has been deployed on a wide range of connected TV & STB devices for more than a decade, addressing web and video rendering. For the last four years, Vewd has invested in building UX and API products focusing on apps and content. The vision is to bring the content closer to the device UX features, so it's easier to search and discover content. Vewd sees metadata ingestion and deep-linking content as an essential activity for bringing additional traffic and exposure to apps and content owners on a device. The use-cases below are described using Vewd turnkey products UX, but they are equally applicable to Vewd customer’s device user interfaces built on top of our API.
This document explains the data attributes needed for content metadata ingestion and how it will be shown on the device.
To have content metadata for an app onboarded by Vewd, the owner or developer of the content must share it for review. This document defines the requirements and the process for ingesting the content metadata and gives an overview of how it will be shown in the device user-interface. Compliant metadata feeds are required by Vewd and will have a quicker time to market. While the metadata attributes may not be compliant with this specification, Vewd will review and process the content feed and provide feedback on what may need to change.
2.3 Metadata use cases
Enable content discovery for your app
Apps traditionally live inside a device user-interface within the home screen, app section, or category in an app store. The content in the app is not discoverable unless the app is accessed. To solve this, the content owner needs to expose access to metadata and deep-links of their content. The content can be made discoverable on Vewd enabled devices through a compliant content metadata feed. This chapter gives a visual overview of the use-cases Vewd will utilize in the device home screen using metadata feed from content owners. These UX features are called app preview, promotions, and catalog search.
2.3.2 App preview
App preview provides a sneak peek of what type of content the app is providing. The content can be launched directly from the home screen and into the app through a deep-link, so the end-user can quickly discover and launch new content. We recommend that CSPs provide promotional content feeds with the most engaging content assets and keep it maintained and fresh over time(*).
*Vewd will display the content in the order we receive it from the content feed as default, alternatively utilize the publishing date of the content
Example app preview in action:
Promotion is used as part of the featured section in Vewd UX products. It autoplay videos on device startup and focuses on a limited set of video promotion items for a given period.
Example promotions in action:
2.3.4 Catalog search
Make the app and its content searchable within Vewd UX products by sharing a compliant full catalog content metadata feed. Vewd will then ingest the content according to the supported content types, for example as movies, tv-show, and clips. From what we have seen, this increases content discoverability and traffic into the app.
Example of catalog search in action:
2.3.5 Data attributes by content types
|Element||Description||Clip||Movie||TV Series||TV Season||TV Episode||Livestream|
Unique content id
Media type indicates the type of content: clip, movie, tv_series, tv_season, tv_epiosde, live stream
Metadata language in RFC 3066 language code
The date when the content became available in the catalogue in ISO 8601 format
|country-availability||List of countries in ISO 3166-1 alpha-2 format for which the content is available||M||M||M||M||M||M|
|duration||Content duration in seconds or in ISO 8601 format||M||M||-||-||M||-|
|deep-links||List of content deep links URL associated with ISO 3166-1 alpha-2 country code for which the deep-link is targeted||M||M||O||M||M||M|
|audio-language||Content original audio language as RFC 3066 language code||O||O||O||O||O||O|
|captions||List of available subtitles languages as RFC 3066 language codes||O||O||O||O||O||O|
|aired-date||The UTC date that clip was first aired or made available (aka release date) in ISO 8601 format||M||M||O||O||M||-|
|tags||List of content descriptor tags||O||O||O||O||O||O|
|genres||List of content categories and genres||M||O||O||O||O||O|
Generic pricing indication of the content, typically indicating:
List of Images, indication image type (thumbnail, poster) URL, width and height
Thumbnails are required for clips, TVSeries, TVEpisode, LivestreamPosters are required for movies
|localizations||List of localized fields per country||O||O||O||O||O||O|
|(tv_series specific attributes)|
|series-id||Unique TV_Series id||-||-||-||M||M||-|
|season-id||Unique TV_Season id||-||-||-||-||M||-|
|number||Season or Episode number||-||-||-||M||M||-|
M : mandatory
O : optional
- : Not applicable
2.4 Definitions and acronyms
|Vewd OS is complete Over The Top (OTT) management and presentation system for Smart TVs. It includes a user-interface with quick access to OTT apps, content, search, device settings, Linear TV & program guide|
|Vewd OpX is a cloud-managed Operator-grade set-top box experience, integrating PayTV services with OTT content. It is based on a flexible set of UX modules (UXM) that can be combined to build or enhance a TV experience|
Vewd App Store
|The Vewd App Store is an HTML5-based storefront of web apps optimized for TV. The Vewd App Store and its apps run from the cloud and are optimized for the TV user experience and its 4-way navigation remote control|
Vewd Content Suite APIs
|API access of app & content metadata for integrators, so they can easily integrate and launch content from their device|
|Access to additional information about the video, such as title, description, genre, thumbnail, and other data attributes described above|
|Content service provider, the party who provides the apps & the content|
2.5 Compliance terminology used in this document
The following keywords used in this specification to indicate the level of compliance needed for the requirements are sourced from RFC2119. In essence:
- MUST, REQUIRE or SHALL indicates that you need to comply with the requirement absolutely.
- SHOULD or RECOMMENDED indicates that while sometimes there could be valid reasons to ignore the requirement, you need to fully understand and accept the implications and risks to the optimal end-user experience.
- MAY or OPTIONAL indicates that you can decide to implement an item at your discretion.
We also use an additional compliance term not described in RFC2119:
- CONDITIONALLY REQUIRED - an item or a feature is supported in the browser if the underlying platform supports this capability.
3. METADATA ONBOARDING PROCESS
3.1 Onboarding process
- CSP gets familiar with Vewd UX products & metadata use-cases visually
- CSP agrees with Vewd to ingest metadata
- CSP provides access to the metadata (promotional and full catalogue feeds) and describes data elements mapping to Vewd data points - 2.3.4 Data attributes by content types
- Vewd validates and/or maps the metadata to this specification (some feed adaptations may be needed, for example in the area of localizations, images formats, genres dictionaries, or others)
- Vewd perform onboarding tests
- Vewd team provides test results to the CSP
- If tests are positive the ingestion can start
- If there are major issues, they need to be fixed and validated before the ingestion can start.
3.1.1 Onboarding tests insights
During the onboarding tests Vewd team will check if:
- All mandatory data elements are present for each media type for both promotional and full catalogue feeds
- Feed payload is successfully ingested by Vewd software
- Selected elements from metadata are visible in Vewd Content Suite API
3.2 Metadata availability
We require the metadata endpoint to be widely accessible for our distributed servers. In case it’s required to limit the availability of the endpoint by e.g whitelisting IP addresses then please use the below list.
The following IP addresses must be allowed to access metadata endpoint(s):
3.2.1 Metadata re-indexing rate
Once the metadata ingestion is officially kicked-off we will periodically check changes in the endpoint and update our index. The refresh rate is around 6 hours but may change in the future without prior notice. It means that any change to your content availability (adding or removing videos or change of metadata) might take up to 6 hours to show in the device user-interface.
Note: In case of deletions in the metadata payload the respective content shall remain accessible for the next 6 hours to let this change be propagated to devices from which the application is being launched. Otherwise, applications may use deep links leading to no content.
3.3 Metadata format
CSP shall expose metadata payload compliant with the data points described in the 2.3.4 Data attributes by content types providing all mandatory attributes and mapping to them. CSP may expose optional or additional data elements in the content feed not covered by this specification, yet they will be ignored. Vewd reserves the right to normalize and map the metadata set received from the CSP with an additional set of attributes from internal or external sources, making the content more discoverable for the end-user.
At this stage, Vewd does not specify metadata format implicitly and is willing to adopt market formats in use, such as but not limited to Google Media Action. However, we expect that metadata payload will contain a flat list of content items (one dimension array, no nested subarrays), where TVSeries/TVSeasons/TVEpisode relation is represented by media-type & series-id and/or season-id respectively.