Roku Design Guidelines

• UI Resolution
• Channel Assets
• Roku-wide settings
• Roku remote control buttons
• UI
• Video player
• In-App Purchases

• App Tracking
• Account Creation
• Login
• Deep linking
• Certification Criteria
• Rokus ideas on Guidelines and best practice

Supported Screen Sizes

Roku supports three resolutions for application user interface, SD only channels are not permitted.

Supported resolutions are defined in the manifest:

Recommended intended resolution

• for SceneGraph applications Roku recommends to design for an intended 1080p resolution
• for performance supply both 1080p & 720p graphical images

Safe Zones

Recommended areas to ensuring the edges of your TV screen do not cut off the interface.

Title Safe Zone - 80% scale of UI resolution

• The FHD Title Safe Zone is 1534x866, offset from the upper left corner (0,0) by 192, 106
• The HD Title Safe Zone is 1022X578, offset from the upper left corner (0,0) by 128,70

Action Safe Zone - 90% scale of UI resolution

• The FHD Action safe zone is 1726x970, offset from the upper left corner (0,0) by 96, 53
• The HD Action safe zone is 1150X646, offset from the upper left corner (0,0) by 64,35

Automatic screen element scaling

UI Autoscaling is a feature on Roku that allows developers to ensure that their channels look good and are legible on different screen sizes and resolutions. This feature automatically scales the user interface to fit the screen size and resolution of the device the channel is running on.

Here's how it works:

1.  The Roku device reports its screen size and resolution to the channel when it launches.
2.  The channel uses this information to determine the appropriate scaling factor for the user interface.
3.  The channel applies the scaling factor to all user interface elements, including images, text, and other graphical elements.
4.  The channel also adjusts the layout of the user interface elements to fit the new scaled dimensions.

It is however possible to manually override automatically scaled images or UI-elements.
The autoscaling for the maskgroup size is not working properly.

Auto Scaling Guideline Rule of Thumb

• Always design for FHD (1920 x 1080px)
• Position element on 3-pixel boundaries
• Choose an element size that is divisible by 3

Following these guidelines minimises visual anomalies caused by floating point rounding errors.

There are values within Rokus settings that should be queried and leveraged by your channel.
For example: Closed Captions, Language/Localisation.

Star/Options button

The Star/Options button is used to reveal contextual options by displaying menus and pop-up dialogs. However, there are limitations to its use. When a video is playing in full-screen mode, pressing this button prompts a Roku pop-up dialogue that offers users a number of standardised options, such as audio tracks and subtitles.

Instant replay button

The instant replay button on a Roku remote allows you to quickly replay the last few seconds of the video you're watching. When you press the instant replay button once, the video will skip back a few seconds (10-25 seconds), allowing you to re-watch a specific moment or catch something you might have missed. The rewind time can be programatically defined. 

This feature is particularly useful when watching sports or other live events where you may want to review a play or moment. It can also be helpful when watching a movie or TV show and you want to quickly re-watch a scene to better understand what's happening. The user will then continue watching with an offset of x seconds or can skip ahead to live viewing. 

Expected behaviour:

While on a standard UI screen:

• No action

During video playback: 
 Pressing instant replay button rewinds the video 10–25 seconds and resume playback, the amount of time rewound takes into account that users may not have the remote at the ready straight away.
 
During music playback:

•  Restart current track from beginning.

ℹ️ Info

Users have the option to enable closed captioning during Instant Replay in the Roku settings. The rationale behind this feature is that users often rewind to catch what was said. Therefore, when using Instant Replay, the last 20 seconds of the video will be replayed with closed captioning activated solely for that section of the replay.

Additionally, certain Roku remotes lack an Instant Replay button. To ensure the feature's accessibility, it can also be made available by pressing the first left dPad during video playback. If users press the dPad left more than once in quick succession, the standard dPad behaviour during video playback should be reinstated.

Rounded corners

There are no rounded corners on Roku. But there are two concepts that make it work anyway: 

9-Patch images
Also known as a nine-patch, is a specially designed image file that is commonly used to create resizable images with stretchable areas. A good use case are buttons with rounded corners.

MasksGroups
The MaskGroup allows an alpha mask bitmap to be applied to the rendering of its children, this is particularly useful for fades and rounded corners on rectangles. Support is limited to players that support OpenGL.

⚠️ Attention

• not possible to use 9-patch images as masks.
• masks will only work on rectangles if the opacity is below max
• auto resizing/converting from FHD to HD does not work on masks; a function is needed to aid scaling

Drop Shadow or Blur

There are no native blur or shadow effects that Roku offers. Shadows can be added using 9-patch images.

Animation

Any integer or float value can be animated. This way the position, opacity and size of an element can be animated. 
Roku also offers a predefined BufferSpinner which rotates an image.
There is no default support for Gifs, inline videos or Lottie-like animations.

Images bigger than the device resolution

When loading images bigger than the current UI the App can start blinking. This can be fixed by setting the loadWidth/loadHeight attribute of the Poster element.

Keyboard

Up until the voice control feature has been added to the list of mandatory feature, it was possible to show and hide a keyboard similar to an iOS-App from the bottom of the screen. 
With the voice control keyboard the predefined DynamicKeyboard is the most reliable option. The dynamic keyboard contains of a keyboard and an input field, which leads to a fullscreen keyboard view.

Voice Control

