Customizing Roku Apps

There are several ways to customize the design of app elements to allow your app to run on a Roku device.

Customizing the Splash Screen

Roku displays a static image as its Splash screen. To customize the splash screen, you need to:

1. Create a new static image to replace the default.
2. Update the Roku manifest file to point to your image.
3. Disable the Splash screen in your app.

Creating New Splash Screen Images

According to Roku’s Manifest Documentation, designers need to provide a single 1920 × 1080 splash screen image. If needed, the Roku device scales it down to the appropriate size depending on your display. Therefore, verify that your FHD image (1920x1080) looks good when resized to HD (1280x720).

You can use any file name; for example logo_FHD.png. Put the image files into your Roku client code base under client/images. See Roku Client Customization.

Updating the Manifest File Splash Screen Entries

Find the following section in your manifest file and update as follows, replacing the logo file name:

# Channel Assets
splash_screen_fhd=pkg:/images/logo_FHD.png

Disable Your App’s Splash Screen

Your app no longer needs to display the Splash screen because the Roku client does so instead. See the Roku Manifest Documentation for additional Splash screen properties that you may want to set.

Customizing the Channel Icon

The Roku channel icon (that is, the app icon) is located in the Roku client code base. You need to:

1. Create a new icon to replace the default.
2. Update the Roku manifest file to point to your icon file.

Creating a New Channel Icon

The channel icon must be a 320 x 180 PNG file.

You can use any file name. Put the icon file into your Roku client code base under /client/images. See Roku Client Customization.

Updating the Manifest File Channel Icon Entry

Add the following line to your manifest file, replacing the file name:

mm_icon_focus_hd=pkg:/images/my_icon.png

Customizing the Wait Screen and Activity Indicator

The default Wait screen looks like this:

The on-screen components are defined by the Roku manifest file. For details, see Roku Manifest File.

A default logo.png and loader.png files are included in the Roku client’s images folder.

The loader.png spins automatically. Not all Roku devices support arbitrary rotations. In particular, some hardware versions only support 90-degree rotation increments. In those cases, the image steps through 90 degrees, 180 degrees, 270 degrees and back to 0 degrees instead of spinning smoothly.

The default background color is 0xDF1D46FF, defined in the manifest file.

To customize the Wait screen, you need to change the default logo image. See Customizing the Roku Wait Screen Images.

You may want to also change the loader image and other screen attributes defined by the WaitMessage.xml file. See Customizing the Roku Wait Screen Images and Customizing the WaitMessage.xml File.

To customize the spinner delay time in You.i React Native Roku apps, see the Cloud Module APIs showWaitSpinnerNow(), setSpinnerDelayMs(), showWaitSpinner(), and hideWaitSpinner().

Customizing the Roku Wait Screen Images

Replace the logo and loader files in our Roku client images folder. The default Wait screen is hardcoded to use these filenames.

Customizing the WaitMessage.xml File

The WaitMessage.xml file contains a Roku SceneGraph that defines the appearance of the Wait screen. It is included in your client at build time. To customize the screen, put a copy of the XML file in your code base and modify it.

The default WaitMessage.xml file is located here: <youi_engine>/src/cloud/components/WaitMessage.xml

You.i TV recommends you put the XML file into your Roku client code base under /client/components. See Roku Client Customization.

For simple changes, you might want to make minor modifications by hand (for example, move the hardcoded location of an image).

For more complex changes, you might want to create your new screen in After Effects and run your screen through a scene export to create the Roku SceneGraph corresponding to your new screen.

Making the Roku Activity Indicator Accessible

You can make the Roku activity indicator accessible so that the Audio Guide automatically makes an announcement when the activity indicator is displayed. Once enabled, the default announcement is “Loading”, but you can customize this text. You can also toggle this feature and change the announced text at runtime.

Use the Cloud module method setWaitSpinnerAccessibilityAttributes() as follows:

Cloud.setWaitSpinnerAccessibilityAttributes(bool accessible, dynamicObject accessibilityAttributes)

For example:

let accessible = true
const accessibilityAttributes = {
  accessibilityLabel: 'My loading indicator',
  accessibilityRole: 'progressbar',
  accessibilityStates: ['expanded', 'selected'],
  accessibilityHint: 'auto dismisses once loading completes'
};
Cloud.setWaitSpinnerAccessibilityAttributes(
  accessible,
  accessibilityAttributes
);

See also Cloud Module and Accessibility.

Customizing Error and Info Dialogs

