Developer Portal

Working With the Cloud Module

The Cloud module exposes the following APIs that are needed when developing an app for Roku. For details, see Cloud Solution APIs.

The Cloud module has two parts: Cloud and CloudConfig.

  • The Cloud module can be included in all You.i Engine One apps. When the Cloud module is included in a build for non-Roku target platforms (such as Android or tvOS), isCloudServer returns false.
  • The CloudConfig module should be included only when the YI_CLOUD_SERVER flag is set.

To enable Cloud Solution:

In your app.cpp file, ensure that the ReactNativeViewController code is as shown below:

 #include <YiCloudModule.h>
#if (YI_CLOUD_SERVER)
#include <YiCloudConfigModule.h>
#endif
...
//Initialize PlatformApp::UserInit()
//Add the module must be done after UserInit()  
bool userInitSuccess = PlatformApp::UserInit();

//Add the module 
GetReactNativeViewController().AddModule<Cloud>();

#if YI_CLOUD_SERVER
//For Roku Cloud 
GetReactNativeViewController().AddModule<CloudConfig>();
#endif

//Perform rest of App::UserInit()
...

//Return value from earlier PlatformApp::UserInit()
return userInitSuccess;				
				

Call the cloud module using the Cloud keyword: Cloud.setDefaultCloudKeyboardTitle("My default title");

To execute certain code blocks or function calls for the Roku target platform, use the isCloudServer boolean. For example:

if (Cloud.isCloudServer)
{
	FocusManager.enableFocus(this.list);
	FocusManager.setNextFocus(this.list, this.list, "right");
}					

Note

NativeEventEmitter.Cloud starts a clientBackgrounded event whenever the Roku client starts playback or is inactivated. Import NativeEventEmitter as follows:

import {NativeEventEmitter, NativeModules} from 'react-native';
const cloudEventEmitter = new NativeEventEmitter(NativeModules.Cloud);

 

isCloudServer

Boolean that is true if the implementation is a cloud server. Allows a multi-platform app to make a runtime check to execute cloud-specific behavior. For details, see Cloud Solution APIs.

isLowEndDevice

Boolean that is true if the device has lower capabilities. For details, see Cloud Solution APIs.

Due to the wide range of supported Roku hardware, You.i TV recommends that you follow Roku guidance; that is, design for high-end devices and then gracefully degrade the experience for low-end hardware. This can include removing more complex assets from scenes, using smaller image sources, and so on.

rokuExternalIp

String with the external IPv4 address of the Roku client. For details, see Cloud Solution Geo Location and Restriction.

terminateApplication()

Terminates the app and returns to the home screen. For details, see Cloud Solution App Exit with Back Button.

showWaitSpinnerNow()

Shows the wait spinner immediately without the configured delay of 2 seconds. For details, see Customizing the Wait Screen and Activity Indicator.

setSpinnerDelayMs(uint32_t delayMs)

Sets the time of spinner delay in milliseconds. delayMs is the spinner delay duration in milliseconds. If hideWaitSpinner() is called within the duration, spinner won't show. The default value for spinner delay is 2000 ms. For details, see Customizing the Wait Screen and Activity Indicator.

showWaitSpinner()

Shows the wait spinner with the configured delay (2 secs). The wait spinner can be used in one of following scenarios:

  • When an app is launched
  • When playback buffers for starting, seeking, and resuming
  • When scene export takes more than 2 secs

For details, see Customizing the Wait Screen and Activity Indicator.

hideWaitSpinner()

Hides the wait spinner. For details, see Customizing the Wait Screen and Activity Indicator.

setDefaultCloudKeyboardTitle(std::string title)

Sets the default title of the Roku keyboard, as specified by title.

Example: Cloud.setDefaultCloudKeyboardTitle("My default title");

setCloudKeyboardTitle(uint64_t tag, std::string title)

Sets the title of the Roku keyboard for a particular view.

Example: Cloud.setCloudKeyboardTitle(findNodeHandle(this.textview2), "Element Title 2!");

pauseExportUpdates()

Pauses the automatic scene tree export process. Until resumed, changes to the scene tree do not result in automated exports. For details, see Developing You.i Engine React Native Apps for Cloud Solution.

resumeExportUpdates()

Resumes the automatic scene tree export process. Changes to the scene tree again result in automated exports. For details, see Developing You.i Engine React Native Apps for Cloud Solution.

areExportUpdatesPaused(Callback boolean)

Returns true if the automatic scene export process is paused. For details, see Developing You.i Engine React Native Apps for Cloud Solution.

exportScreen() (Deprecated)

This has been deprecated. Use exportSubtree() as a substitute.

exportSubtree(uint64_t tag)

Triggers the export of the given subtree to the client. A common use of this method is to update the content data of a list. For details, see Developing You.i Engine React Native Apps for Cloud Solution.

