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, 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");

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);

debit1

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);

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");

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, 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");

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);

credit4

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");

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);

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, 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");

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);

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)

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);

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");

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");
Did this page help you? Please enter your feedback below. For questions about using this part of the platform, please contact support here