SparkPlayer
Provides access to a player details
e.g.
var player = Spark.getPlayer();
or
var player = Spark.loadPlayer(myplayerid);
getAllBalances
signature getAllBalances()
returns JSON
Returns a map of the player's balance for each currency type.
example
var allBalances = Spark.getPlayer().getAllCurrencies();
getDisplayName
signature getDisplayName()
returns string
Gets the display name of the player.
This may be null for a player who has only used device authentication. Other authentication mechanisms will return a value.
example
var displayName = Spark.getPlayer().getDisplayName();
getUserName
signature getUserName()
returns string
Gets the username name of the player.
For a player who has only used device authentication this value will be generated from the device id.
example
var userName = Spark.getPlayer().getUserName();
getPlayerId
signature getPlayerId()
returns string
Gets the GameSparks ID of the player
example
var playerId = Spark.getPlayer().getPlayerId();
persist
signature persist()
returns void
Saves the players data to the DB. By default, changes are persisted after the script executes. This method ensures changes are saved immediately so other scripts running in parallel see the changes immediately.
example
Spark.getPlayer().persist();
credit1
signature credit1(number quantity)
returns void
Credits the currency1 balance of the player with the amount specified.
params
quantity - the amount to credit
example
Spark.getPlayer().credit1(20);
signature credit1(number quantity, string reason)
returns void
Credits the currency1 balance of the player with the amount specified.
params
quantity - the amount to credit
reason - the reason for the credit
example
Spark.getPlayer().credit1(20, "Loyalty Bonus");
debit1
signature debit1(number quantity, string reason)
returns boolean
Debits the currency1 balance of the player with the amount specified.
params
quantity - the amount to debit
reason - the reason for the debit
returns
true if the debit was successful, false if the current balance was not sufficient
example
Spark.getPlayer().debit1(5, "Loser Penalty");
signature debit1(number quantity)
returns boolean
Debits the currency1 balance of the player with the amount specified.
params
quantity - the amount to debit
returns
true if the debit was successful, false if the current balance was not sufficient
example
Spark.getPlayer().debit1(5);
credit2
signature credit2(number quantity, string reason)
returns void
Credits the currency2 balance of the player with the amount specified.
params
quantity - the amount to credit
reason - the reason for the credit
example
Spark.getPlayer().credit2(20, "Loyalty Bonus");
signature credit2(number quantity)
returns void
Credits the currency2 balance of the player with the amount specified.
params
quantity - the amount to credit
example
Spark.getPlayer().credit2(20);
debit2
signature debit2(number quantity, string reason)
returns boolean
Debits the currency2 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
reason - the reason for the debit
example
Spark.getPlayer().debit2(5, "Loser Penalty");
signature debit2(number quantity)
returns boolean
Debits the currency2 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
example
Spark.getPlayer().debit2(5);
credit3
signature credit3(number quantity, string reason)
returns void
Credits the currency3 balance of the player with the amount specified.
params
quantity - the amount to credit
reason - the reason for the credit
example
Spark.getPlayer().credit3(20, "Loyalty Bonus");
signature credit3(number quantity)
returns void
Credits the currency3 balance of the player with the amount specified.
params
quantity - the amount to credit
example
Spark.getPlayer().credit3(20);
debit3
signature debit3(number quantity)
returns boolean
Debits the currency3 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
example
Spark.getPlayer().debit3(5);
signature debit3(number quantity, string reason)
returns boolean
Debits the currency3 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
reason - the reason for the debit
example
Spark.getPlayer().debit3(5, "Loser Penalty");
credit4
signature credit4(number quantity)
returns void
Credits the currency4 balance of the player with the amount specified.
params
quantity - the amount to credit
example
Spark.getPlayer().credit4(20);
signature credit4(number quantity, string reason)
returns void
Credits the currency4 balance of the player with the amount specified.
params
quantity - the amount to credit
reason - the reason for the credit
example
Spark.getPlayer().credit4(20, "Loyalty Bonus");
debit4
signature debit4(number quantity, string reason)
returns boolean
Debits the currency4 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
reason - the reason for the debit
example
Spark.getPlayer().debit4(5, "Loser Penalty");
signature debit4(number quantity)
returns boolean
Debits the currency4 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
example
Spark.getPlayer().debit4(5);
credit5
signature credit5(number quantity)
returns void
Credits the currency5 balance of the player with the amount specified.
params
quantity - the amount to credit
example
Spark.getPlayer().credit5(20);
signature credit5(number quantity, string reason)
returns void
Credits the currency5 balance of the player with the amount specified.
params
quantity - the amount to credit
reason - the reason for the credit
example
Spark.getPlayer().credit5(20, "Loyalty Bonus");
debit5
signature debit5(number quantity, string reason)
returns boolean
Debits the currency5 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
reason - the reason for the debit
example
Spark.getPlayer().debit5(5, "Loser Penalty");
signature debit5(number quantity)
returns boolean
Debits the currency5 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
example
Spark.getPlayer().debit5(5);
credit6
signature credit6(number quantity, string reason)
returns void
Credits the currency6 balance of the player with the amount specified.
params
quantity - the amount to credit
reason - the reason for the credit
example
Spark.getPlayer().credit6(20, "Loyalty Bonus");
signature credit6(number quantity)
returns void
Credits the currency6 balance of the player with the amount specified.
params
quantity - the amount to credit
example
Spark.getPlayer().credit6(20);
debit6
signature debit6(number quantity, string reason)
returns boolean
Debits the currency6 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
reason - the reason for the debit
example
Spark.getPlayer().debit6(5, "Loser Penalty");
signature debit6(number quantity)
returns boolean
Debits the currency6 balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
quantity - the amount to debit
example
Spark.getPlayer().debit6(5);
getBalance1
signature getBalance1()
returns number
Gets the currency1 balance of the player.
example
var bal = Spark.getPlayer().getBalance1();
debit
signature debit(string shortCode, number quantity, string reason)
returns boolean
Debits the named currency balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
shortCode - the shortCode of the named currency to debit
quantity - the amount to debit
reason - the reason for the debit
example
Spark.getPlayer().debit("GOLD", 5, "Loser Penalty");
signature debit(string shortCode, number quantity)
returns boolean
Debits the named currency balance of the player with the amount specified.
Returns true if the debit was successful, false if the current balance was not sufficient.
params
shortCode - the shortCode of the named currency to debit
quantity - the amount to debit
example
Spark.getPlayer().debit("GOLD", 5);
getBalance2
signature getBalance2()
returns number
Gets the currency2 balance of the player.
example
var bal = Spark.getPlayer().getBalance2();
credit
signature credit(string shortCode, number quantity)
returns void
Credits the named currency balance of the player with the amount specified.
params
shortCode - the short code of the named currency to credit
quantity - the amount to credit
example
Spark.getPlayer().credit("GOLD", 20);
getBalance3
signature getBalance3()
returns number
Gets the currency3 balance of the player.
example
var bal = Spark.getPlayer().getBalance3();
credit
signature credit(string shortCode, number quantity, string reason)
returns void
Credits the named currency balance of the player with the amount specified.
params
shortCode - the short code of the named currency to credit
quantity - the amount to credit
reason - the reason for the credit
example
Spark.getPlayer().credit("GOLD", 20, "Loyalty Bonus");
getBalance4
signature getBalance4()
returns number
Gets the currency4 balance of the player.
example
var bal = Spark.getPlayer().getBalance4();
getBalance5
signature getBalance5()
returns number
Gets the currency5 balance of the player.
example
var bal = Spark.getPlayer().getBalance5();
getBalance6
signature getBalance6()
returns number
Gets the currency6 balance of the player.
example
var bal = Spark.getPlayer().getBalance6();
getBalance
signature getBalance(string shortCode)
returns number
Gets the player's balance for the specified currency.
params
shortCode - The short code of the named currency to get the player's balance for.
example
var bal = Spark.getPlayer().getBalance("GOLD");
addVGood
signature addVGood(string shortCode, number quantity)
returns boolean
Finds a virtual good by short code and adds the quantity specified to the player this SparkPlayer object represents.
Returns true if the add was successful. false if the shortcode does not exist, or the user already has the maximum amount of the specified good.
params
shortCode - the virtual good's short code
quantity - the amount to add
example
var goodsAdded = Spark.getPlayer().addVGood(vgShortCode, 42);
signature addVGood(string shortCode, number quantity, string reason)
returns boolean
Finds a virtual good by short code and adds the quantity specified to the player this SparkPlayer object represents.
Returns true if the add was successful. false if the shortcode does not exist, or the user already has the maximum amount of the specified good.
params
shortCode - the virtual good's short code
quantity - the amount to add
reason - the reason for adding the virtual good
example
var goodsAdded = Spark.getPlayer().addVGood(vgShortCode, 42, "Loyalty bonus");
useVGood
signature useVGood(string shortCode, number quantity, string reason)
returns boolean
Removes a quantity of virtual goods from the player.
Returns true if the player had enough of the virtual good specified by short code. If the method returns false, no modification is made.
params
shortCode - the virtual good's short code
quantity - the amount to consume
reason - the reason for using the virtual good
example
var goodsUsed = Spark.getPlayer().useVGood(vgShortCode, 34, "Loser penalty");
signature useVGood(string shortCode, number quantity)
returns boolean
Removes a quantity of virtual goods from the player.
Returns true if the player had enough of the virtual good specified by short code. If the method returns false, no modification is made.
params
shortCode - the virtual good's short code
quantity - the amount to consume
example
var goodsUsed = Spark.getPlayer().useVGood(vgShortCode, 34);
hasVGood
signature hasVGood(string shortCode)
returns number
Determines whether the player has a particular virtual good.
Returns the quantity of the virtual good the player has.
params
shortCode - the virtual good's short code
example
var hasGood = Spark.getPlayer().hasVGood(vgShortCode);
addAchievement
signature addAchievement(string shortCode)
returns boolean
Adds an achievement to the player this SparkPlayer object represents.
The player will be given any award that is configured against the award in the developer portal.
Returns true if the achievement was added. false if the player already had the achievement, or the shortCode does not exist
params
shortCode - The shortCode of the achievement
example
var achievementAdded = Spark.getPlayer().addAchievement(shortCode);
removeAchievement
signature removeAchievement(string shortCode)
returns boolean
Removes an achievement from the player.
Returns true if the achievement was removed. false if player did not have the achievement.
Returns false if the player did not have the achievement.
params
shortCode the shortCode of the achievement to remove
example
var achievementRemoved = Spark.getPlayer().removeAchievement(shortCode);
hasAchievement
signature hasAchievement(string shortCode)
returns boolean
Determines whether the player has a particular achievement.
Returns true if the player has the achievement
params
shortCode - The shortCode of the achievement
example
var hasAchievement = Spark.getPlayer().hasAchievement(shortCode);
dismissMessage
signature dismissMessage(string messageId)
returns boolean
Allows a script to dismiss a given message that belongs to a player.
Returns true if a message was dismissed.
params
messageId
example
var messageDismissed = Spark.getPlayer().dismissMessage(messageId);
getExternalIds
signature getExternalIds()
returns JSON
Returns a map of external system ids to external ids.
This allows you to determine, for example, the player facebook id.
Map keys: 'FB' - Indicates the ID is a facebook id
example
var externalIds = Spark.getPlayer().getExternalIds();
getFriendIds
signature getFriendIds()
returns JSON
Returns an array of the player's social friend ids.
example
var friends = Spark.getPlayer().getFriendIds();
isOnline
signature isOnline()
returns boolean
Returns true if this player is currently has an open WebSocket.
example
var online = Spark.getPlayer().isOnline();
validatePassword
signature validatePassword(string password)
returns boolean
Validates the given password against the one stored for this player.
params
password - the password to validate
returns
true if the given password matches the one stored for this player.
example
var doesPasswordMatch = Spark.getPlayer().validatePassword(passwordEnteredByPlayer);
setPassword
signature setPassword(string password)
returns void
Sets a new password for this player.
params
password - the password to set
example
Spark.getPlayer().setPassword(password);
isHiddenOnLeaderboards
signature isHiddenOnLeaderboards()
returns boolean
Boolean value indicating if this player is currently being hidden from leaderboards.
example
var hidden = Spark.getPlayer().isHidden();
hideOnLeaderboards
signature hideOnLeaderboards()
returns void
Hide the player from current leaderboards. Prevents any new scores posted showing up as well.
example
Spark.getPlayer().hideOnLeaderboards();
showOnLeaderboards
signature showOnLeaderboards()
returns void
Show the player on current leaderboards, redisplaying any existing scores. New scores will begin to show up on leaderboards again as they are recorded.
example
Spark.getPlayer().showOnLeaderboards();
getPushRegistrations
signature getPushRegistrations()
returns SparkPushRegistration[]
Gets push registrations of the player
example
var pushRegistrations = Spark.getPlayer().getPushRegistrations();
removePushRegistration
signature removePushRegistration(string id)
returns void
Removes the registration with the given id. The device associated with this registration will no longer receive push notifications for this player.
example
Spark.getPlayer().removePushRegistration(registrationId);
setSegmentValue
signature setSegmentValue(string segmentType, string segmentValue)
returns void
Sets a value for a single segment against the player.
example
Spark.getPlayer().setSegmentValue("PROFILE", "P1");
getSegmentValue
signature getSegmentValue(string segmentType)
returns string
Gets a value for a single segment from the player.
example
var profileSegmentValue = Spark.getPlayer().getSegmentValue("PROFILE");
getSegments
signature getSegments()
returns JSON
Gets all segment values from the player.
example
var segments = Spark.getPlayer().getSegments();
disconnect
signature disconnect(boolean excludeCurrent)
returns void
Disconnects this player, a SessionTerminatedMessage will be sent to the socket, and the socket will be unauthenticated
params
excludeCurrent - If the script is running in the context of the user being disconnected, the current socket will not be disconnected
example
Spark.getPlayer().disconnect(true);
getAchievements
signature getAchievements()
returns string[]
Gets all achievements from this player
example
Spark.getPlayer().getAchievements();
getVirtualGoods
signature getVirtualGoods()
returns JSON
Gets all virtual goods from the player.
example
var goods = Spark.getPlayer().getVirtualGoods();
resetAuthTokens
signature resetAuthTokens()
returns void
Removes all auth tokens for this user, this will force a re-authentication.
example
Spark.getPlayer().resetAuthTokens();
signature resetAuthTokens(boolean excludeCurrent)
returns void
Removes auth tokens for this user, this will force a re-authentication.
params
excludeCurrent - If the script is running in the context of the user having tokens reset, the current token will not be reset
example
Spark.getPlayer().resetAuthTokens(true);
getLastSeen
signature getLastSeen()
returns date
Gets the lastSeen value for the player.
example
var lastSeen = Spark.getPlayer().getLastSeen();
unlock
signature unlock()
returns void
Unlocks the account for this player if it has been locked by too many failed login attempts.
example
Spark.getPlayer().unlock();
getCreationDate
signature getCreationDate()
returns date
Gets the creation date of the player.
example
var creationDate = Spark.getPlayer().getCreationDate();
matchesMongoQuery
signature matchesMongoQuery(ScriptableObject mongoQuery)
returns boolean
Checks if this player would be returned by the given mongo query.
example
var isMatch = Spark.getPlayer().matchesMongoQuery({});
matchesMongoQueryString
signature matchesMongoQueryString(string mongoQueryString)
returns boolean
Checks if this player would be returned by the given mongo query (as a string).
example
var isMatch = Spark.getPlayer().matchesMongoQueryString("");
getExperimentSegments
signature getExperimentSegments()
returns SparkPlayerExperimentSegment[]
Returns the current experiment segments of the player.
example
var experiments = Spark.getPlayer().getExperimentSegments();
removeExperiment
signature removeExperiment(number experimentId)
returns boolean
Removes the player from the given experiment.
returns
true if the player was part of the experiment, false if the player was not part of the experiment
example
var removed = Spark.getPlayer().removeExperiment();
setExperimentSegment
signature setExperimentSegment(number experimentId, string experimentSegmentName)
returns boolean
Sets the experiment segment for the player.
returns
true if the experiment segment was added to the player, false if the player already had the experiment segment
example
var added = Spark.getPlayer().setExperimentSegment(47, "FireSale");
deletePlayer
signature deletePlayer()
returns void
Deletes this player and associated data from system collections.
Note that any data linked to the player in runtime collections is not deleted, since the GameSparks platform has no way of identifying this data automatically.
This deletion is irreversible and should be used with extreme caution.
example
var userName = Spark.loadPlayer("57f4af757d196627bc79abc9").deletePlayer();
getPrivateData
signature getPrivateData(string name)
returns JSON
Gets the value from a name value pair structure that allows custom data to be attached to this object. 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 privateData = Spark.getPlayer().getPrivateData("name");
var privateData = Spark.getChallenge().getPrivateData("name");
setPrivateData
signature setPrivateData(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 this object. This data can either be complex JSON or simple values.
The data is not visible to the client
params
name - The name in the name value pair
value - The value to set in the name value pair
example
Spark.getPlayer().setPrivateData("name", "value");
Spark.getChallenge().setPrivateData("name", "value");
removePrivateData
signature removePrivateData(string name)
returns void
Removes a value from a name value pair structure that allows custom data to be attached to this. This data can either be complex JSON or simple values.
params
name - The name in the name value pair
example
Spark.getPlayer().removePrivateData("name");
Spark.getChallenge().removePrivateData("name");
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");