GS2-Money SDK for Game Engine API リファレンス
モデル
EzWallet
ウォレット
ウォレット内の通貨は大きく有償で購入した通貨と、無償で入手した通貨が分けて管理されます。
有償で購入した通貨は更に購入時の単価毎に管理され、サービス終了になってしまった際の返金や資金決済法に該当するだけの残高が存在するかが集計できます。
ウォレットにはスロットがあり、スロットごとに異なる残高を管理できます。
プラットフォームをまたいで残高を共有できない場合にはプラットフォーム毎に異なるスロットを利用することで分けて管理することができます。
その際に無償で入手した通貨は全てのプラットフォームで共通した値を利用することもできます。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
slot | int | ✓ | ~ 100000000 | スロット番号 | |
paid | int | ✓ | 0 | ~ 2147483646 | 有償課金通貨所持量 |
free | int | ✓ | 0 | ~ 2147483646 | 無償課金通貨所持量 |
shareFree | bool | ✓ | false | 無償課金通貨を共有するか | |
updatedAt | long | ✓ | 現在時刻 | 最終更新日時 (UNIX時間 単位:ミリ秒) |
メソッド
get
ウォレットを取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペースの名前 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
slot | int | ✓ | ~ 100000000 | スロット番号 |
Result
型 | 説明 | |
---|---|---|
item | EzWallet | ウォレット |
実装例
var domain = gs2.Money.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
var item = await domain.ModelAsync();
var domain = gs2.Money.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->Money->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Wallet(
0 // slot
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
値の変更イベントハンドリング
var domain = gs2.Money.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
var domain = gs2.Money.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->Money->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Wallet(
0 // slot
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Money::Model::FWallet> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
withdraw
ウォレットから残高を消費
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペースの名前 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
slot | int | ✓ | ~ 100000000 | スロット番号 | |
count | int | ✓ | 1 ~ 2147483646 | 消費する課金通貨の数量 | |
paidOnly | bool | ✓ | false | 有償課金通貨のみを対象とするか |
Result
型 | 説明 | |
---|---|---|
item | EzWallet | 消費後のウォレット |
price | float | 消費した通貨の価格 |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
型 | 基底クラス | 説明 |
---|---|---|
ConflictException | ConflictException | ウォレットの操作処理が衝突しました。リトライが必要です |
InsufficientException | BadRequestException | ウォレットの残高が不足しています |
実装例
try {
var domain = gs2.Money.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
var result = await domain.WithdrawAsync(
count: 50,
paidOnly: null
);
var item = await result.ModelAsync();
var price = result.Price;
} catch(Gs2.Gs2Money.Exception.Conflict e) {
// The wallet operation process conflicted. Retry required.
} catch(Gs2.Gs2Money.Exception.Insufficient e) {
// Wallet balance is insufficient.
}
var domain = gs2.Money.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Wallet(
slot: 0
);
var future = domain.WithdrawFuture(
count: 50,
paidOnly: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Money.Exception.ConflictException)
{
// The wallet operation process conflicted. Retry required.
}
if (future.Error is Gs2.Gs2Money.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 price = future.Result.Price;
const auto Domain = Gs2->Money->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Wallet(
0 // slot
);
const auto Future = Domain->Withdraw(
50 // count
// paidOnly
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Money::Error::FConflictError::Class))
{
// The wallet operation process conflicted. Retry required.
}
if (e->IsChildOf(Gs2::Money::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 Price = Result->Price;