Cloud Module

The Cloud module exposes APIs that are needed when developing an app for Roku.

Jump right to the APIs

About the Cloud Module

The Cloud module has two parts: Cloud and CloudConfig.

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

Enabling the 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()
//Adding 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");
}

Cloud Module APIs

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.

isLowEndDevice

Boolean that is true if the device has lower capabilities.

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 Geo Location and Restriction.

terminateApplication()

Terminates the app and returns to the home screen. For details, see 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, the spinner won’t show. The default value for the 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.

setWaitSpinnerAccessibilityAttributes()

Makes the wait spinner accessible, so that the Audio Guide automatically makes an announcement when the activity indicator is displayed. 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.

announceText(std::string announcement)

Announces the specified text on the client. Note that the Audio Guide must be enabled on the Roku device.

To learn more about creating accessible Roku apps, see Roku Accessibility.

Example: Cloud.announceText("Some text");

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 Roku Development.

resumeExportUpdates()

Resumes the automatic scene tree export process. Changes to the scene tree again result in automated exports. For details, see Roku Development](/6.15/rn/plan/roku-considerations/).

areExportUpdatesPaused(Callback boolean)

Returns true if the automatic scene export process is paused. For details, see Roku Development.

exportScreen() (Deprecated)

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

exportSubtree(uint64_t tag, bool unused)

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 Roku Development.

Example: exportSubtree(findNodeHandle(this.listRef), true)

sendFocusMap()

Updates the client’s focus map because focus relationships between scene components have changed. For details, see Focus Map.

setInitialScrollIndex(uint64_t tag, uint32_t index) (Deprecated)

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.

Note React Native apps on Roku Cloud no longer require the Cloud module’s setInitialScrollIndex method for lists, and it has been deprecated as of You.i Platform version 6.0. In anticipation of the removal of setInitialScrollIndex in a future release, we recommend using initialScrollIndex as you would have on other RN apps, as it now works the same on all RN-supported platforms. For implementation details, refer to the 6.0 Migration Guide.

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 In-app Purchases.

getRokuChannelCred(Callback resolvePromise, Callback rejectPromise)

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

saveRokuChannelCred(Callback resolvePromise, Callback rejectPromise)

Store the Roku ChannelCred event. Includes the Roku client in-app purchase channel credentials. This is an asynchronous network operation. The appropriate callback function is invoked when complete. For details, see In-app Purchases.

getAvailableProducts(Callback resolvePromise, Callback rejectPromise)

In-app purchase request of available products for the channel. getAvailableProducts returned data includes information such as product name, product description, product poster URL, free trial type, free trial quantity, purchase date, product type and quantity. This is an asynchronous network operation. The appropriate callback function is invoked when complete. For details, see 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 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 In-app Purchases.

EnqueuePostExportAction(Callback actionPromise)

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

SendAppBeacon(const CYIString &beaconName) (deprecated)

Sends an app beacon of the provided name to the Roku client.

SendPlatformAnalyticsEvent(PlatformAnalyticsType type, const CYIString &eventName)

Roku requires all applications to send certain analytics events. These mandatory analytics aren’t related to any application-side business logic. These events must have one of the following types:

• Application events, which are converted by the Roku client into App Beacon messages
• Authentication events, which are converted by the Roku client into either Roku Event Dispatcher or Roku Ads Framework messages, depending on settings in the Roku manifest file

Roku does not dictate the name of these events or when they must be sent; this is completely up to the application developer.

Examples

CYICloud::GetInterface().SendPlatformAnalyticsEvent(CYICloudInterface::PlatformAnalyticsType::Application, "AppLaunchComplete");

CYICloud::GetInterface().SendPlatformAnalyticsEvent(CYICloudInterface::PlatformAnalyticsType::Authentication, "Roku_Authenticated");

GetLastPlaybackSessionInfo()

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

invokeCommand(cmd: string, args: object): Promise

Invokes the custom BrightScript command.

The first parameter is a BrightScript command name as a string. The second parameter is an object used by the 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 Roku 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:

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 Roku 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")