GS2-LoginReward SDK for Game Engine API リファレンス

ゲームエンジン向け GS2-LoginReward SDK の モデルの仕様 と API のリファレンス

モデル

EzReceiveStatus

受け取り状態

ユーザーごと・ボーナスモデルごとのログインボーナスの受け取り状態を追跡します。
各エントリがその日の報酬を受け取り済みかどうかを示す真偽値の配列(receivedSteps)を保持します。
また、日次の受け取り資格を判定するために、最後にボーナスを受け取った時刻(lastReceivedAt)を記録します。
receivedSteps はボーナスサイクルの再開時(ストリーミングモードの繰り返し有効時など)にリセットされることがあります。

有効化条件必須デフォルト値の制限説明
bonusModelNamestring
~ 128文字ボーナスモデル名
この受け取り状態が紐づくログインボーナスモデルの名前。
ユーザーの受け取り進捗を特定のボーナスモデル定義に関連づけ、どの報酬リストと配布ルールが適用されるかを決定します。
receivedStepsList<bool>[]0 ~ 100 items受け取りステップ
報酬リストの各日に対応する順序付きの真偽値配列。
true はユーザーがその日の報酬を受け取り済みであることを示し、false は取り逃がしたか未受け取りであることを示します。
配列のインデックスは関連する BonusModel の rewards 配列と対応します。
ストリーミングモードで繰り返しが有効な場合、サイクルの再開時にこの配列はリセットされます。
lastReceivedAtlong最終受け取り時刻
ユーザーが最後にログインボーナスを受け取った時刻のタイムスタンプ。
ボーナスモデルで定義されたリセット時間に基づき、ユーザーが本日のボーナスを既に受け取り済みかどうかを判定するために使用されます。
受け取り状態がクリアされた際(繰り返しモードでのサイクル再開時など)に 0 にリセットされます。

EzBonusModel

ログインボーナスモデル

ログインボーナスモデルにはログインボーナスの配布スケジュールを設定します。
配布スケジュールには《スケジュールモード》と《ストリーミングモード》があります。

スケジュールモードでは、GS2-Schedule のイベントの指定が必須で、そのイベントの開始日からの経過日数でボーナスの配布を行います。
途中で撮り逃しが発生した場合、その分のボーナスは配布されません。

ストリーミングモードでは、毎日ボーナスに設定された報酬を先頭から順番に配布します。
ストリーミングモードでは繰り返しの設定が可能です。その場合、ストリームの終端に達した場合、先頭から再度配布を行います。

スケジュールモード・ストリーミングモード 共に、取り逃がしの救済機能があります。
一定のコストを支払うことで、取り逃がしたボーナスを受け取ることができます。
ただし、GS2-Schedule のイベントが関連づけられている場合、イベントの開始日からの経過日数より先のボーナスは受け取ることができません。
取り逃がし機能はストリーミングモードかつ繰り返しが有効な場合は使用することができません。

スケジュールモード・ストリーミングモード 共に、設定可能なボーナスの最大日数は100日です。

有効化条件必須デフォルト値の制限説明
namestring
~ 128文字ログインボーナスモデル名
ログインボーナスモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
metadatastring~ 2048文字メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。
mode文字列列挙型
enum {
  “schedule”,
  “streaming”
}
モード
ログインボーナスの配布スケジュールの種類を指定します。
「schedule」モードでは、GS2-Schedule のイベント開始日からの経過日数に基づいて報酬が配布されます。
「streaming」モードでは、カレンダーの日付に関係なく、毎日先頭から順番に報酬が配布されます。
定義説明
“schedule”スケジュールモード
“streaming”ストリーミングモード
periodEventIdstring~ 1024文字期間イベント GRN
ログインボーナスを有効化する期間を表す GS2-Schedule のイベントGRN。
スケジュールモードでは必須で、報酬配布の経過日数を計算する起点の開始日を決定します。
ストリーミングモードでは省略可能ですが、指定した場合はイベント開始日からの経過日数より先のボーナスは受け取れなくなります。
resetHourint{periodEventId} == ""
✓※
0 ~ 23リセット時間(UTC)
受け取りフラグがリセットされる時刻(0-23、UTC)。
ログインボーナスにおける日付の切り替わりタイミングを決定します。
periodEventId が未指定の場合にのみ必要です。イベントが設定されている場合、リセットタイミングはイベントのスケジュールに従います。

