Overview
A client application needs to read the response it receives from Content Delivery and render each screen and the rails that it contains according to the contents of the response.
This page explains:
Together with Rails responses – instances, it lays out the expected rails functionality that is expected to be supported by an OpenTV ENTera partner client application.
Basic rails concepts
Templates and layouts
A template represents a page in your application. For example, there may be a template for each of the following
Home screen
Movies screen
Guide (EPG) screen
Explore screen
Each template can have one or more layouts. For example, it might have:
One layout for each destination: tv, mobile, tablet, and desktop
A single (default) layout that applies to all possible destinations.
One or more layouts that apply to one or more destinations and a default layout for destinations that are not covered by a specific layout
For example, you could have one layout that applies only to mobile and a default layout that will be used for all other destinations.
When a client requests templates, it specifies its destination type in the request and Content Delivery returns the layout for each template that matches the specified destination.
Rails and rail sections
A rail can consist of one or more rail sections. For example, a single rail could contain the following sections:
Although these are added to the rail as three sections in OpCon, the response that you receive from Content Delivery will simply include nine section blocks, one for each item that the client needs to render in the rail.
Blueprints
A blueprint defines a type of strip (rail). It includes a set of parameters that define how a rail that is based on it should be presented.
Each defined blueprint can have one or more instances, each of which defines a specific version of the blueprint.
For example, there is a predefined blueprint called Magazine Strip. And there are predefined instances of Magazine Strip called Large Poster Magazine and Hero Magazine 1.
Similarly, for the predefined blueprint type called Promotional Strip, there are instances called Single Promotion: 3:1 Dual Height Row and Double Promotion: 4:1 Dual Height Row.
When a rail is created, it is based on an instance of a blueprint, that is, one of the following:
A predefined instance of a predefined blueprint
A custom instance of a predefined blueprint
A predefined instance of a custom blueprint
A custom instance of a custom blueprint
No blueprint at all (legacy rail)
Custom components
A custom component is a component with specific functionality that can be added to a rail. For example:
An ad banner
An application launcher
A feature banner
Each of these items, when included in a rail response, includes the target that the client should navigate to if the user clicks or taps the item:
For an ad banner, the ad server URL
For an app launcher, the platform-specific package ID
For a feature banner, the ID of the template (page in the client app) to be navigated to
Key/value pair groups
A key/value pair group is a common configuration element that can be used to extend the definition of a rail/strip.
As with blueprints, there are both key/value pair groups and specific instances of each key-value pair group.
After a rail has been created, one or more key/value pair group instance can be added to it.
For example, there are predefined key/value pair groups for:
Branding – includes an image and a brand name for adding branded elements to a rail/strip
Logo (rail) – includes a logo image that the client should add to the rail
Logo (content) – includes a logo image for content and fields that indicate the positioning and opacity of the logo
Android Channels API – includes a setting that maps content to Android TV’s native channel system
Note that a rail/strip with an instance of this key/value pair group will not usually have any content – it will be populated by channels from the Android Channels API.
Note that you can only add an instance of a key-value pair group to a specific rail. You cannot add one to a blueprint or blueprint instance.
Ad-hoc key/value pairs
In addition to key/value pair groups, a rail can have ad-hoc key/value pairs. These are referred to as Additional Properties in the OpCon UI.
Ad-hoc key/value pairs were typically used to provide client applications with details about how to render rails before blueprints existed.
Typical call flow
Typically, the client will need to make several calls to get all the information it needs to render the different pages that make up its interface and the rails within each page:
Call GET https://<host>:<port>/contentdelivery/v1/templateviews/hierarchy to get the hierarchy of templates that represent the various screens.
For each page/template, call GET https://<host>:<port>/contentdelivery/v1/templatesummary/{templateId} to get the rails that make up the page (without their contents).
For each rail on the page, call GET https://<host>:<port>/contentdelivery/v2/templateviews/{templateId}/rails/{railId}?limit=10 to get the rail contents and metadata.
You are recommended to use the limit, page, and offset parameters to load only enough rail items to fill the visible part of the rail and the first part that the user will see if they scroll horizontally, and only load more if they do scroll.
See Best practices – rails.
When you make a request to Content Delivery, you should include the destination (e.g., tv or mobile) in the Nagra-Target header. Content Delivery returns the appropriate layout for that destination.
You must also include the device type (e.g., Android or iOS) in the Nagra-Device-Type header. This ensures that the rails that Content Delivery returns reference the correct technical contents (e.g., an HLS technical for iOS or a DASH technical for Android).
Rail fields
The following tables explain the fields that are returned when you make a rail request for each type of blueprint, custom component, and key/value pair group.
For the specific values that are returned for each instance of a blueprint or key/value pair group, see Rails responses – instances.
Differences between template and rail responses
The differences between a template response and a rail response are as follows:
Both templates and rails can have blueprints applied to them. Blueprints at the template level are a legacy feature.
Common fields
The following table lists the fields that are not specific to blueprints, custom components, or key/value pair groups:
Field | Description | Availability (template or rail) | Value/present | Meaning/actions |
|---|
name
| The name of the rail | Both | Always present (mandatory) | The client should display this as the title of the rail if title is null. |
title
| The rail title | Both | May be present or null | If title is not null, the client should use this as the title of the rail. |
layout
| The default image orientation | Both | Either Landscape or Portrait | Use this value for all rails in the layout, unless: They are overridden at the rail level, or The rail uses a blueprint that determines the orientation of the images
|
properties
| Other properties for the rail | Both | Zero or more key/value pairs | Typically used to instruct the client on how to present the rail before blueprints were introduced. |
sections
| The sections that the rail includes. In a template response, this is always an empty array. | Rail (present in template response, but always an empty array) | N/A | To get the actual contents of the rail, you must make a get rail request. In the rail response, the sections block will be populated (unless the rail is empty). |
hasNext
| Whether there is more content available for the rail. In a template response, this is always null. | Rail (present in template response but always null) | N/A | To get the actual contents of the rail, you must make a get rail request. In the rail response, the hasNext field will be true if more content is available or false if not. |
id
| The ID of the rail | Both | Always present | No action required |
Blueprints
The following fields are all within the configurationProperties block.
Standard strip
Keys | Type | Values | Description |
|---|
type
| static | standard_strip
| The type field defines the type of rail this blueprint describes. |
layout_style
| static | standard
| The layout_style defines how the rail should be presented to the user. It provides guidance on the display format and interaction style, helping the client to organise and showcase content effectively. standard:
The standard layout presents tiles in a linear, continuous fashion, allowing users to scroll left or right freely without boundaries. This style is best suited for displaying a large volume of content in a seamless, uninterrupted scrolling experience. The focus is on smooth, continuous navigation through the content. Example:
|
tile_pattern
| enum selector (duplicates on, re-ordering on) | default,
16x9,
4x3,
3x2,
2x3,
4x5,
1x1,
3x1,
4x1
| The tile_pattern defines the layout and aspect ratio of tiles within the rail. The selected pattern, which may consist of a combination of aspect ratios, is repeated across the rail and can accommodate duplicate tiles. default: The tile pattern is dynamically determined by the client, meaning the client has full control over how the tiles are arranged. 16x9, 4x3, 2x3, 4x5, 1x1, 3x1, 4x1: These are fixed aspect ratios for tiles. You can specify multiple ratios, and they will be repeated across the rail in the order selected.
Examples: Single aspect ratio: Multiple aspect ratios: Multiple aspect ratios with duplicates:
|
show_more
| boolean | | The show_more setting instructs the client whether to display a “Show More” link or button within the rail. This link allows users to navigate to a separate screen or view that is specific to the rail content, offering more detailed or expanded options. This is typically used when the content in the rail exceeds the initial set of items shown, and the user can view more items in a dedicated section. true: Displays the “Show More” link or button, allowing the user to load additional content or navigate to a more detailed view. false: Hides the “Show More” link, limiting the user to the initially displayed content without offering the ability to view more.
Notes: The actual placement, behaviour, and flow of the “Show More” functionality (e.g., the navigation to the next screen or the content load mechanism) is not defined within this blueprint and must be implemented by the client as needed. The client should ensure that the “Show More” experience is intuitive and aligns with the content layout and user interface.
|
max_pages
| numeric (0 to 1000) | | The max_pages setting defines the maximum number of pages that can be retrieved for the rail. This value allows clients to control the number of results displayed within the rail, offering more control over how much content is shown at once. 0: No restriction on the number of pages. The client can continue retrieving pages until no more are available, allowing for an infinite or uninterrupted content stream. > 0: The client is restricted to retrieving no more than the specified number of pages. If the rail can display more content, the client must stop retrieving additional pages once the limit is reached.
The max_pages value is an absolute maximum. However, there may not be enough content available to reach the full amount defined. In other words, if the total number of items is less than the maximum, the client will only retrieve what is available. If max_pages is set to a specific limit and more content exists, the show_morefield can be used to allow the user to "break out" from the rail into a separate page where the max_pages limit is no longer applied. This would allow access to more content beyond the specified max_pages restriction. Example Usage: Unlimited pages: Limited pages: max_pages: 5
This would indicate the client should be restricted to only retrieving up to five pages, even if more pages are available in the rail's content source. If fewer than five pages are available, the client will retrieve what is available.
|
visible
| boolean | | The visible setting acts as a simple flag that allows the client to show or hide a rail without removing it from the template or layout. true: The rail will be displayed to the user within the layout. false: The rail will be hidden from view but still remains part of the template. It can be toggled back to true later without needing to modify the layout or template structure.
|
Magazine strip
Keys | Type | Values | Description |
|---|
type
| static | magazine_strip
| The type field defines the type of rail this blueprint describes. magazine_strip:
A magazine_strip type defines a rail that is double-height, multi-tile, and can optionally contain hero tiles that span multiple rows. This type is often used for layouts where the content is presented in a magazine-style format, with visually impactful tiles (e.g., hero tiles) that stand out and occupy more space compared to the other smaller tiles.
|
layout_style
| enum | dual_row_hero_grid,
dual_row_grid_hero,
single_row_grid
| The layout_style field specifies how the tiles should be arranged within the rail. These options allow for flexibility in how larger tiles (such as hero tiles) are placed alongside smaller content tiles. Hero tiles are optional, but when included, they may repeat at different points within the layout. dual_row_hero_grid:
This layout style places a large hero tile that spans both rows at the beginning of the rail, followed by smaller grid-style tiles. Hero tiles can repeat throughout the layout, acting as focal points, while the grid tiles present additional content in a more compact, uniform format. dual_row_grid_hero:
In this style, the grid layout is displayed first, with two rows of smaller tiles, followed by a large hero tile that spans both rows. Hero tiles can repeat throughout the layout, acting as focal points, while the grid tiles present additional content in a more compact, uniform format single_row_grid:
A simple single row grid layout with no hero tiles. Tiles will be double height.
|
grid_tile_pattern
| enum selector (duplicates on, re-ordering on) | default,
16x9,
4x3,
3x2,
2x3,
4x5,
1x1
| The grid_tile_pattern field defines the layout and aspect ratio of tiles within the rail. This pattern, which may consist of a combination of aspect ratios, is repeated across the rail, and can accommodate duplicate tiles. When combined with hero tiles, the pattern is repeated as part of the overall layout, ensuring consistency in how tiles appear throughout the rail. default:
The tile pattern is dynamically determined by the client, meaning the client has full control over how the tiles are arranged. 16x9, 4x3, 3x2, 2x3, 4x5, 1x1:
These are fixed aspect ratios for tiles. You can specify multiple ratios, and they will be repeated across the rail in the order selected. When hero tiles are used, they will be incorporated into the repeating pattern either at the start, or at the end
Examples: Single aspect ratio:
4x3
Result: [4x3] [4x3] [4x3] ... Multiple aspect ratios:
4x3, 16x9
Result: [4x3] [16x9] [4x3] [16x9] ... Multiple aspect ratios with duplicates:
4x3, 4x3, 16x9, 16x9
Result: [4x3] [4x3] [16x9] [16x9] ... Combination with repeating hero tiles:
4x3, 16x9, (hero tiles)
Result: [4x3] [16x9] [Hero] [4x3] [16x9] [Hero] .. Combination with non-repeating hero tiles:
4x3, 16x9, (hero tiles)
Result: [4x3] [16x9] [Hero] [4x3] [16x9] [4x3] [16x9] ....
|
grid_tile_pattern_invert
| boolean | | The grid_tile_pattern_invert field allows for the inversion of the aspect ratio pattern across rows within a 2-row grid. When set to true, the aspect ratios specified for each row in the grid_tile_pattern are inverted between the rows. This feature simplifies the configuration for alternating aspect ratios between two rows, where the pattern in row 1 is swapped for row 2, creating a visually dynamic effect. When set to true: The pattern specified for row 1 is inverted in row 2.
For example, if row 1 is configured as 4x3, 16x9, the result for row 2 would be 16x9, 4x3. When set to false (or not specified): The pattern defined in grid_tile_pattern will be applied consistently across both rows, without inversion.
|
hero_tile_aspect_ratio
| enum | default,
16x9,
4x3,
3x2,
2x3,
4x5,
1x1
| The hero_tile_aspect_ratio field specifies the aspect ratio for the "hero" tile within a rail layout. The hero tile is typically a larger, more prominent tile designed to draw attention, often placed at the top or highlighted within a section. In a configuration where there are two rows, the hero tile is always intended to span both rows, providing a larger visual impact. default: The aspect ratio of the hero tile is dynamically determined by the client, giving full control over how the hero tile is rendered. 16x9, 4x3, 3x2, 2x3, 4x5, 1x1, 3x1, 4x1:
These are fixed aspect ratios for tiles.
|
hero_tile_repeat
| boolean | | The hero_tile_repeat field controls whether the hero tile appears multiple times within the grid layout, or just once, providing flexibility for layouts with either a single or multiple hero tiles. true: The hero tile will be inserted repeatedly in the grid layout, appearing at multiple positions according to the selected tile pattern. This is useful when multiple hero tiles are needed across the rail for visual consistency or emphasis. false: The hero tile appears only once, typically spanning multiple rows at the top of the rail, providing a singular, prominent visual.
|
show_more
| boolean | | The show_more setting instructs the client whether to display a “Show More” link or button within the rail. This link allows users to navigate to a separate screen or view that is specific to the rail content, offering more detailed or expanded options. This is typically used when the content in the rail exceeds the initial set of items shown, and the user can view more items in a dedicated section. true: Displays the “Show More” link or button, allowing the user to load additional content or navigate to a more detailed view. false: Hides the “Show More” link, limiting the user to the initially displayed content without offering the ability to view more.
Notes: The actual placement, behaviour and flow of the “Show More” functionality (e.g., the navigation to the next screen or the content load mechanism) is not defined within this blueprint and must be implemented by the client as needed. The client should ensure that the “Show More” experience is intuitive and aligns with the content layout and user interface
|
max_pages
| numeric (0 to 1000) | | The max_pages setting defines the maximum number of pages that can be retrieved for the rail. This value allows clients to control the number of results displayed within the rail, offering more control over how much content is shown at once. 0: No restriction on the number of pages. The client can continue retrieving pages until no more are available, allowing for an infinite or uninterrupted content stream. > 0: The client is restricted to retrieving no more than the specified number of pages. If the rail can display more content, the client must stop retrieving additional pages once the limit is reached.
The max_pages value is an absolute maximum. However, there may not be enough content available to reach the full amount defined. In other words, if the total number of items is less than the maximum, the client will only retrieve what is available. If max_pages is set to a specific limit and more content exists, the show_morefield can be used to allow the user to "break out" from the rail into a separate page where the max_pages limit is no longer applied. This would allow access to more content beyond the specified max_pages restriction. Example Usage: Unlimited pages: Limited pages: max_pages: 5
This would indicate the client should be restricted to only retrieving up to five pages, even if more pages are available in the rail's content source. If fewer than five pages are available, the client will retrieve what is available.
|
visible
| boolean | | The visible setting acts as a simple flag that allows the client to show or hide a rail without removing it from the template or layout. true: The rail will be displayed to the user within the layout. false: The rail will be hidden from view but still remains part of the template. It can be toggled back to true later without needing to modify the layout or template structure.
|
Keys | Type | Values | Description |
|---|
type
| static | promotional_strip
| The type field defines the category of rail this blueprint describes. A promotional_strip rail is designed to highlight featured or time-sensitive content, such as special offers, exclusive releases, or marketing-driven material/advertisements. This type of rail may be visually distinct, include attention-grabbing elements, or allow for dynamic content updates based on promotional cycles. These are designed to work in conjunction with feature_banner rail items, although they can accept any standard rail item. |
layout_style
| enum | triple_height,
dual_height,
single_height
| The layout_style field specifies how the tiles should be arranged within the rail. triple_height:
A simple single-row, triple-height layout dual_height:
A simple single-row, double-height layout single_height:
A simple single-row, single-height layout
|
carousel
| boolean | | The carousel is a special layout variant designed to show a limited number of items at a time (typically three to five). It emphasises a more organised or featured display, often showcasing highlighted content or key items. Carousels are commonly used for promotions, featured items, or spotlight content. Depending on the client’s navigation style, a carousel may include navigation controls, such as: Carousels are ideal for highlighting specific content, ensuring that the user’s attention is drawn to a select few items within the strip. Notes: |
tile_pattern
| enum selector (duplicates on, re-ordering on) | 16x9,
4x3,
2x3,
3x2,
4x5,
1x1,
3x1,
4x1
| The tile_pattern field defines the layout and aspect ratio of tiles within the rail. This pattern, which may consist of a combination of aspect ratios, is definitive and will NOT repeat across the rail. Duplicate tiles can be specified. 16x9, 4x3, 3x2, 2x3, 4x5, 1x1, 3x1, 4x1:
These are fixed aspect ratios for tiles, and will be shown in the order they are selected
Examples: Single aspect ratio:
4x3
Result: [4x3] ... Multiple aspect ratios:
4x3, 16x9
Result: [4x3] [16x9] ... Multiple aspect ratios with duplicates:
16x9, 4x1, 16x9
Result: [16x9] [4x1] [16x9] ...
|
visible
| boolean | | The visible setting acts as a simple flag that allows the client to show or hide a rail without removing it from the template or layout. true: The rail will be displayed to the user within the layout. false: The rail will be hidden from view but still remains part of the template. It can be toggled back to true later without needing to modify the layout or template structure.
|
Custom components
The following fields are all within the configurationProperties block.
Application
Keys | Type | Values | Description |
|---|
type
| static | application
| Defines the type of the rail item. An application represents a third-party app (such as YouTube, Netflix, or Prime Video) that can be launched from the interface. |
title
| string | | The title field represents the user-friendly display name of the application. This is the name that will be shown to the user in the appropriate UI element(s), such as in a rail or other content listings. For localisation, use the format "i18n.title.{locale}" in the client_context field to define translations for each locale. The client_context array should include entries like "i18n.title.en_GB": "Spotify" and "i18n.title.ja_JP": "スポティファイ", allowing the title to be displayed correctly across different regions and languages. |
background_colour
| hex colour | | Specifies a background colour for the application tile. |
stb_androidtv_package_id
| string | | The package ID used to reference the application on Android TV STBs. Example: com.amazon.amazonvideo.livingroom |
stb_linux_id
| string | | The identifier for referencing the application on Linux-based STBs. |
mobile_android_package_id
| string | | The package ID for referencing the application on Android mobile devices. Example: com.amazon.avod.thirdpartyclient |
mobile_ios_bundle_id
| string | | The bundle ID for referencing the application on iOS devices. |
mobile_ios_store_id
| string | | The ID for redirecting to the app store in the scenario that the application is not installed on iOS devices. |
integrated_linux_id
| string | | The identifier for referencing the application on integrated Linux-based environments. |
Pre-installed application
Keys | Type | Values | Description |
|---|
type
| static | application
| Defines the type of the rail item. An application represents a third-party app (such as YouTube, Netflix, or Prime Video) that can be launched from the interface. |
title
| string | | The title field represents the user-friendly display name of the application. This is the name that will be shown to the user in the appropriate UI element(s), such as in a rail or other content listings. For localisation, use the format "i18n.title.{locale}" in the client_context field to define translations for each locale. The client_context array should include entries like "i18n.title.en_GB": "Spotify" and "i18n.title.ja_JP": "スポティファイ", allowing the title to be displayed correctly across different regions and languages. |
background_colour
| hex colour | | Specifies a background colour for the application tile. |
stb_androidtv_package_id
| string | | The package ID used to reference the application on Android TV STBs. Example: com.amazon.amazonvideo.livingroom |
stb_linux_id
| string | | The identifier for referencing the application on Linux-based STBs. |
mobile_android_package_id
| string | | The package ID for referencing the application on Android mobile devices. Example: com.amazon.avod.thirdpartyclient |
mobile_ios_bundle_id
| string | | The bundle ID for referencing the application on iOS devices. |
mobile_ios_store_id
| string | | The ID for redirecting to the app store in the scenario that the application is not installed on iOS devices. |
integrated_linux_id
| string | | The identifier for referencing the application on integrated Linux-based environments. |
Feature banner
Keys | Type | Values | Description |
|---|
type
| static | feature_banner
| Defines the type of the rail item. A feature_banner is a visually prominent content item intended for promotional purposes, typically featuring an image and an optional navigation action. |
template_id
| template selector | | When action is template_navigation, this field specifies the template to navigate to when the feature banner is selected. |
When using a feature banner within a rail, the rail must also have a key/value pair section to specify the display image to be used (either Internal image or External image (see below).
Keys | Type | Values | Description |
|---|
type
| static | promo_banner
| Defines the type of the rail item. A promo_banner is a visually prominent content item intended for promotional purposes, typically featuring an image and an optional navigation action. |
url
| string | | The URL to direct the user to on interaction |
When using a promotional banner within a rail, the rail must also have a key/value pair section to specify the display image to be used (either Internal image or External image (see below).
Advertisement Banner
Keys | Type | Values | Description |
|---|
type
| static | advertisement_banner
| Defines the type of the rail item. An advertisement_banner is a visually prominent content item intended for promotional purposes, typically featuring an image and an optional navigation action. |
ad_server_url
| string | | The ad_server_url field is a string that specifies the URL from which the advertisement content is served. This URL is provided by the ad server (e.g., Google Ad Manager, Amazon Publisher Services) and is used by the client to retrieve the advertisement and related assets (such as images, videos, or interactive elements). It may also include tracking information for impression and click tracking, as well as other parameters necessary for rendering the ad correctly. This URL serves as the endpoint for fetching the ad creative and other relevant details (e.g., targeting parameters, ad placement information) and ensures that the client connects to the appropriate ad server for content delivery. |
refresh_interval
| numeric (0 to 86400) | | The refresh_interval field is a numeric value that defines the interval, in seconds, at which an advertisement or content should be refreshed or reloaded. The value can range from 0 to 86,400 seconds (24 hours). A value of 0 indicates that the ad or content should not be refreshed automatically, while values greater than 0 specify the time in seconds after which the ad or content will be refreshed. This is particularly useful for dynamic or rotating ads that need to update regularly to show fresh content or prevent stale creative from being shown. Valid Range: Example values: 0 (No refresh – the ad will remain static until explicitly refreshed by the client or user interaction)
60 (Refresh every 60 seconds)
300 (Refresh every 5 minutes)
|
Key/value pair groups
The following fields are all within the configurationProperties block.
Logo configuration (rail)
Keys | Type | Values | Description |
|---|
type
| static | logo_configuration_rail
| The type field categorises this blueprint as logo branding, defining how brand logos are applied within a rail. |
When applying a logo configuration (rail) KVP group to a rail, the rail must also have a key/value pair section to specify the display image to be used (either Internal image or External image (see below).
Logo configuration (rail content)
Keys | Type | Values | Description |
|---|
type
| static | logo_configuration_tile
| The type field categorizes this blueprint as logo branding, defining how brand logos are applied within a rail. |
logo_tile_position
| enum | center,
top_left,
top_right,
bottom_left,
bottom_right
| The logo_placement_tile_position field specifies the position of the brand logo within the content tile. You can select one of the following options: center: The logo is placed at the center of the content tile. top_left: The logo is placed as an overlay in the top-left corner of the content tile. top_right: The logo is placed as an overlay in the top-right corner of the content tile. bottom_left: The logo is placed as an overlay in the bottom-left corner of the content tile. bottom_right: The logo is placed as an overlay in the bottom-right corner of the content tile.
|
When applying a logo configuration (rail content) KVP group to a rail, the rail must also have a key/value pair section to specify the display image to be used (either Internal image or External image (see below).
Client-side processing
This is a marker to indicate to the client they should render the contents on the client side, fetching more data as needed. Each app implementation may have bespoke components with this behaviour. If the app does not have code to handle this item it should ignore it entirely.
Keys | Type | Values | Description |
|---|
type
| static | clientside
| The type field defines the category of KVP group. The clientside type serves as a marker indicating that the rail requires bespoke processing either in addition to, or instead of, that of a standard rail. Depending on the requirements, these special rails: May have content added to them in the normal manner May require the client to build the entire rail structure itself May require additional / different processing of the content and/or the entire rail May require any mix of the above
This allows for greater flexibility in content presentation, filtering, and personalisation based on user interactions, preferences, or local device conditions. Unlike static rail types that retrieve and display predefined content, clientside enables real-time modifications without requiring back-end updates. It can be used for features such as dynamically generated recommendations, locally cached content, or interactive filtering within a rail. |
identifier
| string | | The identifier is a unique string used by the client to determine the specific client-side logic or rendering behavior required. This allows the client to distinguish between different variations of the same type and apply the appropriate processing, layout, or interaction patterns. |
client_context
| array (string) | | The client_context is an optional field that provides additional contextual hints related to the KVP group use case. Each entry in the array represents a specific hint or configuration detail for the client to interpret, and each may affect how the blueprint is rendered or interacted with. |
Internal image
Keys | Type | Values | Description |
|---|
type
| static | internal_image
| The type field defines the category of KVP group. The internal_image value indicates to the client this is a group containing information for images accessed via the platform’s internal image service. |
image_type
| enum | logo,
banner,
background
| The image_type field specifies the category of image being defined within the group. This helps differentiate between various visual elements used within the UI. logo – Represents a logo, typically used as a small, recognisable mark placed within the rail or on content tiles. banner – Represents a wider branding element, often spanning across sections of the screen rail to provide stronger brand association. background – Represents a full-background image, used to set the overall visual theme behind the rail’s content.
|
reference
| string | | The reference to an internal image stored within the platform’s image service. This is the default image for the image_type unless specific light or dark variants are provided. |
alt_text
| string | | The alt_text field provides alternative text for the logo, intended to describe the logo for users who rely on screen readers, such as TalkBack. This ensures accessibility for visually impaired users by providing a meaningful description of the logo's content or purpose. The text should be clear, concise, and relevant to the brand or application, allowing users to understand what the logo represents. For localisation, use the format "i18n.alt_text.{locale}" in the client_context field to define translations for each locale. The client_context array should include entries like "i18n.alt_text.en_GB": "Spotify logo" and "i18n.alt_text.ja_JP": "スポティファイ ロゴ", ensuring the alt text is appropriately localised across regions and languages. |
External image
Keys | Type | Values | Description |
|---|
type
| static | external_image
| The type field defines the category of KVP group. The external_image value indicates to the client this is a group containing information for images accessed via externally hosted URLs rather than being stored within the platform’s internal image service |
image_type
| enum | logo,
banner,
background
| The image_type field specifies the category of image being defined within the group. This helps differentiate between various visual elements used within the UI. logo – Represents a logo, typically used as a small, recognisable mark placed within the rail or on content tiles. banner – Represents a wider branding element, often spanning across sections of the screen rail to provide stronger brand association. background – Represents a full-background image, used to set the overall visual theme behind the rail’s content.
|
scale_factor
| numeric (-100 to +100) | | Values other than 0 mean the client must provide the specified level of scaling on the image. |
url
| image | | Specifies the direct URL to an externally hosted image. This is the default image for the image_type unless specific light or dark variants are provided. |
alt_text
| string | | The alt_text field provides alternative text for the logo, intended to describe the logo for users who rely on screen readers, such as TalkBack. This ensures accessibility for visually impaired users by providing a meaningful description of the logo's content or purpose. The text should be clear, concise, and relevant to the brand or application, allowing users to understand what the logo represents. For localisation, use the format "i18n.alt_text.{locale}" in the client_context field to define translations for each locale. The client_context array should include entries like "i18n.alt_text.en_GB": "Spotify logo" and "i18n.alt_text.ja_JP": "スポティファイ ロゴ", ensuring the alt text is appropriately localised across regions and languages. |
Android Channels API
Keys | Type | Values | Description |
|---|
type
| static | android_channels_api
| The type field defines the category of KVP group. The android_channels_api type serves as a marker indicating that the content for this rail should be sourced dynamically using the Android Channels API rather than being predefined within the back-end. The Android Channels API is part of the Android TV home screen experience, allowing apps to create and manage custom content channels (rails) that integrate seamlessly with the launcher. While the layout and structure of the rail can still be configured within the blueprint, the actual content population is controlled by the client through API calls. This enables flexible, real-time updates to live TV, on-demand content, or personalised recommendations, aligning with the Android TV user experience. |
stb_androidtv_package_id
| string | | This field specifies the package name of the Android app associated with the set-top box (STB) that is calling the Android Channels API. The package name is a unique identifier for the app on the Android platform, ensuring that the correct app is referenced when interacting with the API. For example, for Amazon Prime Video on Android TV, the package name would be com.amazon.amazonvideo.livingroom. |
