Spark

The Spark object that is available to all scripts is the entry point into the GameSparks API.

It can be used for getting access to objects and functions within the GameSparks platform.

This interface is available in all scripts using the notation "Spark."

e.g.

To return a JSON representation of the Object being acted upon

var data = Spark.getData();

getPlayer

signature getPlayer()

returns SparkPlayer

validity All except Global Message Scripts

Returns a SparkPlayer object that represents the player who either sent, or is going to receive the object that is invoking this script.

example

var player = Spark.getPlayer();

loadPlayer

signature loadPlayer(string playerId)

returns SparkPlayer

validity All Scripts

Returns a SparkPlayer object that represents the player that has the supplied GameSparks player ID.

params

playerId - the unique player identifier.

example

var player = Spark.loadPlayer(myplayerid);

loadPlayerByExternalId

signature loadPlayerByExternalId(string externalSystem, string externalId)

returns SparkPlayer

validity All Scripts

Returns a SparkPlayer object that represents the player that in the supplied external system has the supplied external ID.

params

externalSystem - the unique external system identifier, supplied as a two letter ID. The options are: {FACEBOOK:FB, AMAZON:AM, GAME_CENTER:GC

GOOGLE_PLAY:GY , GOOGLE_PLUS:GP, KONGREGATE:KO, PSN:PS, QQ:QQ, STEAM:ST, TWITCH:TC, TWITTER:TW, VIBER:VB, WECHAT:WC, XBOX:XB

XBOXONE:X1, NINTENDO:NX}

externalId - the player identifier in the external system.

example

var player = Spark.loadPlayerByExternalId("FB",myplayerexternalid);

getChallenge

signature getChallenge(string challengeInstanceId)

returns SparkChallenge

validity All Scripts

Allows a script to load a SparkChallenge object by it's ID.

This is mainly used on LogChallengeEventRequests where the ID of the SparkChallenge can be retrieved using Spark.data.challengeId.

params

challengeInstanceId - the unique challenge identifier.

example

var myChallenge = Spark.getChallenge(Spark.data.challengeId);

sendMessage

signature sendMessage(JSON data, SparkPlayer[] players)

returns void

DEPRECATED use Spark.message(extCode)

validity All Scripts

Sends a ScriptMessage to one or more spark Players.

The 'data' attribute of the SparkMessage will match the data parameter supplied.

params

data - the JSON Data to send.

players - the SparkPlayer array to send the message to.

example

Spark.sendMessage({"alert" : "You've just won a car!"}, myplayers);

sendMessageExt

signature sendMessageExt(JSON data, string extCode, SparkPlayer[] players)

returns void

DEPRECATED use Spark.message(extCode)

validity All Scripts

Sends a ScriptMessage to one or more spark Players.

The 'data' attribute of the SparkMessage will match the data parameter supplied.

The extCode parameter will be used to look up the configuration for the message from ScriptMessage Extensions

params

data - the JSON Data to send.

extCode - The short code of the ScriptMessage extension, if not found, the default ScriptMessage will be used.

players - the SparkPlayer array to send the message to. If empty or null no message will be sent.

example

Spark.sendMessageExt({"alert" : "You've just won a car!"},"CODE1" ,myplayers);

sendMessageWithoutPush

signature sendMessageWithoutPush(JSON data, SparkPlayer[] players)

returns void

DEPRECATED use Spark.message(extCode)

validity All Scripts

Sends a ScriptMessage to one or more spark Players. Push notifications will be supressed for this message

The 'data' attribute of the SparkMessage will match the data parameter supplied.

params

data - the JSON Data to send.

players - the SparkPlayer array to send the message to.

example

Spark.sendMessage({"alert" : "You've just won a car!"}, myplayers);

sendMessageById

signature sendMessageById(JSON data, string[] playerIds)

returns void

DEPRECATED use Spark.message(extCode)

validity All Scripts

Sends a ScriptMessage to one or more spark Players.

The 'data' attribute of the SparkMessage will match the data parameter supplied.

params

data - the JSON Data to send.