※ periodEventId が "" であれば 必須
repeat文字列列挙型
enum {
  “enabled”,
  “disabled”
}
{mode} == “streaming”
✓※
繰り返し
全ての報酬を配布し終えた後に、先頭から再度配布を行うかどうか。
ストリーミングモードでのみ有効です。有効にすると、最後の報酬を配布した後に最初の報酬に戻ってループします。
注意: 繰り返しが有効な場合、取り逃がし救済機能は使用できません。
定義説明
“enabled”有効
“disabled”無効

※ mode が “streaming” であれば 必須
rewardsList<EzReward>0 ~ 100 items報酬リスト
日毎の報酬の順序付きリスト。各エントリは1日分のログインボーナスに対応し、インデックス 0 から順に配布されます。
スケジュールモードでは、インデックスはイベント開始日からの経過日数に対応します。
ストリーミングモードでは、インデックスはログイン日数に対応します。最大100エントリまで設定可能です。
missedReceiveRelief文字列列挙型
enum {
  “enabled”,
  “disabled”
}
“disabled”取り逃がし救済機能
取り逃がしたボーナスの救済機能を有効にするかどうか。有効にすると、ユーザーは指定されたコスト(消費アクション)を支払うことで、受け取り損ねたボーナスを遡って受け取ることができます。
任意で、救済の許可前に条件を確認する検証アクションも設定できます。
ストリーミングモードかつ繰り返しが有効な場合は使用できません。デフォルトは「disabled」です。
定義説明
“enabled”有効
“disabled”無効
missedReceiveReliefVerifyActionsList<EzVerifyAction>{missedReceiveRelief} == “enabled”
[]0 ~ 10 items取り逃がし救済の検証アクションリスト
取り逃がし救済を許可する前に実行される検証アクションのリスト。
救済処理の前にユーザーの資格などの前提条件をチェックします。最大10個まで設定できます。
missedReceiveRelief が有効な場合にのみ適用されます。

※ missedReceiveRelief が “enabled” であれば 有効
missedReceiveReliefConsumeActionsList<EzConsumeAction>{missedReceiveRelief} == “enabled”
[]0 ~ 10 items取り逃がし救済の消費アクションリスト
取り逃がしたボーナスを救済するためにユーザーが支払うコストを定義する消費アクションのリスト。
例えば、ゲーム内通貨やアイテムを救済コストとして消費するよう設定できます。最大10個まで設定できます。
missedReceiveRelief が有効な場合にのみ適用されます。

※ missedReceiveRelief が “enabled” であれば 有効

EzReward

報酬

ログインボーナスの1日分の報酬設定を表します。
各 Reward にはユーザーが受け取るもの(アイテム、通貨、経験値など)を定義する入手アクションのリストが含まれます。
BonusModel の rewards 配列は1日あたり1つの Reward を保持し、順番に配布されます。
報酬の値はバフシステム(BonusModelBuff)を通じて実行時に変更でき、入手アクションにレート乗数を適用できます。

有効化条件必須デフォルト値の制限説明
acquireActionsList<EzAcquireAction>
1 ~ 10 items入手アクションリスト
この日の報酬としてユーザーに付与されるリソースを定義する入手アクションのリスト。
各アクションは入手アクション(アイテム追加、通貨付与など)とそのリクエストパラメータを指定します。
報酬あたり最低1個、最大10個のアクションを設定できます。

EzConfig

コンフィグ設定

トランザクションの変数に適用する設定値のキーバリューペア。
Config エントリにより、実行時に入手アクションの動的なパラメータ化が可能になります。
例えば、スロット名やその他のコンテキスト依存の値を Config 設定を通じてトランザクションリクエストに注入でき、
マスターデータを変更することなく柔軟な報酬設定を実現できます。

有効化条件必須デフォルト値の制限説明
keystring
~ 64文字キー
トランザクションパラメータ内で置換される変数名。最大64文字。
valuestring~ 51200文字
トランザクションパラメータ内で対応するキーに代入される値。最大51,200文字。

EzConsumeAction

消費アクション

消費アクションの仕組みを通じてユーザーからリソースを消費するアクションを定義します。
取り逃がしボーナスの救済でユーザーが支払うコスト(通貨の差し引き、アイテムの消費など)を指定するために使用されます。
action フィールドは消費アクションの種類を指定し、request フィールドには対応するリクエストパラメータが含まれます。

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
消費アクションで実行するアクションの種類
requeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列

EzVerifyAction

検証アクション

