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. For C++ apps, add the following code to your SplashScreenViewController. (You.i TV recommends it be inside BuildView):

CYICloud::GetInterface().SetExportHint(pSceneView, HINT::EXCLUDE_NODE, true);

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:

Roku with You.i Engine Cloud app's default wait screen

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.

For the API information related to spinner delay time in You.i Engine C++ Roku apps, see CYICloudInterface Class Reference.

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 CYICloudInterface::SetWaitSpinnerAccessibilityAttributes as follows:

CYICloudInterface::SetWaitSpinnerAccessibilityAttributes(CYIAccessibilityAttributes::Accessible accessible, std::unique_ptr<CYIAccessibilityAttributes> pAttributes)

For example:

bool accessible = true;
std::unique_ptr<CYIAccessibilityAttributes> pAccessibilityAttributes = std::make_unique<CYIAccessibilityAttributes>();
pAccessibilityAttributes->SetLabel("My loading indicator");
pAttributes->SetRole(CYIAccessibilityAttributes::Role::ProgressBar);
pAttributes->ReplaceStates({{CYIAccessibilityAttributes::State::Expanded, true}, {CYIAccessibilityAttributes::State::Selected, true}});
pAccessibilityAttributes->SetHint("auto dismisses once loading completes");
CYICloud::GetInterface().SetWaitSpinnerAccessibilityAttributes(accessible, std::move(pAccessibilityAttributes));

See also CYICloudInterface Class Reference.

Customizing the InternetDownDialog component

You can customize the InternetConnectionDown.xml definition for the dialog box, which is displayed when the internet connection is detected to be down or there is a network issue between the Cloud Solution’s client and server for the app on the Roku platform. The dialog box is not displayed if the internet connection is down while a video is being played because the Roku target platform handles this case with its own dialog box.

To customize the message that is part of the InternetDownDialog component, which is displayed when network issues are detected, update the message.xml file. The message.xml file is located at <youi-engine>/src/cloud/resource. The message can be modified in the resource/message.xml using the networkDown key, such as:

<networkDown>
   <description>Unable to communicate with service.</description>
   <title>Network Error</title>
   <instruction>Check networking equipment status or press Home button to exit</instruction>
</networkDown>

To change the look and feel of the dialog box, such as using different color or font, customize the InternetDownDialog.xml file. The file can be found at <youi-engine>/src/cloud/components/.

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.
  • useStaticNodeID: The default is false. It should be set to true when using HINT::STATIC_ID. This feature is supported for C++ apps 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.