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.

Note

The Cloud module has been split in two: Cloud and CloudConfig. As described above, the Cloud module is designed to be included even in non-cloud builds. When used in non-cloud builds, isCloudServer is false. All other APIs can be called without any issues. You need to make the following changes in the App.cpp file for your app to work with You.i Engine One:

    • The Cloud module should not be enclosed inside the YI_CLOUD_SERVER flag as done previously, because the cloud module can be used by non-cloud builds also. The new CloudConfig module should only be included in cloud builds as shown below:
      #include <YiCloudModule.h>
      #if (YI_CLOUD_SERVER)
        #include <YiCloudConfigModule.h>
      #endif
    • The CloudConfig module, instead of Cloud module, should be added to ReactNativeViewController in the #ifdef YI_CLOUD_SERVER build flag. Therefore, GetReactNativeViewController().AddModule<Cloud>(); should be changed to GetReactNativeViewController().AddModule<CloudConfig>();.

Previously, the cloud module was only available on the Roku builds of the React Native projects using the following import statements:

import { NativeModules } from 'react-native';
const Cloud = NativeModules.Cloud;
		

For non-Roku builds, the Cloud module was not available. So any calls to the cloud APIs had to be wrapped with a check if the Cloud module existed:

if (Cloud) {
	NativeModules.Cloud.setDefaultCloudKeyboardTitle("My default title");
}

But now, the cloud module is always present, even for the non-Roku builds. This means it can always be safely called without a need to do any checks before calling it.

The Cloud module is still included in the code in the same way as done previously as shown below:

import { NativeModules } from 'react-native';
const Cloud = NativeModules.Cloud;
	

But now you can call it using the Cloud keyword instead:

Cloud.setDefaultCloudKeyboardTitle("My default title");
		

If you want to check whether the code blocks or the functions calls are only for the Roku target platform, it is no longer sufficient to check if the Cloud module exists. The isCloudServer boolean must now be always checked as shown below to verify before making any functions calls:

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

Note

NativeEventEmitter.Cloud starts an clientBackgrounded event whenever the Roku client starts playback or is inactivated. To import NativeEventEmitter, do the following:

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

Following is the list of APIs that are part of the Cloud module:

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 return 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 resolvePromise)

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

exportScreen()

Manually triggers the export of all views on the screen. For details, see Developing You.i Engine React Native Apps for Cloud Solution.

exportSubtree(uint64_t tag, bool useJSON)

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.

exportAsNativeListView()

Forces the export of a list as a Roku's default native list. Automatically causes the client to update its SceneGraph. The default one is exportAsComponentScrollingView. When using exportAsNativeListView, remember the following limitations:

  • A Roku list can use only one template. If needed, separate a list into multiple lists, one for each template used. Lists of lists are an exception. The individual child lists can use only one template each. The template can vary from child list to child list. The parent list can use multiple templates.
  • An ideal Roku list item template consist of 2-4 views.
  • Each list item template must contain only one PushButtonView.
  • Lists on Roku always hard clip items that exceed the top boundary. Ensure list item layouts do not exceed the bounds of the root list composition.
  • Padding between list items is not supported. You.i TV recommends you create empty space within the list item template.
  • No items should exceed the boundaries of the root list composition. For example, do not animate any element outside the root list composition boundary. Although there is no clipping in between list items, adjacent list items can overlap in undesirable ways if boundaries are exceeded. For example, a gradient image may overlap an adjacent list item if its width is too large.
  • List item views for a given list must be of the same size.
  • ImageNodeIn animations on list items should be removed in AE.
  • You.i TV recommends using non-animated scrolling if scrolling across many list items as animated scrolling will have poor user experience.
  • Due to limitations of the native Roku list component, a single renderItem must be used for FlatLists.
  • Animations on list items are not supported on Roku using Facebook React Native components.
  • Currently, buttons and touchables in lists or scrolled views will not respond to dynamic property changes.
  • Set initialNumToRender equal to the number of items in the list. Otherwise, only the visible content is exported.
  • Various scrollTo functions, such as scrollToEnd, scrollToIndex, scrollToItem, and scrollToOffset, do not work on the carousel lists.
  • Calling scrollTo functions repeatedly on a list with magnets results in unexpected behavior.

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()

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, args, callback)

Invokes the custom BrightScript command.

The first parameter is a BrightScript command name as a string. The second parameter is a folly::dynamic 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 string, int, float, and bool elements. The third parameter is a callback that is called with the result of the custom command.