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"));
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();
signature getHttp(string url, number timeout)
returns SparkHttp
validity All Scripts
Provides access to a SparkHttp interface
params
url - the URL of the service to connect to
timeout - (Optional) the max time in milliseconds to wait for the response, if null the system default will be used.
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 APIKey)
returns SendGrid
validity All Scripts
Send an email via the SendGrid email delivery provider
params
APIKey - your SendGrid API key
example
Spark.sendGrid("SG.SendGridAPIKey");
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;