(Certification Criteria #4.12)
Roku voice keyboards must be used for email, PIN and password entry.

RFI popup
When trying to enter an email-address a Roku native RFI screen is displayed on top of the channel, prompting the user to grant Roku access to share their information with the channel. Only if the user declines this a form is displayed to manually enter their information.

HTML rendering

Roku does not support rendering web content. 
By limiting the complexity to certain tags and using a HTML-syntax which is also valid XML it is possible to render HTML as XML manually.

Row-list Do's & Don'ts

• Do: Each row can have a different height
• Do: Each Item in a row has the same height
• Do: It is possible to scale an item up, but only within the boundaries of it's container.
• Don't: It is not possible to scale an item and move other items out of the way.

When using the Video Node on Roku there is two ways to work with the Player UI. Either use it or hide it completely. The native settings menu will and should always be available via Star/Options key. When building a custom PlayerUI the Remote-specific features and the native behaviour should be taken into account.

Trick play

(Certification Criteria #4.7)
Thumbnails must be displayed during trick play for VOD content longer than 15 minutes.

Roku Advertising Framework (RAF)

• RAF library built into the Roku SDK
• Roku likes ads to be cancellable
• no user interactions while ad is playing
• Supported features of popular ad formats

Roku in-app purchases allow users to buy digital content or services within a Roku channel. This feature enables channel owners to monetise their content by offering additional features, subscription services, or one-time purchases.  The user has to always be logged in before making in-app purchases.

There are four IAP-product options with different price tiers to choose from:

• Monthly subscription
• Yearly subscription
• One-time purchase (once) e.g. purchasing a movie or TV-Show
• One-time purchase e.g. purchasing channel credit

Roku Pay

Request for information (RFI) and order confirmation screens are provided by Roku Pay and can't be modified.

On device account creation

(Certification Criteria #2.2)
If a channel requires authentication, it must carry out account sign-ups and sign-ins using On-device authentication exclusively, without redirecting users to an external webpage. The sign-up and sign-in processes must not contain links to promotional or marketing material that is hosted off-device, nor may they employ off-device sign-up or sign-in mechanisms like rendezvous linking.

On device up-/downgrade

(Certification Criteria #2.2)
Authenticated transactional channels **must complete upgrades and downgrades on the device using Roku Pay to pass certification**. Channels need to add a product group to enable and facilitate upgrades and downgrades, and they should block the on-device upgrade/downgrade flow if the subscription was not created through Roku Pay. Channels must also follow certain steps to handle on-device upgrades and downgrades via Roku Pay, including creating a product group and using the Roku Pay validate transaction API.

Type of subscriptions

Channels implementing Roku Pay can only offer monthly and annual subscriptions through subscription video on demand (SVOD) channels. SVOD channels can create one or more monthly and annual subscription products, offer free-trials and discounts, and schedule limited-time offers. Monthly and annual subscriptions can further be organised into product groups to support on-device upgrades/downgrades and prevent customers from accidentally being double-billed for the same service.

Screen Flow for subscription IAP

1. Landing page (clear about prices, highlight free trials/offers), 
2. RFI screen (Roku pay built-in) must be displayed in sign-up flow to pass certification, 
3. Plan selection screen, 
4. Order confirmation screen

The Roku Analytics Component Library (RACL) incorporates various third-party analytics solutions, such as Google Analytics, Omniture, and Ooyala Analytics, to name a few. This library offers an effortless means of integrating SceneGraph channels with one or more of these analytics solutions.

(Certification Criteria #2.3)
Channels that require users to log in and have streamed more than one million hours per month on average over the past three months, as well as new channels that are expected to reach this threshold soon after launch, are required to implement Automatic Account Link in order to pass certification. This requirement applies to TVE channels that use Adobe Primetime Authentication.

(Certification Criteria: #5)
Roku Deep linking is a feature of the Roku platform that allows developers to link directly to specific content within a Roku channel, rather than just launching the channel itself. With deep linking, users can be taken directly to a specific piece of content within a channel, bypassing the need to navigate through menus and search for the content manually.

• typically sent from content discovery features (e.g. search, voice, targeted display ads)
• Deep link requests contain two key parameters: contentid and mediaType
• a contentId is a URL-encoded ASCII string (maximum 255 characters) that uniquely identifies content in a channel. The contentId may be an alphanumeric string, URL, or pipe-separated key-value pairs
  (for example, series=myAwesomeShow|Season=1|Episode=1)

ContentId

• episodic content, Roku Search only recognises the episode contentid
• the contentid in the Roku Search feed (PlayID) must map to the contentid in your channel for the same content

⚠️ Attention
When dealing with episodic content, Roku Search only recognises the contentID of each individual episode. As a result, the contentID for an episode must remain consistent whether it is launched via a deep link or an episodic picker screen. The different deep-link behaviours are determined solely by the media type, and any separate contentIDs used to identify the season and series of the same content item are consequently ignored.

• The mediaType specifies how a channel should behave when receiving a deep link request.

Deep linking behaviour by media type

• short form and tv-specials: content launched directly into playback
• movies: launched directly into playback - bookmarks are used to determine playback position
• television series: contain a set of related episodes, deep linking behaviour based on media type:
• episode: episode is launched directly into playback with bookmarks
• season: channel launches content springboard organised by season with season highlighted, the episode should launch into playback
• series: launches most appropriate episode into playback using smart bookmark
• Best practice: save bookmarks in backend, in order to have bookmarks available on all devices linked to the same Roku account
• smart bookmark: determine best episode to play based on viewing experience with series
  (eg. in-progress episode is launched at current position, next episode if previous completed, S1E1 is launched if never started)

ℹ️ Info

(Certification Criteria #3.7)
To pass certification an app size of 4 MB must not be exceeded.

• Designing Roku channels
• Best practices