操作の実行前に条件を検証するアクションを定義します。
取り逃がしボーナスの救済で、救済を許可する前に前提条件(ユーザーの資格、リソースの利用可能性など)を確認するために使用されます。
action フィールドは検証アクションの種類を指定し、request フィールドには対応するリクエストパラメータが含まれます。

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
検証アクションで実行するアクションの種類
requeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列

EzAcquireAction

入手アクション

入手アクションの仕組みを通じてユーザーにリソースを付与するアクションを定義します。
報酬内で使用され、ユーザーが受け取るもの(インベントリへのアイテム追加、通貨の付与、経験値の付与など)を指定します。
action フィールドは入手アクションの種類を指定し、request フィールドには対応するリクエストパラメータが含まれます。

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
入手アクションで実行するアクションの種類
requeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列

EzVerifyActionResult

検証アクションの実行結果

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
検証アクションで実行するアクションの種類
verifyRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
verifyResultstring~ 1048576文字結果内容

EzConsumeActionResult

消費アクションの実行結果

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
消費アクションで実行するアクションの種類
consumeRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
consumeResultstring~ 1048576文字結果内容

EzAcquireActionResult

入手アクションの実行結果

有効化条件必須デフォルト値の制限説明
action文字列列挙型
enum {
}
入手アクションで実行するアクションの種類
acquireRequeststring
~ 524288文字アクション実行時に使用されるリクエストのJSON文字列
statusCodeint0 ~ 999ステータスコード
acquireResultstring~ 1048576文字結果内容

EzTransactionResult

トランザクション実行結果

サーバーサイドでのトランザクションの自動実行機能を利用して実行されたトランザクションの実行結果

有効化条件必須デフォルト値の制限説明
transactionIdstring
36 ~ 36文字トランザクションID
verifyResultsList<EzVerifyActionResult>0 ~ 10 items検証アクションの実行結果リスト
consumeResultsList<EzConsumeActionResult>[]0 ~ 10 items消費アクションの実行結果リスト
acquireResultsList<EzAcquireActionResult>[]0 ~ 100 items入手アクションの実行結果リスト

メソッド

missedReceive

取り逃がしたログインボーナスを受け取る

過去にログインできなかった日のボーナスを、後から受け取ることができます。
この機能を使うには、ボーナスモデルで「取り逃がし救済」が有効になっている必要があります。
有効な場合、プレイヤーはコストを支払うことで取り逃がした報酬を受け取れます。たとえば「ジェム50個を消費して3日目の報酬を受け取る」といった使い方ができます。

スケジュールモードでは、イベント開始日からの経過日数までの報酬のみ救済できます。
ストリーミングモードでは、ステップ番号は自動で判定できるため省略可能です。

ストリーミングモードで「繰り返し」が有効な場合、この機能は使用できません。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
bonusModelNamestring
~ 128文字ログインボーナスモデル名
ログインボーナスモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession
stepNumberint0 ~ 100受け取るステップ番号 ストリーミングモードでは省略が可能です
configList<EzConfig>[]0 ~ 32 itemsトランザクションの変数に適用する設定値

Result

説明
itemEzReceiveStatus受け取り状態
bonusModelEzBonusModelログインボーナスモデル
transactionIdstring発行されたトランザクションID
stampSheetstringログインボーナスの受け取りの実行に使用するスタンプシート
stampSheetEncryptionKeyIdstringスタンプシートの署名計算に使用した暗号鍵GRN
autoRunStampSheetboolトランザクションの自動実行が有効か
atomicCommitboolトランザクションをアトミックにコミットするか
transactionstring発行されたトランザクション
transactionResultEzTransactionResultトランザクション実行結果

Error

このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。

基底クラス説明
AlreadyReceivedExceptionBadRequestException今日のログインボーナスはすでに受け取っています。

実装例

try {
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Bonus(
    );
    var result = await domain.MissedReceiveAsync(
        bonusModelName: "bonus-0001",
        stepNumber: 1,
        config: null
    );
} catch(Gs2.Gs2LoginReward.Exception.AlreadyReceivedException e) {
    // You have already received today's login bonus.
}
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Bonus(
    );
    var future = domain.MissedReceiveFuture(
        bonusModelName: "bonus-0001",
        stepNumber: 1,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2LoginReward.Exception.AlreadyReceivedException)
        {
            // You have already received today's login bonus.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Bonus(
    );
    const auto Future = Domain->MissedReceive(
        "bonus-0001", // bonusModelName
        1 // stepNumber
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::LoginReward::Error::FAlreadyReceivedError::Class))
        {
            // You have already received today's login bonus.
        }
        return false;
    }

