Player balances

Use the SDK to manage player currency balances.

Read time 3 minutes

Last updated a day ago

The

PlayerBalances

namespace contains all the methods for fetching and updating a player's currency balances. These methods will return the balances for the currently signed in player from the Authentication SDK.

Note

All the methods in this namespace can throw an EconomyException.

GetBalancesAsync

Retrieve the currency balances for the current user. Takes an optional

GetBalancesOptions

. When getting balances, you can use the

GetBalancesOptions

to set a limit on the number of balances to fetch (between 1 and 100 inclusive). This is to help with pagination. The default number is 20. The following sample code retrieves the first five balances for the current user, and then retrieves the next five, including those for currencies that have since been deleted from the configuration.


// Optional, defaults to 20GetBalancesOptions options = new GetBalancesOptions{    ItemsPerFetch = 5};GetBalancesResult getBalancesResult = await EconomyService.Instance.PlayerBalances.GetBalancesAsync(options);List<PlayerBalance> firstFiveBalances = getBalancesResult.Balances;// do something with your balancesif (getBalancesResult.HasNext) {    getBalancesResult = await getBalancesResult.GetNextAsync(options.ItemsPerFetch);    List<PlayerBalance> nextFiveBalances = getBalancesResult.Balances;    // do something with your balances}

These methods return a

GetBalancesResult

. See GetBalancesResult.

GetBalancesOptions

The options object for a

GetBalancesAsync

call. It has the following field:

```
ItemsPerFetch
```
: An int. Defaults to 20. Use this to set the maximum number of balances to fetch per call between 1 and 100 inclusive.

GetBalancesResult

GetBalancesResult

provides paginated access to the list of balances retrieved. It has the following fields:

```
Balances
```
: A
```
List<PlayerBalance>
```
with the currently fetched balances.

It has the following methods:

```
GetNextAsync(int itemsToFetch = 20)
```
: This method asynchronously fetches more results. It has one optional parameter to limit the amount of results fetched (this can be between 1 and 100 inclusive, default is 20). It will return a new result, which contains both the original items and the newly fetched items in its
```
Balances
```
list.

SetBalanceAsync

Sets the balance of the specified currency to the specified value. This method optionally takes a

SetBalancesOptions

object used to set the write lock. If provided, an exception is thrown unless the

writeLock

matches the

writeLock

received by a previous read, in order to provide optimistic concurrency. If not provided, the transaction proceeds regardless of any existing

writeLock

in the data. This method returns the current balance after the update has been applied, if the operation is successful.


string currencyID = "GOLD_BARS";int newAmount = 1000;string writeLock = "someLockValueFromPreviousRequest";SetBalanceOptions options = new SetBalanceOptions{    WriteLock = writeLock};PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.SetBalanceAsync(currencyID, newAmount);// ORPlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.SetBalanceAsync(currencyID, newAmount, options);

SetBalanceOptions

The options object for a

SetBalanceAsync

call. It has the following field:

```
WriteLock
```
: A string. Defaults to
```
null
```
. Use this to set a write lock for optimistic concurrency. See Write Lock.

IncrementBalanceAsync

Increments the balance of the specified currency by the specified value. This method optionally takes a

IncrementBalancesOptions

object used to set the write lock. If provided, then an exception is thrown unless the

writeLock

matches the

writeLock

received by a previous read, in order to provide optimistic concurrency. If not provided, the transaction proceeds regardless of any existing

writeLock

in the data. This method returns the current balance after the update is applied, if the operation is successful.


string currencyID = "GOLD_BARS";int incrementAmount = 1000;string writeLock = "someLockValueFromPreviousRequest";IncrementBalanceOptions options = new IncrementBalanceOptions{    WriteLock = writeLock};PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.IncrementBalanceAsync(currencyID, newAmount);// ORPlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.IncrementBalanceAsync(currencyID, newAmount, options);

IncrementBalanceOptions

The options object for a

IncrementBalanceAsync

call. It has the following field:

```
WriteLock
```
: A string. Defaults to
```
null
```
. Use this to set a write lock for optimistic concurrency. See Write Lock.

DecrementBalanceAsync

Decrements the balance of the specified currency by the specified value. This method optionally takes a

DecrementBalanceOptions

object used to set the write lock. If provided, then an exception is thrown unless the

writeLock

matches the

writeLock

received by a previous read, in order to provide optimistic concurrency. If not provided, the transaction proceeds regardless of any existing

writeLock

in the data. This method returns the current balance after the update is applied, if the operation is successful.


string currencyID = "GOLD_BARS";int decrementAmount = 1000;string writeLock = "someLockValueFromPreviousRequest";DecrementBalanceOptions options = new DecrementBalanceOptions{    WriteLock = writeLock};PlayerBalance newBalance = await EconomyService.Instance.PlayerBalances.DecrementBalanceAsync(currencyID, newAmount);// ORPlayerBalance otherNewBalance = await EconomyService.Instance.PlayerBalances.DecrementBalanceAsync(currencyID, newAmount, options);

DecrementBalanceOptions

The options object for a

DecrementBalanceAsync

call. It has the following fields:

```
WriteLock
```
: A string. Defaults to
```
null
```
. Use this to set a write lock for optimistic concurrency. See Write Lock.

PlayerBalance

A player balance represents a single currency balance for a player. It has the following fields:

```
CurrencyId
```
: The ID of the currency this balance represents.
```
Balance
```
: The integer amount of this currency the player has.
```
WriteLock
```
: The current
```
writeLock
```
string.
```
Created
```
: The date this balance was created. It is an EconomyDate object.
```
Modified
```
: The date this balance was modified. It is an EconomyDate object.

It also has the following helper methods:

GetCurrencyDefinitionAsync

This is a convenience method to get the currency definition for the currency associated with this balance. It returns a CurrencyDefinition.


PlayerBalance myPlayerBalance = ... // Get a player balance from one of the above methodsCurrencyDefinition currencyDefForMyPlayerBalance = myPlayerBalance.GetCurrencyDefinitionAsync();

BalanceUpdated

This event can be subscribed to in order to be notified when the SDK updates the balance of a particular currency. The subscriber is passed the currency ID of the balance that was updated.

Note

This event is be called for SDK initiated actions (for example, updating player's balances, making purchases). It is not called for any updates from other devices / service side changes.


EconomyService.Instance.PlayerBalances.BalanceUpdated += currencyID => {    Debug.Log($"The currency that was updated was {currencyID}");};

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Economy

Economy

Player balances

GetBalancesAsync

GetBalancesOptions

GetBalancesResult

SetBalanceAsync

SetBalanceOptions

IncrementBalanceAsync

IncrementBalanceOptions

DecrementBalanceAsync

DecrementBalanceOptions

PlayerBalance

GetCurrencyDefinitionAsync

BalanceUpdated