Running Server Extensions from Unity 3D

One of the advantages of Kii Cloud is that it exposes all of its APIs as a REST web service. This is not only useful for developers using Kii Cloud from platforms that don’t have a dedicated SDK, but also gives developers the chance to use new features before they are officially released in the SDKs.

Let’s take a look at an example: calling Server Extensions from Unity 3D using the REST API. Since Unity 3D is the most recent addition to Kii’s platform, it is still catching up with some of the newest features like Server Extensions. Server Extensions allow developers to extend the functionality of Kii Cloud by deploying javascript code to create new, custom endpoints. So if there’s something that the API does not support by default you can extend it.

Deploying Server Extensions

First of all you need to create an app at developer.kii.com following these steps:

1. Create an account at http://developer.kii.com
2. Create an application as explained in “Register an application” following steps 1, 2, and 3 (disregard the other sections): http://documentation.kii.com/en/starts/unity/
3. Note the App Id, App Key, Client Id and Client Secret assigned to your app as explained in “Register an application” following step 4 (disregard the other sections): http://documentation.kii.com/en/starts/unity/

Now it’s time to deploy a Server Extension. Let’s create a simple echo service (It will give us back the message we send as parameter). Create a file called echo.js with the following content:

function echo(params, context) {
    return params.message;
}

Note: the function name “echo” will be the endpoint name (see next section)

We’ll use Kii server tool to deploy it (look for the icon with a cloud here https://developer.kii.com/#/sdks). Switch to the server tool directory from the command line, execute the following after adding your app’s keys (assuming you selected US for location of your app):

node bin/kii-servercode.js deploy-file --file echo.js --site us --app-id YOUR_APP_ID --app-key YOUR_APP_KEY --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

Done! Your server extension is ready to be called.

Calling Server Extensions

In order to be able to talk to Kii’s REST API we need to be able to send POST HTTP requests with proper headers, data and endpoint information. In order to do this we’re going to use the native Unity 3D class WWW (so no 3rd party HTTP classes are needed) and a little bit of help from an extra class to encode/decode JSON.

The class WWW will help us send an HTTP request to Kii Cloud API using POST. This request will require the following data:

• Kii App Id and App Key (you get these when creating an app on developer.kii.com)
• Name of your custom endpoint (the name of the JS method you created) so you call the right server extension (you can have multiple methods doing different things)
• Your JSON data (if your server extension uses parameters as input)
• (Optional) A Kii user authentication bearer (a token) if you want to run the server extensions as an authenticated user rather than anonymously (you can get this token after signing in a user using Kii Cloud)

The code to call the server extension will look more or less like this (assuming you configured your app on developer.kii.com to be hosted in the US):

public static WWW RunServerExtension (string appId, string appKey, string endpoint, string kii_access_token, string msg)
{
	WWWForm form = new WWWForm();
	Hashtable headers = form.headers;
	headers["Content-Type"] = "application/json";
	headers["x-kii-appid"] = appId;
	headers["x-kii-appkey"] = appKey;
	if(kii_access_token != null)
		headers["Authorization"] = "Bearer " + kii_access_token;
	form.AddField("message", msg);
	Hashtable data = new Hashtable();
	data["message"] = msg;
	string json = JSON.JsonEncode(data);
	Debug.Log("Sending: " + json);
	byte[] bytes = Encoding.UTF8.GetBytes(json);
	return new WWW("https://api.kii.com/api/apps/" + appId + "/server-code/versions/current/" + endpoint, bytes, headers);
}

Note that the method takes your app’s App Id and the App Key that you wrote down in previous steps. It’s important that you use the same method name that you use in your extension as the endpoint parameter (in this case it’s “echo“).

This call will not block the game since we’re running WWW in a Coroutine (the execution is yielded until we get a response from the server).

If you want to try this out you can download our demo project KiiUnityREST and run the Init scene after configuring your app keys using the Kii Game Cloud top level editor menu.

This is all for now. This technique allows you to have the best of both worlds in Unity, a dedicated SDK plus any REST API call!

On my next blog post I will show you how to send push notifications from Unity also via Kii REST API. Stay tuned!

Unity 3D Developer? Sign up to our contest and win 10K in prizes!!

Kii Cloud is a full-stack mobile backend to accelerate iOS, Android, HTML5 and Unity app development. Optional ad network integration is available to help you monetize. Get started with a free account at developer.kii.com