Functionality of Server Code

Kii Cloud provides four methods for executing server code. All of them are described in this topic. You can pick the most suitable one for your application needs.

For all methods, you will run your logic by specifying an endpoint defined in server code. An endpoint is a JavaScript function having the type defined by the server extension.

See the following example. This is an endpoint named funcName that returns a string of "Hello!" (For more information about the syntax, see Server Code Syntax).

function funcName(params, context) {
  // Your code comes here...
  return "Hello!";
}

You can write any processes required for your service, such as calls to the Kii Cloud SDK and external servers in your server code. Specify the endpoint name funcName as an API parameter or in the configuration file that is used to call the endpoint.

One endpoint can be executed by multiple methods. For example, you can run an endpoint on a scheduled basis and also run the same endpoint manually whenever needed.

Manual operation

You can invoke server code deployed in Kii Cloud via the mobile app API and run it on the server. Only the execution result will be sent to the mobile app as a response.

The following figure illustrates the overall flow of the manual operation (See Parameters for Manual Operation and Manually Executing Server Code for the detailed instructions).

In this example, the server code has two endpoints, add and sub and the client application invokes the endpoint add. The server code is executed on the server, and the result is sent to the client.

To prevent an infinite loop of server code executions, Kii Cloud returns an error if server code uses the Kii Cloud SDK or the REST API to call the server code.

Trigger-based hook

You can automatically run server code when data is updated in Kii Cloud. A data update event that causes server code to run is called a trigger. A trigger and its target endpoint are associated in the server hook configuration file.

With a trigger-based hook, you can build features like:

  • Loading initial data when a new user is created (e.g. loading welcome gifts to new game users).
  • Auto-aggregating data when a new KiiObject is created in a bucket.

The following figure illustrates the overall flow of the server code execution initiated by a trigger-based hook (See Parameters for a Trigger-based Hook and Trigger-based Hook for the detailed instructions). Note that the actual server hook configuration file is written in the JSON format.

The following table summarizes available triggers (See Trigger-based Hook for the complete list). In the server hook configuration file, you can put multiple sets of a trigger and a server code endpoint.

Target Available triggers
Bucket A KiiObject is created, deleted, or updated in the target bucket.
User A user is created or deleted, a user's email address or phone number is authenticated, a user's password is reset or updated, or a user's attributes are updated.
Group A group is created or added, or a member is added or removed.
Thing A thing is registered or unregistered, enabled or disabled, an owner is added or removed, or information of a thing is updated.
Installation A device is installed or uninstalled for receiving push notifications.

In all cases, you can get details of the data change (e.g., The User ID and URL of a newly created user, Object ID and URL of the modified bucket and KiiObjects) when server code is launched by a trigger.

To prevent an infinite loop of server code executions, data update caused by a trigger-based hook does not invoke another trigger-based hook. However, data update caused by server code executed manually can invoke a trigger-based hook.

Schedule-based hook

A schedule-based hook is useful for launching server code regularly on the designated date and time. You can use this feature, for example, to perform regular data cleanup and data aggregation.

As illustrated in the figure, you will define a pair of a server code endpoint and the time when the endpoint will be executed and specify the pair in the server hook configuration file (See Parameters for a Schedule-based Hook and Schedule-based Hook for the detailed instructions).

In this example, we set a schedule-based hook that would execute the endpoint cleanup with a parameter time = 3am on 3:00 (UTC) every day.

You can set multiple schedules on one endpoint so as to execute it in multiple timings. The execution time can be set by a combination of a month, a day of the month, hour, minute, and a day of the week, its repetition, or a list of combinations. For example, you can set a simple execution time profile such as every hour as well as a complex one such as every 11:00 and 16:00 on Saturdays and Sundays.

To prevent an infinite loop of server code executions, data update caused by a schedule-based hook does not invoke a trigger-based hook.

Thing-IF trigger

If you are building an IoT solution with the Thing-IF SDK, you can register a trigger to execute your server code automatically.

The trigger feature supported by the Thing-IF SDK will allow you to execute the designated action when the uploaded state satisfies the preset condition. By specifying the server code endpoint and the corresponding parameters in the action, you can let the trigger launch the server code automatically at the preset condition.

See Auto Execution with Triggers for the details of the Thing-IF trigger feature.

When you implement server code that is executed by a Thing-IF trigger, the implementation steps are the same as those for manual operation. Read the Thing-IF SDK guide to learn about the Thing-IF specific features, such as getting the execution result of server code.