playerIds - An array of player id strings to send the message to.

example

Spark.sendMessage({"alert" : "You've just won a car!"}, myplayerids);

sendMessageByIdExt

signature sendMessageByIdExt(JSON data, string extCode, string[] playerIds)

returns void

DEPRECATED use Spark.message(extCode)

validity All Scripts

Sends a ScriptMessage to one or more spark Players.

The 'data' attribute of the SparkMessage will match the data parameter supplied.

The extCode parameter will be used to look up the configuration for the message from ScriptMessage Extensions

params

data - the JSON Data to send.

extCode - The short code of the ScriptMessage extension, if not found, the default ScriptMessage will be used.

playerIds - An array of player id strings to send the message to.

example

Spark.sendMessage({"alert" : "You've just won a car!"}, myplayerids);

sendMessageByIdWithoutPush

signature sendMessageByIdWithoutPush(JSON data, string[] playerIds)

returns void

DEPRECATED use Spark.message(extCode)

validity All Scripts

Sends a ScriptMessage to one or more spark Players.

The 'data' attribute of the SparkMessage will match the data parameter supplied. Push notifications will be supressed for this message

params

data - the JSON Data to send.

playerIds - An array of player id strings to send the message to.

example

Spark.sendMessage({"alert" : "You've just won a car!"}, myplayerids);

message

signature message(string extCode)

returns SparkMessage

validity All Scripts

Creates a SparkMessage object using the default configuration from the portal.

Providing an ext code allows different configurations to be used as th template.

params

extCode - (Optional) The extCode of a scriptMessageExtension, if null or not found the standard ScriptMessage configuration will be used.

returns

a SparkMessageobject

example

Spark.message("myExtCode"));

save

signature save(string collectionName, JSON document)

returns boolean

validity All Scripts

Saves a document to the named collection.

params

collectionName - the collection name to save the document to.

document - the document to save. If the document contains and _id field, and the collection already contains a document with the same _id it will be updated.

returns

true if the save was successful, false if there was an error

example

Spark.save("myCollection", {"key":"value"});

remove

signature remove(string collectionName, JSON query)

returns boolean

validity All Scripts

Removes a document or documents from the named collection based on the query.

params

collectionName - the collection name to remove the document from.

query - the query that determines what documents to remove

returns

true if the save was successful, false if there was an error

example

Spark.remove("myCollection", {"key":"value"});

find

signature find(string collectionName, JSON query)

returns JSON

validity All Scripts

Performs a query on the named collection using find (without a projection).

http://docs.mongodb.org/manual/reference/method/db.collection.find

params

collectionName - the collection to query

query - the mongo query. For details see http://docs.mongodb.org/manual/core/read-operations/

returns

The result of the query, can be a simple document or a list

example

Spark.find("myCollection", {"key":"value"});

signature find(string collectionName, JSON query, JSON projection)

returns JSON

validity All Scripts

Performs a query on the named collection using find (with a projection)

http://docs.mongodb.org/manual/reference/method/db.collection.find

params

collectionName - the collection to query

query - the mongo query. For details see http://docs.mongodb.org/manual/core/read-operations/

projection - the projection,

returns

The result of the query, can be a simple document or a list

example

Spark.find("myCollection", {"key":"value"}, {"projectionKey":"projectionValue"});

lock

signature lock(SparkChallenge challenge)

returns void

validity All Scripts

Locks a challenge for writing. Whilst the script 'owns' this lock no other script can modify the challenge

Useful for situations where there may be concurrent access required to a SparkChallengeObject.

Other scripts can continue to read the Challenge

If a Script gains a lock to the object, it will be released once the release method is called, or if the release method is not called, when the script terminates.

params

challenge - the challenge to lock

example

Spark.lock(mychallenge);

unlock

signature unlock(SparkChallenge challenge)

returns void

validity All Scripts

Unlocks the challenge.

This makes it available for other scripts to acquire a lock on it.

params

challenge - the challenge to unlock

example

Spark.unlock(mychallenge);

lockKey

signature lockKey(string lockName, number tryMillis)