Example: exportSubtree(pListView, true)

sendFocusMap()

Updates the client's focus map because focus relationships between scene components have changed. For details, see Cloud Solution APIs and Focus Map.

setInitialScrollIndex(uint64_t tag, uint32_t index)

Sets the start of a list to be at the specified index, instead of starting from the first list item. For example, if a list has 20 list items and you specify an index of 7, the list starts from list item 7 instead of the first list item. For details, see Roku List Development.

setInitialScrollIndexWithFocus(uint64_t tag, uint32_t index)

This API does the following:

  • Sets the start of a list to be at the specified index, instead of starting from the first list item.
  • Sets focus to be on the list item associated with the specified index. (The focus request is delayed until after the Roku client receives the new scene graph update.)

Call this API with the onload() method, otherwise app behavior may be incorrect.

For details, see Roku List Development.

getRokuUserAccount(Callback resolvePromise, Callback rejectPromise)

Request the Roku user account (partial user data of email address). This is an asynchronous network operation. The appropriate callback function is invoked when complete. For details, see Cloud Solution In-app Purchases.

getRokuChannelCred(Callback resolvePromise, Callback rejectPromise)

Request the Roku ChannelCred event. Includes the Roku Partner Unique Customer Identifier. This is an asynchronous network operation. The appropriate callback function is invoked when complete. For details, see Cloud Solution In-app Purchases.

getAvailableProducts(Callback resolvePromise, Callback rejectPromise)

In-app purchase request of available products for the channel. This is an asynchronous network operation. The appropriate callback function is invoked when complete. For details, see Cloud Solution In-app Purchases.

getUserPurchases(Callback resolvePromise, Callback rejectPromise)

In-app purchase request of user purchases. This is an asynchronous network operation. The appropriate callback function is invoked when complete. For details, see Cloud Solution In-app Purchases.

requestPurchase(folly::dynamic args, Callback resolvePromise, Callback rejectPromise)

In-app purchase request to purchase a given product. This is an asynchronous network operation. The appropriate callback function is invoked when complete. For details, see Cloud Solution In-app Purchases.

EnqueuePostExportAction(Callback actionPromise)

Queues an action to be executed after the next scene export.

GetLastPlaybackSessionInfo()

Gets the recently updated playback session information, such as bookmark and audio/cc settings.

invokeCommand(cmd: string, args: object): Promise<any>

Invokes the custom BrightScript command.

The first parameter is a BrightScript command name as a string. The second parameter is an object for the You.i RN Cloud Solution app to send key-value pairs of arguments. Note that the arguments must be JSON serializable and must only contain one of the following types: string, bool, or array/object containing string and bool. The third parameter is a callback that is called with the result of the custom command.

setIncomingFocusStyle(uint64_t tag, folly::dynamic style)

Allows you to specify which list item will have focus when a user enters a list. The usage examples provided are for ListRef, but usage is similar for List. Possible values:

closest

Description: Move focus to the closest list item. The closest item is computed locally on the client to keep request latency low.

Usage: Cloud.setIncomingFocusStyle(findNodeHandle(this.listRef), "closest")

previousItem

Description: Move focus to the item that was selected the last time this list had focus. The list item is computed locally on the client to keep request latency low.

Usage: Cloud.setIncomingFocusStyle(findNodeHandle(this.listRef), "previousItem")

server

Description: The You.i Engine Cloud server computes where focus should go inside of the list. This setting gives you focus behavior that exactly matches other platforms, but it results in higher network request latency.

Usage: Cloud.setIncomingFocusStyle(findNodeHandle(this.listRef), "server")

setOutgoingFocusStyle(uint64_t tag, folly::dynamic style)

Allows you to specify where focus moves when a user exits a list. The usage examples provided are for ListRef, but usage is similar for List. Possible values:

closest

Description: Move focus to the node closest to the list item, based on the size of the list item. The node is computed locally on the client to keep request latency low.

Usage: Cloud.setOutgoingFocusStyle(findNodeHandle(this.listRef), "closest")

As shown here, closest moves focus to the node that's closest to the list item:

Set focus to the item closest to the list item

closestToList

Description: Move focus to the node closest to the list, based on the size of the whole list. The node is computed locally on the client to keep request latency low. This setting is equivalent to the After Effects composition hint outgoingFocusStyle:focusMap.

Usage: Cloud.setOutgoingFocusStyle(findNodeHandle(this.listRef), "closestToList")

As shown here, closestToList moves focus to the node that's closest to the center of the list:

server

Description: The You.i Engine Cloud server computes where focus should go when leaving the list. This setting gives you focus behavior that exactly matches other platforms, but it results in higher network request latency.

Usage: Cloud.setOutgoingFocusStyle(findNodeHandle(this.listRef), "server")