Roku Cloud Solution Fundamentals

This topic describes concepts that you need to understand to create Roku apps.

Cloud Solution Architecture

You.i Roku Cloud Solution allows developers to create high performance Roku apps with React Native or C++ without coding with Roku’s BrightScript language.

The Cloud Solution provides a unique user experience for any Roku app user. The following diagram illustrates the architecture behind the Cloud Solution:

The Roku device contains only a small generic app that acts as a client of a cloud-based server. App logic runs on the cloud-based server along with You.i Platform and a set of APIs. The cloud-based app logic sends screen instructions to the client through the APIs. The APIs converts app screen instructions into a format that the Roku device can consume. The client connects to the cloud-based server through a TCP socket.

The Cloud Solution uses Amazon Simple Storage Service (S3) to store the app’s screens as a series of zip files that the client can consume. A given screen is stored in a single zip file, which is a Roku Component Library. S3 is also used to store a copy of the app’s static assets, such as AE images.

A typical sequence of operation is:

1. The client sends selection events from the user to the cloud-based app logic. The events drive app operation.
2. The cloud-based server generates the zip files and copies them to S3 storage once a screen is staged.
3. The server sends the client an instruction to display the screen along with the tokenized URL to the Component Library.

The Cloud Solution uses Amazon Simple Storage Service (S3) to store the app’s screens as a series of zip files that the client can consume. A given screen is stored in a single zip file, which is a Core Component Library.

A typical sequence of operation is:

1. The client consumes the Component Library from S3 storage.
2. The client consumes video and other dynamic content directly from the back-end CMS service.

Cloud Solution Architecture Implications

The previous architecture implies the following:

• There is much more networking between the different components of the solution (cloud server, AWS S3, and Roku client).
• There are more points of failure.
• Latency and data size (for example, scene complexity and image size) are important considerations.
• It is more complex to set up.
• The AWS S3 servers currently are all in the US. Geo-checking needs to use the Roku device’s IP address, which is available through an API.
• There is 1:1 scaling between the Roku client and the cloud server.
• The code containing the app logic is not required to fit within the memory footprint of a Roku device.

Anatomy of a Cloud Solution App

In a traditional app, all of its components are bundled together into one package. In a Cloud Solution app, its components are in multiple locations:

• The cloud server contains the app’s logic
• An S3 bucket contains the app’s static images

• The Roku client contains the following app components:

  • fonts
  • Splash screen
  • Roku channel icon
  • Activity indicator
  • manifest configuration file, for setting items such as the app name, networking info, ads, and DRM
  • BrightScript source files

The following topics describe details about how the You.i Roku Cloud Solution operates. Consider them when developing an app for a Roku platform:

• Images

• Video Playback

• Dynamic Updates

• Focus Map

• Client-Server Interaction:

  • Export Process
  • C++ App Modal Scene
  • Static Assets

Images

Static images that are normally bundled with the app (for example, AE assets) are stored in S3 to reduce the client package size.

Static assets are stored in the static-assets subfolder of the application’s bucket.

Dynamic images are provided by the CMS service as in the base application. The Component Libraries refer to them so that the client can download them directly.

Video Playback

When the app starts a video, the Cloud Solution sends the client a PlayVideo command with the tokenized URL and required metadata. The video is streamed directly from the client’s local Roku player.

Custom onscreen controls for video playback are not supported at this time because all playback and associated controls are handled by the client’s local Roku player.

To pass Roku certification, the app must support state-based play (bookmarking) for videos longer than 15 minutes. The app must be able to receive bookmark events from the Roku client, pass to a restful endpoint, and resume video playback at the bookmarked time.

Dynamic Updates

If the contents of the screen changes (for example, list contents change due to a search), the host application sends commands to the client to have it update its local scene.

The Cloud Solution can automatically detect and update the following changes to the You.i Platform scene tree:

• animations starting
• node visibility changes
• text field changes
• image URI changes
• focus root changes

Changes to CYIListView contents can be updated dynamically; however, the host application sometimes need to contain additional code to explicitly trigger the update through calls to the Cloud Solution API (for C++ apps) or to Cloud native module methods (for You.i React Native apps). For more information, see Roku List Development.

For increased performance, the Cloud Solution also informs the client of partial scene tree updates.

Although scene updates normally operate automatically, you may want to control the behavior of the partial scene tree export algorithm in some situations; for example, when the contents of a list changes over several frames. The Cloud Solution and the Cloud native module offers APIs to:

• Pause and resume scene tree updates
• Query to find out if updates are paused
• Manually trigger the export of all staged scenes

Additional C++ or You.i React Native APIs may be available.

Dynamic Updates and Facebook React Native Components