returns boolean

validity All Scripts

Creates a lock on an arbitrary key. Whilst the script 'owns' this lock no other script can lock on the same key, and will be blocked until the lock is released.

Useful for situations where there may be concurrent access required to an object or data.

Locks are reentrant and recursive, i.e. if you lock the same key twice, you will need to call unlockKey() twice to completely release the lock.

Alternatively, an unlockKeyFully() call will release the lock regardless of how many times it has been locked by this thread.

Locks will always be released fully when the script terminates.

params

lockKey - a unique identifier for the lock

tryMillis - if another thread has the lock, how long to block and attempt to acquire the lock before giving up

example

var gotLock = Spark.lockKey(lockName, 0);

returns

true if the lock was acquired, false otherwise

unlockKey

signature unlockKey(string lockName)

returns boolean

validity All Scripts

Releases a lock on the given key, assuming it is held by this thread.

This makes it available for other scripts to acquire a lock on it.

Note that locks are recursive, i.e. if you have locked twice on this key, you must unlock twice before other scripts can gain this lock.

params

lockKey - the key that was previously locked

example

Spark.unlock(lockName);

returns

true if the lock was released, false otherwise

unlockKeyFully

signature unlockKeyFully(string lockName)

returns boolean

validity All Scripts

Fully releases all locks on the given key, assuming they are held by this thread.

This makes it immediately available for other scripts to acquire a lock on it, regardless of how many times you have locked it previously.

params

lockKey - the key that was previously locked

example

Spark.unlockKeyFully(lockName);

returns

true if the lock was released, false otherwise

hasScriptErrors

signature hasScriptErrors()

returns boolean

validity All Scripts

Allows the script to detect if there have been any script errors set during the request or response.

example

var hasErrors = Spark.hasScriptErrors();

setScriptError

signature setScriptError(string key, JSON value)

returns void

validity All Scripts

Allows an error to be added to either the request or a response being acted upon.

In the case of requests this will cause the request to be rejected. This is useful if you have some custom logic that needs to determine whether GameSparks should process the request.

The 'error' object of the Response or Message objects will contain an entry that matches the supplied parameters.

params

key - the key to the data

value - the data, can be either complex JSON or simple types

example

Spark.setScriptError("myerrorkey", {"test":12345});

getScriptError

signature getScriptError(string key)

returns JSON

Gets the value of the script error for the given key. In the case of response scripts this may have been set in the request.

params

name - The name in the name value pair

returns

a JSON object

example

var error = Spark.getScriptError("name");

removeScriptError

signature removeScriptError(string key)

returns void

Removes a value from a name value pair structure containing any script errors that have previously been set.

params

name - The name in the name value pair

example

Spark.removeScriptError("name");

removeAllScriptErrors

signature removeAllScriptErrors()

returns void

Removes all script errors that have been set

example

Spark.removeAllScriptErrors();

getLog

signature getLog()

returns SparkLog

validity All Scripts

Provides access to a SparkLog interface

example

var logger = Spark.getLog();

getPlayerIds

signature getPlayerIds()

returns string[]

validityGlobal Message Scripts

Messages are targeted to multiple players.

This method gives access to the ID's of all the target players.

This can be accessed in both Global Message Scripts and User Message Scripts

The ID's can in turn be used with getPlayer to access the player details

returns

An array of Id's

example

var playerIds = Spark.getPlayerIds();

logEvent

signature logEvent(string eventKey, JSON values)

returns void

validity All Scripts

Allows a script to post a LogEventRequest on behalf of the current player.

Can be useful to post a score to a global leaderboard when a score has been posted to a challenge.

params

example

Spark.logEvent("HS", {"HS":234});

getHttp

signature getHttp(string url)

returns SparkHttp

validity All Scripts

Provides access to a SparkHttp interface

params

url - the URL of the service to connect to

example

var httpSender = Spark.getHttp();

dismissMessage

signature dismissMessage(string messageId)

returns boolean

validity All Scripts

Allows a script to dismiss a given message.