receive

今日のログインボーナスを受け取る

指定されたボーナスモデルに基づいて、今日分のログインボーナスを受け取ります。
各ボーナスモデルには日ごとの報酬が順番に定義されています。たとえば「1日目: ジェム100個、2日目: スタミナ回復薬5個、3日目: レアガチャチケット、…」のような設定が可能です。
プレイヤーはログインするたびにこのAPIを呼び出すことで、報酬ステップを順に進めていきます。

ボーナスの配布方式には2種類あります:

  • スケジュールモード: 特定のカレンダー期間に紐づいて報酬が配布されます。ログインしなかった日の報酬はスキップされます。
  • ストリーミングモード: カレンダーの日付に関係なく、ログインするたびに先頭から順番に報酬が配布されます。

既に今日のボーナスを受け取り済みの場合はエラーになります。
すべての報酬を配布し終えた後、「繰り返し」が有効な場合(ストリーミングモードのみ)は、最初の報酬に戻ってサイクルが再開されます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
bonusModelNamestring
~ 128文字ログインボーナスモデル名
ログインボーナスモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession
configList<EzConfig>[]0 ~ 32 itemsトランザクションの変数に適用する設定値

Result

説明
itemEzReceiveStatus受け取り状態
bonusModelEzBonusModelログインボーナスモデル
transactionIdstring発行されたトランザクションID
stampSheetstringログインボーナスの受け取りの実行に使用するスタンプシート
stampSheetEncryptionKeyIdstringスタンプシートの署名計算に使用した暗号鍵GRN
autoRunStampSheetboolトランザクションの自動実行が有効か
atomicCommitboolトランザクションをアトミックにコミットするか
transactionstring発行されたトランザクション
transactionResultEzTransactionResultトランザクション実行結果

Error

このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。

基底クラス説明
AlreadyReceivedExceptionBadRequestException今日のログインボーナスはすでに受け取っています。

実装例

try {
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Bonus(
    );
    var result = await domain.ReceiveAsync(
        bonusModelName: "bonus-0001",
        config: null
    );
} catch(Gs2.Gs2LoginReward.Exception.AlreadyReceivedException e) {
    // You have already received today's login bonus.
}
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Bonus(
    );
    var future = domain.ReceiveFuture(
        bonusModelName: "bonus-0001",
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2LoginReward.Exception.AlreadyReceivedException)
        {
            // You have already received today's login bonus.
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Bonus(
    );
    const auto Future = Domain->Receive(
        "bonus-0001" // bonusModelName
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::LoginReward::Error::FAlreadyReceivedError::Class))
        {
            // You have already received today's login bonus.
        }
        return false;
    }

getBonusModel

特定のログインボーナスのスケジュールを取得する

ボーナスモデル名を指定して、1つのログインボーナスモデルの詳細を取得します。
特定のボーナスの詳細画面を表示する際に使います。たとえば、7日分の報酬を一覧表示し、受け取り済みの日にチェックマークを付けるような画面です。

返却されるモデルには報酬リスト、ボーナスモード、繰り返し設定、取り逃がし救済の設定が含まれます。
GetReceiveStatus と組み合わせることで、どの日の報酬を受け取り済みで、どの日がまだ受け取れるかを把握できます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
bonusModelNamestring
~ 128文字ログインボーナスモデル名
ログインボーナスモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

Result

説明
itemEzBonusModelログインボーナスモデル

