How to Implement External HTTP Callbacks

You can make HTTP calls into the GameSparks platform either from external servers or from your own processes. When these calls are made, you can execute some custom Cloud Code to do whatever processing you need:

The HTTP request can either be a GET or POST request, and all parameters passed to the server are accessible via the Spark.getData() function.
If you pass query string parameters on a POST request, both sets of values are accessible:
- Single parameters are passed to JavaScript as Strings.
- Multiple parameters with the same name are passed to JavaScript as a String array.
POST parameters are only interpreted into the data object when the content type of the request is "multipart/form-data". For other usages see the Reading POST Data section below.

Set SparkHttp timeout! The default timeout for SparkHttp calls is 30 seconds but we strongly recommend that you set this at 5 seconds or lower. If there's any delay in receiving a reply from the endpoint, then waiting for the default 30 second period could seriously impact your Cloud Code's performance. You can use Spark.getHttp() to set the timeout.

Creating Cloud Code to Handle Requests

To create a script to handle the request from the Cloud Code page, under Scripts select System, and use Callback URL.

The Callback URL

https://{apiKey}.{stage}.gamesparks.net/callback/{apiKey}/{credential}/{serverSecret}/{playerId}

stage : "preview" or "live" (depending on whether you are accessing the live servers or not).
apiKey : The API Key of you game.
credential : The name of the credential you want to use to connect.
serverSecret : The server secret of your game, accessible from the Configurator > Credentials page.
playerId(optional) : The ID of the player. If this is supplied, then Spark.getPlayer() will be the player specified.

Trailing Slash Required! If you don't pass a playerId, you still need to include the / after your serverSecret.

Adding Parameters

For a GET request, you can add parameters to the query string that are passed to your script. For example:

https://{apiKey}.{stage}.gamesparks.net/callback/{apiKey}/{credential}/{serverSecret}/{playerId}?attr1=abc&attr2=bcd&attr2=cde

With this URL, the following code can be used to access these parameters:


    //attribute1 is a string
    var attribute1 = Spark.getData().attr1;

    //attribute2 is an array
    var attribute2 = Spark.getData().attr2;

    //attribute2[0] is bcd
    //attribute2[1] is cde

Producing Response Body

Using Script Data to Send Back JSON Response

The scriptData object from the callback script is written to the output stream as a JSON document.


    Spark.setScriptData("key1", "value1");
    Spark.setScriptData("key2", "value2");

This will generate the JSON output:


    {
        "key1": "value1",
        "key2": "value2"
    }

Using RESPONSE_RAW for Text-Based Output

If you do not want to write JSON but want to use your own text-based output, setting a value with the key "RESPONSE_RAW" in script data will override the JSON output and return this value directly;


    Spark.setScriptData("RESPONSE_RAW", "OK");

Will generate the response as :

OK

Note: If you use setScriptData and not RESPONSE_RAW, then RESPONSE_HEADERS is a reserved word so it won't appear in the JSON output.

Producing Headers

Setting Response Headers

You can set response headers in the output:


Spark.setScriptData("RESPONSE_HEADERS", {"myHeader":"myValue"})

Other ways to set ResponseHeaders:

You can specify the Content-Type Response Header by passing in the following parameters: contentType and characterEncoding like this:

https://{apiKey}.{stage}.gamesparks.net/callback/{apiKey}/{credential}/{serverSecret}/{playerId}?contentType=yourContentType&characterEncoding=UTF8

If these parameters are passed in but the Content-Type is also passed-in in the RESPONSE_HEADERS, the RESPONSE_HEADERS will be used.

Reading POST Data

There are instances where a remote server may not set the content-type header correctly, and the post data are not automatically translated into Spark.getData(). In these cases, the POST requests have an additional "REQUEST_BODY" attribute set into Spark.getData(). This is the body of the HTTP post request as a string, so you can do your own parsing of this value:

    var rawPostData = Spark.getData().REQUEST_BODY