Interpreting rails responses

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:

Basic rails concepts
The structure of the template and rail responses
The fields that are returned and how this affects what the client should display

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:

A promotional banner
Three curated content items
Five recommended content items

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:

sections block:
- In a template response, this is always an empty array.
- In a rail response, it contains the actual rail contents and metadata.
hasNext:
- In a template response, this is always null.
- In a rail response, it has a value of true or false to indicate whether more content is available.
session block – not present in template response.

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. standard_strip: A `standard_strip` type defines a rail that is single height and multi-tile. It typically represents a straightforward content strip with tiles of uniform height (width can vary if required), presented in a linear fashion.
`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: A long list of movies or shows that users can scroll through without limitations
`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: `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] ...`
`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 (default): 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_more`field 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: `max_pages: 0` This would allow the client to continue fetching additional pages as long as more content is available, without any artificial limitations. 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 (default): 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` (the default): 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 (default): 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_more`field 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: `max_pages: 0` This would allow the client to continue fetching additional pages as long as more content is available, without any artificial limitations. 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 (default): 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.

Promotional strip

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: Arrows: To move to the next or previous items. Dots: To show the number of available items and the current position within the carousel. Carousels are ideal for highlighting specific content, ensuring that the user’s attention is drawn to a select few items within the strip. Notes: The carousel layout is highly flexible, and the navigation controls (arrows, dots) are not defined in this blueprint but should be implemented as needed by the client.
`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 (default): 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.

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

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.

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.

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.

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.

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

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.

Overview

Basic rails concepts

Templates and layouts

Rails and rail sections

Blueprints

Custom components

Key/value pair groups

Ad-hoc key/value pairs

Typical call flow

Rail fields

Differences between template and rail responses

Common fields

Blueprints

Standard strip

Magazine strip

Promotional strip

Custom components

Application

Pre-installed application

Feature banner

Promotional banner

Advertisement Banner

Key/value pair groups

Logo configuration (rail)

Logo configuration (rail content)

Client-side processing

Internal image

External image

Android Channels API