Returns true if a message was dismissed. This method does not check if the message belongs to the current user.

params

messageId - the id of the message to dismiss

returns

true if the message was dismissed

example

Spark.dismissMessage("528b3411e4b09c9ee8497949");

metaCollection

signature metaCollection(string collectionName)

returns SparkMongoCollectionReadOnly

validity All Scripts

Gets a metadata collection by name, this collection is read only and can be queried using the methods defined in the SparkMongoCollectionReadOnly object.

params

collectionName - the name of the collection you wish to access

example

var myMetaCollection = Spark.metaCollection("metatest");

getFiles

signature getFiles()

returns SparkFiles

validity All Scripts

Provides access to file operations via a SparkFiles interface

example

var files = Spark.getFiles();

uploadedXml

signature uploadedXml(string uploadId)

returns SparkXmlReader

DEPRECATED use Spark.getFiles().uploadedXml(uploadId)

validity All Scripts

Provides access to an uploaded file via a SparkXmlReader interface

params

uploadId - the id of the uploaded file

example

var reader = Spark.uploadedXml("myUploadId");

uploadedJson

signature uploadedJson(string uploadId)

returns JSON

DEPRECATED use Spark.getFiles().uploadedJson(uploadId)

validity All Scripts

Provides access to an uploaded file via a JSON object

params

uploadId - the id of the uploaded file

returns

A JSON object

example

var reader = Spark.uploadedJson("myUploadId");

downloadableXml

signature downloadableXml(string shortCode)

returns SparkXmlReader

DEPRECATED use Spark.getFiles().downloadableXml(shortCode)

validity All Scripts

Provides access to a downloadable file via a SparkXmlReader interface

params

shortCode - the short code for the downloadable file

returns

example

var reader = Spark.downloadableXml("shortCode");

downloadableJson

signature downloadableJson(string shortCode)

returns JSON

DEPRECATED use Spark.getFiles().downloadableJson(shortCode)

validity All Scripts

Provides access to a downloadable file via a JSON object

params

shortCode - the short code for the downloadable file

returns

example

var reader = Spark.downloadableJson("shortCode");

sendGrid

signature sendGrid(string username, string password)

returns SendGrid

validity All Scripts

Send an email via the SendGrid email delivery provider

params

username - your SendGrid accounet username

password - your SendGrid account password

example

Spark.sendGrid(username, password);

getScheduler

signature getScheduler()

returns SparkScheduler

validity All Scripts

Utility to schedule execution of a module in the future

example

Spark.getScheduler();

getCache

signature getCache()

returns SparkCache

validity All Scripts

Utility to cache complex objects in memory

example

Spark.getCache();

sendRequest

signature sendRequest(JSON request)

returns JSON

validity All Scripts

Sends a Request to the platform, this mimics the process a client uses to send requests

The request is sent as the current player, if there is no current player the method will fail.

Cloud code attached to the request/response will not be executed. Use the SparkRequests API if cloud code execution is required.

returns - The response as would be returned to the client

example

Spark.sendRequest({"@class": ".LogEventRequest", "eventKey": "SOT", "SC": "1000"});

sendRequestAs

signature sendRequestAs(JSON request, string playerId)

returns JSON

validity All Scripts

Sends a Request to the platform, this mimics the process a client uses to send requests

The request is sent as the player identified by playerId, if there playerId is invalid the requst will fail.

Cloud code attached to the request/response will not be executed. Use the SparkRequests API if cloud code execution is required.

returns - The response as would be returned to the client

example

Spark.sendRequestAs({"@class": ".LogEventRequest", "eventKey": "SOT", "SC": "1000"}, "1234567890");

getRedis

signature getRedis()

returns SparkRedis

validity All Scripts

Returns a reference to a SparkRedis object

example

Spark.getRedis();

getLeaderboards

signature getLeaderboards()

returns SparkLeaderboards

validity All Scripts

Returns a reference to a SparkLeaderboards object, used to access the leaderboards for this game.

example

Spark.getLeaderboards();

getClientIp

signature getClientIp()

returns string

validity All Scripts