実装例

    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).BonusModel(
        bonusModelName: "bonus-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).BonusModel(
        bonusModelName: "bonus-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    )->BonusModel(
        "bonus-0001" // bonusModelName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
値の変更イベントハンドリング
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).BonusModel(
        bonusModelName: "bonus-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).BonusModel(
        bonusModelName: "bonus-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    )->BonusModel(
        "bonus-0001" // bonusModelName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::LoginReward::Model::FBonusModel> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

listBonusModels

ログインボーナスのスケジュール一覧を取得する

ネームスペースに設定されているすべてのログインボーナスモデルを取得します。
各モデルは報酬スケジュールを定義しています。1日目に何がもらえるか、2日目に何がもらえるか、といった内容です。

ログインボーナスの一覧画面を作る際に使います。
たとえば「7日間新人ボーナス」と「月間ログインボーナス」が同時に開催されている場合、このAPIで両方の情報を取得できます。

返却されるモデルには、ボーナスモード(スケジュール / ストリーミング)、日ごとの報酬リスト、繰り返しの有無、取り逃がし救済の可否が含まれます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。

Result

説明
itemsList<EzBonusModel>ログインボーナスモデルのリスト

実装例

    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.BonusModelsAsync(
    ).ToListAsync();
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.BonusModels(
    );
    List<EzBonusModel> items = new List<EzBonusModel>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->BonusModels(
    );
    TArray<Gs2::UE5::LoginReward::Model::FEzBonusModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
値の変更イベントハンドリング
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeBonusModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeBonusModels(callbackId);
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeBonusModels(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeBonusModels(callbackId);
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeBonusModels(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeBonusModels(CallbackId);

getReceiveStatus

特定のボーナスの受け取り進捗を取得する

1つのログインボーナスモデルに対するプレイヤーの受け取り状態を取得します。
受け取り状態には、各日の受け取り済み/未受け取りを示す真偽値のリスト(receivedSteps)が含まれます。たとえば [true, true, false, true, false, false, false] は「1日目と2日目は受け取り済み、3日目は取り逃がし、4日目は受け取り済み、5〜7日目はまだ」という意味です。

GetBonusModel と組み合わせて、各日の報酬内容と受け取り状況を並べて表示するログインボーナス詳細画面を作るのに使います。

レスポンスにはボーナスモデルの情報も含まれるため、1回のAPI呼び出しで報酬内容と受け取り状況の両方を表示できます。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
bonusModelNamestring
~ 128文字ボーナスモデル名
この受け取り状態が紐づくログインボーナスモデルの名前。
ユーザーの受け取り進捗を特定のボーナスモデル定義に関連づけ、どの報酬リストと配布ルールが適用されるかを決定します。
gameSessionGameSession
GameSession

Result

説明
itemEzReceiveStatus受け取り状態
bonusModelEzBonusModelログインボーナスモデル

実装例

    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).ReceiveStatus(
        bonusModelName: "bonus-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).ReceiveStatus(
        bonusModelName: "bonus-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->ReceiveStatus(
        "bonus-0001" // bonusModelName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
値の変更イベントハンドリング
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).ReceiveStatus(
        bonusModelName: "bonus-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).ReceiveStatus(
        bonusModelName: "bonus-0001"
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.Subscribe(
        value => {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->ReceiveStatus(
        "bonus-0001" // bonusModelName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::LoginReward::Model::FReceiveStatus> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

    // イベントハンドリングを停止
    Domain->Unsubscribe(CallbackId);

listReceiveStatuss

全ボーナスの受け取り進捗を一覧で取得する

プレイヤーが関わったすべてのログインボーナスモデルの受け取り状態を取得します。
各状態から、どの日の報酬を受け取り済みで、どの日がまだ受け取れるかがわかります。

ログインボーナスの概要画面を作る際に使います。たとえば「7日間新人ボーナス: 4/7受け取り済み」「月間ボーナス: 12/30受け取り済み」のように進捗を表示できます。

ゲーム起動時に未受け取りのボーナスがあるかどうかを確認し、プレイヤーに受け取りを促すのにも便利です。

Request

有効化条件必須デフォルト値の制限説明
namespaceNamestring
~ 128文字ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。
gameSessionGameSession
GameSession

Result

説明
itemsList<EzReceiveStatus>受け取り状態のリスト
nextPageTokenstringリストの続きを取得するためのページトークン

実装例

    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.ReceiveStatusesAsync(
    ).ToListAsync();
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.ReceiveStatuses(
    );
    List<EzReceiveStatus> items = new List<EzReceiveStatus>();
    while (it.HasNext())
    {
        yield return it.Next();
        if (it.Error != null)
        {
            onError.Invoke(it.Error, null);
            break;
        }
        if (it.Current != null)
        {
            items.Add(it.Current);
        }
        else
        {
            break;
        }
    }
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->ReceiveStatuses(
    );
    TArray<Gs2::UE5::LoginReward::Model::FEzReceiveStatusPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
値の変更イベントハンドリング
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeReceiveStatuses(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeReceiveStatuses(callbackId);
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    
    // イベントハンドリングを開始
    var callbackId = domain.SubscribeReceiveStatuses(
        () => {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    domain.UnsubscribeReceiveStatuses(callbackId);
    const auto Domain = Gs2->LoginReward->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->SubscribeReceiveStatuses(
        []() {
            // リストの要素が変化した時に呼び出される
        }
    );

    // イベントハンドリングを停止
    Domain->UnsubscribeReceiveStatuses(CallbackId);