You.i React Native component attributes are either static or dynamic in nature:

• Dynamic attributes: Their values can change during app execution in response to an event or a change in conditions.
• Static attributes: Their values are declared by JSX code or by After Effects settings.

You.i Roku Cloud Solution currently offers varying degrees of support for dynamic attributes. Refer to UI Components for more information on specific component attributes.

The support level for dynamic attributes reflects the current nature of the Cloud Solution that depends on having a relatively static screen with respect to visual changes made by the application. These visual changes could be a result of events or some custom render behavior. Visual changes appear on the Roku client only after the app logic exports a new component library and instructs the Roku client to display it.

Focus Map

To improve performance, local focus navigation is handled entirely by the client. The Roku Scenegraph API does not provide automatic focus navigation (except within lists). The Cloud Solution leverages You.i Platform’s focus system to pre-calculate the focus relationships; that is, the focus neighbors of every view. These relationships are called the Focus Map. It is sent to the client immediately after a new component library is exported and the cloud-based server has a view with focus. The following is an example:

{
  "nodes":[
    {
      "name":"Btn-Settings[224033]",
      "up":"Btn-Page-Browse[224035]",
      "down":"",
      "right":"ListOfLists[5]",
      "left":""
    },
    {
      "name":"Btn-Page-Browse[224035]",
      "up":"Btn-Page-Search[224036]",
      "down":"Btn-Settings[224033]",
      "right":"ListOfLists[5]",
      "left":""
    },
    ...
}

  <Button
    ...
    ref = {(ref) => {
      this.refButton = ref;
    }}
  />

  updateFocus(focus) {
    ...
    FocusManager.setFocusable(findNodeHandle(this.refButton), focus);
  }


  <TouchableHighlight
    ...
    ref = {(ref) => {
      this.refTouchable = ref;
    }}
  />

  updateFocus(focus) {
    ...
    FocusManager.setFocusable(findNodeHandle(this.refTouchable), focus);
  }

Client-Server Interaction

Client server interactions include the export process and the handling of static assets.

Export Process

Once a screen is staged, the Cloud Solution exports all staged scenes into a format that the client can read (that is, a SceneGraph Component Library). For You.i React Native apps, if there are any dynamic updates made after the scenes are exported, the Cloud Solution updates the exported scenes dynamically in the SceneGraph.

Typically, the format is an XML representation of the screen content. The export is made by traversing the nodes in the You.i Platform scenes and creating a matching document, substituting in the Roku SceneGraph node types. The following is an example:

<Rectangle
  id="Dark_Blue_Solid_3_01"
  translation="[0.0,0.0]"
  scaleRotateCenter="[639.999939,359.999969]"
  scale="[1.0,1.0]"
  rotation="0"
  opacity="1"
  width="1279.9999"
  height="719.99994"
  color="0x353537FF"
/>
<Group
  id="Mover_04"
  translation="[359.999207,359.999969]"
  scaleRotateCenter="[0.0,0.0]"
  scale="[1.0,1.0]"
  rotation="0"
  opacity="1">
    <CYIScrollingView
      id="ListOfLists_040"
      size="[1279.999878,719.999939]"
      translation="[-95.999992,-359.999969]"
      scaleRotateCenter="[639.999939,359.999969]"
      scale="[1.0,1.0]"
      rotation="0"
      opacity="1"
      direction="vertical">

In some cases there are no matching Roku node types. In such cases, the document uses custom node types; for example, CYIScrollingView in the previous snippet. The exported scenes are bundled into a zip file for that screen; for example, Lander.zip. Each zip file is a Roku Component Library. Ideally, the Component Library would be transferred to the Roku device with a TCP socket; however, BrightScript does not yet support TLS on TCP for Component Libraries. The Component Library is therefore copied to Amazon S3 instead. The client is then given the command to load the new Component Library from the Amazon S3 URL; for example, https://s3.amazonaws.com/trutvdev-store/.../featured.zip.

If you use the JSON export strategy, remember that the JSON-based transfer is faster for smaller updates, but may be slower for large updates.

C++ App Modal Scene

A modal scene is a scene that is displayed over an existing staged scene (for example, an overlay or notification dialog that is shown above a PDP).

For C++ apps, there are two approaches to exporting modal scenes. The first and simplest is to do nothing, and let the staging of the overlay trigger a component library transfer. This approach can work well for an app with a very simple UI.

The second and recommended approach is to register each modal with the Cloud Solution. The modals are exported with all component libraries so that they are available at any time in app code. Once registered, staging such an overlay no longer triggers a new component library transfer. See AddModalScene() in CYICloudInterface Class Reference.

Static Assets

Working with static assets with a cloud-based application is similar to the traditional development workflow with one additional step.