API Reference of GS2-Money2 SDK for Game Engine
Model
EzWallet
Wallet
Currency in the wallet is managed separately for currency purchased for a fee and currency obtained for free. Currency purchased for a fee is further managed by the unit price at the time of purchase, allowing for refunds in the event of service termination, or to determine if the balance is sufficient to meet the requirements of the Funds Settlement Act.
The wallet has slots and each slot has a different balance. If balances cannot be shared across platforms, they can be managed separately by using different slots for each platform. Currency acquired for free can also be shared across all platforms.
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
slot | int | ✓ | ~ 100000000 | Slot Number | |
summary | EzWalletSummary | ✓ | Wallet Status | ||
sharedFreeCurrency | bool | ✓ | Share Free Currency | ||
updatedAt | long | ✓ | Datetime of last update |
EzWalletSummary
Wallet Status
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
paid | int | ✓ | 0 | ~ 2147483646 | Count of Paid |
free | int | ✓ | 0 | ~ 2147483646 | Count of Free |
total | int | ✓ | 0 | ~ 2147483646 | Count of Total |
EzDepositTransaction
Deposit Transaction
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
price | float | ✓ | ~ 100000.0 | Purchase Price | |
currency | string | {price} > 0 | ~ 8 chars | Currency Code | |
count | int | ✓ | ~ 2147483646 | Count |
Methods
get
Get Wallet
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace Name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
slot | int | ✓ | ~ 100000000 | Slot Number |
Result
Type | Description | |
---|---|---|
item | EzWallet | Wallet |
Implementation Example
var domain = gs2.Money2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
var item = await domain.ModelAsync();
var domain = gs2.Money2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Money2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Wallet(
0 // slot
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
Value change event handling
var domain = gs2.Money2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId);
var domain = gs2.Money2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
var future = domain.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Money2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Wallet(
0 // slot
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Money2::Model::FWallet> value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
Warning
This event is called when the value in the local cache that the SDK has is changed.
The local cache will only be changed by executing the SDK’s API, or by executing a stamp sheet via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
withdraw
Consume the balance from the wallet
Request
Type | Require | Default | Limitation | Description | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128 chars | Namespace Name | |
accessToken | string | ✓ | ~ 128 chars | User Id | |
slot | int | ✓ | ~ 100000000 | Slot Number | |
withdrawCount | int | ✓ | 1 ~ 2147483646 | Quantity of billable currency to be consumed | |
paidOnly | bool | ✓ | false | Only for paid currency |
Result
Type | Description | |
---|---|---|
item | EzWallet | Post-withdraw Wallet |
withdrawTransactions | List<EzDepositTransaction> | List of consumed deposit transactions |
Error
Special exceptions are defined in this API. GS2-SDK for GameEngine provides specialized exceptions derived from general exceptions to facilitate handling of errors that may need to be handled in games. Please refer to the documentation here for more information on common error types and handling methods.
Type | Base Type | Description |
---|---|---|
ConflictException | ConflictException | The wallet operation process conflicted. Retry required. |
InsufficientException | BadRequestException | Wallet balance is insufficient. |
Implementation Example
try {
var domain = gs2.Money2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
var result = await domain.WithdrawAsync(
withdrawCount: 50,
paidOnly: null
);
var item = await result.ModelAsync();
var withdrawTransactions = result.WithdrawTransactions;
} catch(Gs2.Gs2Money2.Exception.Conflict e) {
// The wallet operation process conflicted. Retry required.
} catch(Gs2.Gs2Money2.Exception.Insufficient e) {
// Wallet balance is insufficient.
}
var domain = gs2.Money2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
var future = domain.WithdrawFuture(
withdrawCount: 50,
paidOnly: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Money2.Exception.ConflictException)
{
// The wallet operation process conflicted. Retry required.
}
if (future.Error is Gs2.Gs2Money2.Exception.InsufficientException)
{
// Wallet balance is insufficient.
}
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.Model();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
var withdrawTransactions = future.Result.WithdrawTransactions;
const auto Domain = Gs2->Money2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Wallet(
0 // slot
);
const auto Future = Domain->Withdraw(
50 // withdrawCount
// paidOnly
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Money2::Error::FConflictError::Class))
{
// The wallet operation process conflicted. Retry required.
}
if (e->IsChildOf(Gs2::Money2::Error::FInsufficientError::Class))
{
// Wallet balance is insufficient.
}
return false;
}
// obtain changed values / result values
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
const auto WithdrawTransactions = Result->WithdrawTransactions;