Developer Portal

Cloud Solution Fundamentals

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

Cloud Solution Architecture

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

Note

Due to special technical limitations and considerations for the Roku platform at this time, these apps must be developed in coordination with You.i TV as part of a development agreement. This approach ensures the best practice approach and app performance.

If you are interested in building apps for Roku with You.i Engine One, contact your You.i TV representative for more information.

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 the You.i Engine 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.
  4. The client consumes the Component Library from S3 storage.
  5. 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 TV Cloud Solution operates. Consider them when developing an app for a Roku platform:

Images

Static images that are normally bundled with the app (for example, AE assets) are stored in S3 to reduce the client package size. When testing an app locally, you must use the AE export process and manually upload static assets to S3. See Copying Static Assets to S3.

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.

Note

You.i TV testing has uncovered that some Roku device models may cause issues with resizing video.

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 Engine 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 must 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 Engine React Native apps).

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 Engine React Native APIs may be available.

Dynamic Updates and Facebook React Native Components

You.i Engine 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 TV's Cloud Solution currently offers varying degrees of support for dynamic attributes. Refer to Facebook React Native Supported Components and You.i Engine React Native 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 the You.i Engine'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":""
},
...
}

Note

There are a few React Native components, including Button, TouchableHighlight and TouchableOpacity, whose disabled property has a known issue in the current version supported by You.i Engine One, in which disabling the component does not remove it from the focus map. To remove or add these comps from the focus map, you'll need to manually toggle their focus through the FocusManager. See the examples below:

<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 Engine 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 Engine 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. When testing an app locally, you must export the static assets from AE and then copy them manually into the static_assets folder in the appropriate bucket in S3 (for example, to the static_assets folder in the my-application bucket). See Copying Static Assets to S3.