You can customize the messages displayed by the client as defined in resources/dialogDefs.json. The schema of each dialog type is described in resources/schemaDialogDefs.json. You can customize client dialogs by supplying alternate dialog definitions, as JSON-formatted data, based on the schema found in the You.i Platform package at src/cloud/resource/schemaDialogDefs.json. The default dialog definitions are provided in src/cloud/resource/dialogDefs.json.

There are three types of dialog: Application Error, Network Status, and AppInfo. Application Error dialogs are for errors that aren’t recoverable and result in application exit when the Home or Exit button is pressed. These errors include:

• applicationError: Generic application error.
• coreComponentFailure: Failure due to an error downloading core components.
• deviceAuthError: Failure of the application to authenticate with the infrastructure.
• serverConnectError: Failure of the client to connect to the service.
• sessionTimeoutMessage: Session timeout when the client is idle for an extended period of time.
• tcpConnectionError: Connection failure after successful connection to the service.
• unsupportedFirmware: The client has been launched on a device with an unsupported RokuOS version.

Networking errors are reported and dismissed automatically by RokuOS. Pressing the Home key in these cases exits the app. These errors include:

• linkDown: Reported by RokuOS when a link to the network is no longer available, for example, when the WiFi is down or the ethernet cable is disconnected.
• networkDown: Reported by RokuOS when the internet service is unreachable.

The Application Info dialog is displayed when the Options key is pressed outside of the Video playback screen. The appInfo dialog can be dismissed with the supplied Close button or Back key press.

To customize one or more of the above dialogs, copy the src/cloud/resource/dialogDefs.json file found in the You.i Platform package and paste it into your application’s AE/assets/json/default folder. You can then send the modified dialogs to the client using CYICloud::GetInterface().InvokeCommand("setCustomDialogDefs", dialogDefs), where the modified dialog definitions are contained in the CYIBundle dialogDefs parameter.

For C++, you can initialize the dialogDefs parameter from the JSON file as follows:

  const std::shared_ptr<yi::rapidjson::Document> pDocument(jsonOptions->GetJSONDocument());
  CYIString customDialogDefs = CYIRapidJSONUtility::CreateStringFromDocument(*pDocument);
  // Send custom dialog defs to client
  CYICloud::GetInterface().InvokeCommand("setCustomDialogDefs", customDialogDefs);

For React Native, customDialogDefs is the contents of the imported custom dialog definition JSON file that you send to the client with the following command:

Cloud.invokeCommand("setCustomDialogDefs", customDialogDefs);

The default dialog definition is used if a custom version is not present.

Each dialog allows a title, description, details, and a Close or Exit (application) button, as specified in the dialog schema. You can add the application name to the title by adding the string “{0}” where you want the name to appear. The description is a string that should be a short synopsis of the error. The details is a list of strings (in the form of an array (["Detail 1", "Detail 2", ...]) that will be displayed in bulleted format under the description. Details that include a parameter such as an errorCode, for example the code for a connection error, are specified by optionalDetails with the named parameter as the key.

Customizing the Cloud Solution Application Configuration File

The serverConfig.json file specifies what interface the Cloud Solution server should instantiate for a Cloud Solution app. The file can be found in the following app subdirectory: /AE/assets/json/default/

The following settings are supported. Some entries are present by default.

• interface: The default value is Roku OS.
• startImmediately: The default value is false. If true, the local host gets started before the Roku client connects. This setting should only be used for debugging. Note that you can also start the app immediately for debugging without the Roku client by launching the app executable from the command line with the -i option, as in ./MyApp -i.
• useFullNames: The default value is true. Only works with debug builds.
• useLocalHTTPServer: The default value is true. Only works with debug builds.
• clientListenPort: The default value is 54322.
• appVersion: The default is an empty string. It should be added for the release builds only.

The node added to serverConfig.json is treeObserverConfig. The structure is as follows:

"treeObserverConfig" : {
   "propertyChangesActive" : true

}

Note that propertyChangesActive is set to true by default. If false, all property updates are disabled for the app. This is useful when debugging, or for old apps that don’t require property changes.

Configuring Placeholder and failedImageUri Images

You should configure additional images for two situations:

• placeholder images while waiting for an image to load
• failedImageUri images when an image has failed to download or decode

Display a Placeholder Image While an Image is Loading

To display a placeholder bitmap image while an image is loading, put the placeholder image file in the client/images folder. The image must be a bitmap PNG file.

Specify this filename in a CYIImageView class component as placeholder:<filename>.

Display a failedImageUri Image When an Image URL Fails to Load

To display a failed image when an image URL failes to download or decode, put the failed image file in the client/images folder. The image must be a bitmap PNG or JPG file.

Specify this filename in a CYIImageView class component as failedImageUri:<filename>.