Cloud Events and Commands

A Cloud app is composed of two main components, the client and the server. These components use a TCP socket connection to communicate with each other.

The server sends commands to the client, instructing the client to perform some action (such as displaying a new screen). The client sends event notifications to the server (such as a button press), allowing the server to respond, if needed.

The following diagram illustrates how the client and the server communicate.

When you create a Cloud app, some events and commands are sent automatically. We call these “standard” events and commands.

The following diagram shows some of the events and commands that are sent automatically when a Cloud app is run.

You can look at the client and server logs to see some of these messages. To learn how to access these logs, check out our client logs and server logs documentation.

Standard events

Some of the most common standard events:

• Key - a user input event
• Video Complete - sent when the state of the video changes to Completed
• Open Keyboard - sent when the keyboard dialog is opened
• Persistent Store - used to store key-value pairs on the client
• Ping - pings the server to check the status of the TCP connection

One of the most common standard events is the key event - triggered each time the user presses a key on the remote control.

A key event is sent using the BrightScript method sendObjectAsJSON like this:

sendObjectAsJSON({ event: "key", key: "ArrowUp" })

The structure of an event is a JSON object that contains the event property with the name of the event and some extra parameters, if needed. In this example, the key parameter containing the key name is also present.

Standard commands

Some of the most common standard commands:

• Video commands - changes the state of the video player (play, pause, stop, seek)
• Kill - closes the client app
• Version - checks that the client is running a version compatible with the server
• Wait Spinner - shows the wait spinner with the configured delay (2 sec)
• Update Node Properties - updates a node from the SceneGraph on the client
• Ping - pings the client to check the status of the TCP connection

The structure of a command is very similar to an event: it’s a JSON object that contains the command property with the name of the command and some extra arguments, if needed.

{"command":"waitSpinner","arguments":{"visible":true,"delay":2000}}

See also Debugging Cloud Events and Commands.

Listening for Cloud client events

To listen for key events on the server, use the Input Module to add an event listener with a callback function for any specific key, such as the ArrowUp key.

The following code sample shows how to listen for key server events for a React Native app. Note that you can achieve the same functionality for a C++ app.

import { FormFactor, Input } from "@youi/react-native-youi";

// ...

handleArrowUpEvent = (event) => {
    if (event.eventType === "up") {
        console.log("EVENT: ArrowUp");
    }
};

componentDidMount() {
    Input.addEventListener(Input.Event.ArrowUp, this.handleArrowUpEvent);
}

componentWillUnmount() {
    Input.removeEventListener(Input.Event.ArrowUp, this.handleArrowUpEvent);
}

Sending commands to the Cloud client

To send a command, you can use the Cloud Module. The Cloud Module APIs expose several methods to send commands.

For example, to show the wait spinner on the Client, call the showWaitSpinner method from the Cloud Module. By default, the wait spinner appears after 2 seconds, but you can change the delay value using the setSpinnerDelayMs method.

import { NativeModules } from "react-native";

const Cloud = NativeModules.Cloud;

// ...

Cloud.showWaitSpinner();

Commands are handled on the Client (BrightScript). The following code sample shows how the showWaitSpinner command is handled.

sub waitSpinnerCommand(command as object)
  logMessage("WaitSpinnerCommand - show")
  showDelayedWaitSpinner(command.delay)
end sub