Returns the client IP address of the current websocket connection (if any).

example

var ip = Spark.getClientIp();

getConfig

signature getConfig()

returns SparkConfig

validity All Scripts

Returns configuration information about the currently published game.

example

var myGameConfig = Spark.getConfig();

getSparkScriptOptions

signature getSparkScriptOptions()

returns SparkScriptOptions

validity All Scripts

Returns a configuration object for cloud-code scripts.

example

var options = Spark.getSparkScriptOptions();

getTeams

signature getTeams()

returns SparkTeams

validity All Scripts

Returns a reference to a SparkTeams object, used to access the teams for this game.

example

Spark.getTeams();

getMultiplayer

signature getMultiplayer()

returns SparkMultiplayer

validity All Scripts

Returns a reference to a SparkMultiplayer object, used to access the platform's multiplayer capabilities.

example

Spark.getMultiplayer();

getProperties

signature getProperties()

returns SparkProperties

validity All Scripts

Returns a reference to a SparkProperties object, used to access the Properties and Property Sets configured against a game.

example

Spark.getProperties();

getBulkScheduler

signature getBulkScheduler()

returns SparkBulkScheduler

validity All Scripts

Returns a reference to a SparkBulkScheduler object, used to perform operations on multiple players at once.

example

Spark.getBulkScheduler();

getDigester

signature getDigester()

returns SparkDigest

validity All Scripts

Returns a reference to a SparkDigest object.

example

Spark.getDigester();

getCredentialType

signature getCredentialType()

returns string

validity All Scripts

Returns the type of the credential used for the current connection (if any).

example

var credentialType = Spark.getCredentialType();

getSessionId

signature getSessionId()

returns string

validity All Scripts

Returns the session ID of the current player (if any).

example

var sessionId = Spark.getSessionId();

getUploadableUtils

signature getUploadableUtils()

returns SparkUploadableUtils

validity All Scripts

Returns a utility class to enable uploading and retrieval of uploadables from cloud code.

example

var util = Spark.getUploadableUtils();

getGameDataService

signature getGameDataService()

returns SparkGameDataService

validity All Scripts

Returns the Game Data Service

example

var api = Spark.getGameDataService();

exit

signature exit()

returns void

Terminates execution of the current script

example

Spark.exit();

getScriptData

signature getScriptData(string name)

returns JSON

Gets the value from a name value pair structure that allows custom data to be attached to the challenge. This data can either be complex JSON or simple values.

params

name - The name in the name value pair

returns

a JSON object

example

var value = Spark.getPlayer().getScriptData("name");

setScriptData

signature setScriptData(string name, JSON value)

returns void

Allows arbitrary data to be added to the object being acted upon.

Sets a value into a name value pair structure that allows custom data to be attached to the challenge. This data can either be complex JSON or simple values.

The data is visible to the client

This data is sent to the player(s) in the 'scriptData' attribute of the Request, Response or Message object.

When scriptData is set to a request, it gets set against the response that will be returned to the player. This allows basic communication between request and response scripts.

params

name - The name in the name value pair

value - The value to set in the name value pair

example

Spark.getPlayer().setScriptData("name", "value");

removeScriptData

signature removeScriptData(string name)

returns void

Removes a value from a name value pair structure that allows custom data to be attached to the challenge. This data can either be complex JSON or simple values.

params

name - The name in the name value pair

example

Spark.getPlayer().removeScriptData("name");

removeAllScriptData

signature removeAllScriptData()

returns void

Removes all script data that has been set

example

Spark.removeAllScriptData();

getRemainingMilliseconds

signature getRemainingMilliseconds()

returns number

Gets the number of milliseconds this script has left to run before a longRunningScriptError is thrown

getData

signature getData()

returns JSON

validity All Scripts

A JSON version of the object being scripted. Can be either a Request, Response or Message.

The structure of the JSON is as the Client either receives or sends it. Attributes can be read, but not changed

example

var userName = Spark.getData().userName;
Did this page help you? Please enter your feedback below. For questions about using this part of the platform, please contact support here