> For the complete documentation index, see [llms.txt](/llms.txt)

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

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



## モデル

### EzReceiveStatus

受け取り状態<br>

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

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

**関連するメソッド:**
missedReceive - 取り逃がしたログインボーナスを受け取る
receive - 今日のログインボーナスを受け取る
getReceiveStatus - 特定のボーナスの受け取り進捗を取得する
listReceiveStatuss - 全ボーナスの受け取り進捗を一覧で取得する


---

### EzBonusModel

ログインボーナスモデル<br>

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

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

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

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

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | ログインボーナスモデル名<br>ログインボーナスモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| mode | 文字列列挙型<br>enum {<br>&nbsp;&nbsp;"schedule",<br>&nbsp;&nbsp;"streaming"<br>}<br> |  | ✓ |  |  | モード<br>ログインボーナスの配布スケジュールの種類を指定します。<br>「schedule」モードでは、GS2-Schedule のイベント開始日からの経過日数に基づいて報酬が配布されます。<br>「streaming」モードでは、カレンダーの日付に関係なく、毎日先頭から順番に報酬が配布されます。"schedule": スケジュールモード / "streaming": ストリーミングモード /  |
| periodEventId | string |  |  |  |  ~ 1024文字 | 期間イベントGRN<br>ログインボーナスを有効化する期間を表す GS2-Schedule のイベントGRN。<br>スケジュールモードでは必須で、報酬配布の経過日数を計算する起点の開始日を決定します。<br>ストリーミングモードでは省略可能ですが、指定した場合はイベント開始日からの経過日数より先のボーナスは受け取れなくなります。 |
| resetHour | int | {periodEventId} == "" | ✓※ |  | 0 ~ 23 | リセット時間（UTC）<br>受け取りフラグがリセットされる時刻（0-23、UTC）。<br>ログインボーナスにおける日付の切り替わりタイミングを決定します。<br>periodEventId が未指定の場合にのみ必要です。イベントが設定されている場合、リセットタイミングはイベントのスケジュールに従います。<br><br>※ periodEventId が "" であれば 必須 |
| repeat | 文字列列挙型<br>enum {<br>&nbsp;&nbsp;"enabled",<br>&nbsp;&nbsp;"disabled"<br>}<br> | {mode} == "streaming" | ✓※ |  |  | 繰り返し<br>全ての報酬を配布し終えた後に、先頭から再度配布を行うかどうか。<br>ストリーミングモードでのみ有効です。有効にすると、最後の報酬を配布した後に最初の報酬に戻ってループします。<br>注意: 繰り返しが有効な場合、取り逃がし救済機能は使用できません。"enabled": 有効 / "disabled": 無効 / <br><br>※ mode が "streaming" であれば 必須 |
| rewards | [List&lt;EzReward&gt;](#ezreward) |  |  |  | 0 ~ 100 items | 報酬リスト<br>日毎の報酬の順序付きリスト。各エントリは1日分のログインボーナスに対応し、インデックス 0 から順に配布されます。<br>スケジュールモードでは、インデックスはイベント開始日からの経過日数に対応します。<br>ストリーミングモードでは、インデックスはログイン日数に対応します。最大100エントリまで設定可能です。 |
| missedReceiveRelief | 文字列列挙型<br>enum {<br>&nbsp;&nbsp;"enabled",<br>&nbsp;&nbsp;"disabled"<br>}<br> |  |  | "disabled" |  | 取り逃がし救済機能<br>取り逃がしたボーナスの救済機能を有効にするかどうか。有効にすると、ユーザーは指定されたコスト（消費アクション）を支払うことで、受け取り損ねたボーナスを遡って受け取ることができます。<br>任意で、救済の許可前に条件を確認する検証アクションも設定できます。<br>ストリーミングモードかつ繰り返しが有効な場合は使用できません。デフォルトは「disabled」です。"enabled": 有効 / "disabled": 無効 /  |
| missedReceiveReliefVerifyActions | [List&lt;EzVerifyAction&gt;](#ezverifyaction) | {missedReceiveRelief} == "enabled" |  | [] | 0 ~ 10 items | 取り逃がし救済の検証アクションリスト<br>取り逃がし救済を許可する前に実行される検証アクションのリスト。<br>救済処理の前にユーザーの資格などの前提条件をチェックします。最大10個まで設定できます。<br>missedReceiveRelief が有効な場合にのみ適用されます。<br><br>※ missedReceiveRelief が "enabled" であれば 有効 |
| missedReceiveReliefConsumeActions | [List&lt;EzConsumeAction&gt;](#ezconsumeaction) | {missedReceiveRelief} == "enabled" |  | [] | 0 ~ 10 items | 取り逃がし救済の消費アクションリスト<br>取り逃がしたボーナスを救済するためにユーザーが支払うコストを定義する消費アクションのリスト。<br>例えば、ゲーム内通貨やアイテムを救済コストとして消費するよう設定できます。最大10個まで設定できます。<br>missedReceiveRelief が有効な場合にのみ適用されます。<br><br>※ missedReceiveRelief が "enabled" であれば 有効 |

**関連するメソッド:**
missedReceive - 取り逃がしたログインボーナスを受け取る
receive - 今日のログインボーナスを受け取る
getBonusModel - 特定のログインボーナスのスケジュールを取得する
listBonusModels - ログインボーナスのスケジュール一覧を取得する
getReceiveStatus - 特定のボーナスの受け取り進捗を取得する


---

### EzReward

報酬<br>

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

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


**関連するモデル:**
EzBonusModel - ログインボーナスモデル



---

### EzConfig

コンフィグ設定<br>

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

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

**関連するメソッド:**
missedReceive - 取り逃がしたログインボーナスを受け取る
receive - 今日のログインボーナスを受け取る


---

### EzConsumeAction

消費アクション<br>

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

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


**関連するモデル:**
EzBonusModel - ログインボーナスモデル



---

### EzVerifyAction

検証アクション<br>

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

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


**関連するモデル:**
EzBonusModel - ログインボーナスモデル



---

### EzAcquireAction

入手アクション<br>

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

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


**関連するモデル:**
EzReward - 報酬



---

### EzVerifyActionResult

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

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


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzConsumeActionResult

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

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


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzAcquireActionResult

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

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


**関連するモデル:**
EzTransactionResult - トランザクション実行結果



---

### EzTransactionResult

トランザクション実行結果<br>

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string |  | ✓ |  | 36 ~ 36文字 | トランザクションID |
| verifyResults | [List&lt;EzVerifyActionResult&gt;](#ezverifyactionresult) |  |  |  | 0 ~ 10 items | 検証アクションの実行結果リスト |
| consumeResults | [List&lt;EzConsumeActionResult&gt;](#ezconsumeactionresult) |  |  | [] | 0 ~ 10 items | 消費アクションの実行結果リスト |
| acquireResults | [List&lt;EzAcquireActionResult&gt;](#ezacquireactionresult) |  |  | [] | 0 ~ 100 items | 入手アクションの実行結果リスト |

**関連するメソッド:**
missedReceive - 取り逃がしたログインボーナスを受け取る
receive - 今日のログインボーナスを受け取る


---

## メソッド

### missedReceive

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

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

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

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

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzReceiveStatus](#ezreceivestatus) | 受け取り状態|
| bonusModel | [EzBonusModel](#ezbonusmodel) | ログインボーナスモデル|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | ログインボーナスの受け取りの実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|

#### Error

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

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

#### 実装例




**Unity (UniTask)**
```csharp

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() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    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() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    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

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

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

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

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

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzReceiveStatus](#ezreceivestatus) | 受け取り状態|
| bonusModel | [EzBonusModel](#ezbonusmodel) | ログインボーナスモデル|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | ログインボーナスの受け取りの実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|

#### Error

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

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

#### 実装例




**Unity (UniTask)**
```csharp

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() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    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() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    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

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

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

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

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzBonusModel](#ezbonusmodel) | ログインボーナスモデル|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).BonusModel(
        bonusModelName: "bonus-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).BonusModel(
        bonusModelName: "bonus-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    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;
    }

```


##### 値の変更イベントハンドリング




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

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

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

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

### listBonusModels

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

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

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

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

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzBonusModel&gt;](#ezbonusmodel) | ログインボーナスモデルのリスト|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.BonusModelsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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());
    }

```


##### 値の変更イベントハンドリング




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

    // イベントハンドリングを停止
    domain.UnsubscribeBonusModels(callbackId);

```

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

    // イベントハンドリングを停止
    domain.UnsubscribeBonusModels(callbackId);

```

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

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

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

### getReceiveStatus

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

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

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

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

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzReceiveStatus](#ezreceivestatus) | 受け取り状態|
| bonusModel | [EzBonusModel](#ezbonusmodel) | ログインボーナスモデル|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).ReceiveStatus(
        bonusModelName: "bonus-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    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;

```

**Unreal Engine 5**
```cpp
    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;
    }

```


##### 値の変更イベントハンドリング




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

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

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

    // イベントハンドリングを停止
    domain.Unsubscribe(callbackId);

```

**Unreal Engine 5**
```cpp
    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);

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---

### listReceiveStatuss

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

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

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

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

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzReceiveStatus&gt;](#ezreceivestatus) | 受け取り状態のリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.LoginReward.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.ReceiveStatusesAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    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;
        }
    }

```

**Unreal Engine 5**
```cpp
    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());
    }

```


##### 値の変更イベントハンドリング




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

    // イベントハンドリングを停止
    domain.UnsubscribeReceiveStatuses(callbackId);

```

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

    // イベントハンドリングを停止
    domain.UnsubscribeReceiveStatuses(callbackId);

```

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

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

```


{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。

ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。

そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}

---