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

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

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



## モデル

### EzShowcase

陳列棚<br>

`陳列棚`には陳列する商品を定義できます。<br>
また、`陳列棚`の商品の販売期間を設定することができます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | 陳列棚名<br>陳列棚固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br/>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| displayItems | [List&lt;EzDisplayItem&gt;](#ezdisplayitem) |  |  | [] | 1 ~ 1000 items | 陳列する商品リスト<br>この陳列棚に陳列される商品のリストです。各陳列商品は単一の商品または商品グループのいずれかです。販売期間イベントが終了または無効な商品は、陳列棚の取得時に自動的にフィルタリングされます。 |
| salesPeriodEventId | string |  |  |  |  ~ 1024文字 | 陳列棚の販売期間を設定した GS2-Schedule のイベントGRN<br>この陳列棚全体の販売期間を制御します。指定した場合、関連する GS2-Schedule のイベント期間中のみ陳列棚が利用可能になります。イベントが有効でない場合、陳列棚は空で返されます。 |

**関連するメソッド:**
getShowcase - ショップの陳列棚と商品を取得する


---

### EzDisplayItem

陳列する商品<br>

陳列棚に表示される商品です。単一の商品または商品グループのいずれかを参照できます。各陳列商品には、陳列棚全体の販売期間とは独立して GS2-Schedule イベントによる個別の販売期間を設定できます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| displayItemId | string |  | ✓ | UUID |  ~ 128文字 | 陳列商品ID<br>陳列商品の一意な名前を保持します。<br/>省略するとシステムによって UUID（Universally Unique Identifier）フォーマットで自動的に割り当てられます。 |
| type | 文字列列挙型<br>enum {<br>&nbsp;&nbsp;"salesItem",<br>&nbsp;&nbsp;"salesItemGroup"<br>}<br> |  | ✓ |  |  | 種類<br>表示する商品の種類です。「salesItem」は固定の対価と報酬を持つ単一商品です。「salesItemGroup」は複数の商品を順番に評価する商品グループで、ステップアップ価格や初回限定割引などに使用されます。"salesItem": 商品 / "salesItemGroup": 商品グループ /  |
| salesItem | [EzSalesItem](#ezsalesitem) | {type} == "salesItem" | ✓※ |  |  | 商品<br><br>※ type が "salesItem" であれば 必須 |
| salesItemGroup | [EzSalesItemGroup](#ezsalesitemgroup) | {type} == "salesItemGroup" | ✓※ |  |  | 商品グループ<br><br>※ type が "salesItemGroup" であれば 必須 |


**関連するモデル:**
EzShowcase - 陳列棚



---

### EzRandomDisplayItem

ランダム陳列棚に陳列された商品<br>

特定のユーザーに対してランダム陳列棚で抽選・表示された商品を表します。現在のローテーション期間における商品の対価、報酬、および購入回数の追跡情報を含みます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ | UUID |  ~ 128文字 | ランダム陳列商品名<br>ランダム陳列商品の一意な名前を保持します。<br/>省略するとシステムによって UUID（Universally Unique Identifier）フォーマットで自動的に割り当てられます。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br/>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| verifyActions | [List&lt;EzVerifyAction&gt;](#ezverifyaction) |  |  | [] | 0 ~ 10 items | 検証アクションリスト |
| consumeActions | [List&lt;EzConsumeAction&gt;](#ezconsumeaction) |  |  | [] | 0 ~ 10 items | 消費アクションリスト |
| acquireActions | [List&lt;EzAcquireAction&gt;](#ezacquireaction) |  |  | [] | 1 ~ 100 items | 入手アクションリスト |
| currentPurchaseCount | int |  | ✓ |  | 1 ~ 2147483646 | 現在の購入回数<br>現在のローテーション期間中にこの商品が購入された回数です。購入のたびに加算され、ローテーション期間が終了するとリセットされます。 |
| maximumPurchaseCount | int |  | ✓ |  | 1 ~ 2147483646 | 最大購入回数<br>現在のローテーション期間中にこの商品を購入できる最大回数です。currentPurchaseCount がこの値に達すると、次のローテーションまで購入できなくなります。 |

**関連するメソッド:**
getRandomShowcaseDisplayItem - ランダム陳列棚の特定の商品を取得する
listRandomShowcaseDisplayItems - ランダム陳列棚に現在表示されている商品一覧を取得する
randomShowcaseBuy - ランダム陳列棚の商品を購入する


---

### EzSalesItem

商品<br>

商品を購入するために必要となる対価と、商品を購入したときに得られる報酬を設定します。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | 商品名<br>商品固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br/>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| verifyActions | [List&lt;EzVerifyAction&gt;](#ezverifyaction) |  |  | [] | 0 ~ 10 items | 検証アクションリスト<br>購入前に実行される前提条件チェックです。すべての検証アクションが成功した後に消費・入手アクションが処理されます。購入資格の条件チェックに使用できます。 |
| consumeActions | [List&lt;EzConsumeAction&gt;](#ezconsumeaction) |  |  | [] | 0 ~ 10 items | 消費アクションリスト<br>購入対価としてリソースを消費するアクションです。商品グループの購入回数制御のために GS2-Limit の CountUp アクションを含めることができます。 |
| acquireActions | [List&lt;EzAcquireAction&gt;](#ezacquireaction) |  |  | [] | 1 ~ 100 items | 入手アクションリスト<br>購入報酬としてリソースを付与するアクションです。すべての消費アクションが正常に完了した後に実行されます。 |

**関連するメソッド:**
buy - 陳列棚の商品を購入する


**関連するモデル:**
EzDisplayItem - 陳列する商品
EzSalesItemGroup - 商品グループ



---

### EzSalesItemGroup

商品グループ<br>

商品グループは陳列棚に陳列するためのエンティティです。<br>
商品グループには複数の商品を所属させることができ、所属している商品の先頭から順番に購入可能かを判定し、一番最初に購入可能だと判定された商品が実際に陳列されます。<br>
初回のみ割引する商品や、ステップアップガチャのように購入回数によって商品の内容が変化する仕組みに使用できます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| name | string |  | ✓ |  |  ~ 128文字 | 商品グループ名<br>商品グループ固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string |  |  |  |  ~ 2048文字 | メタデータ<br>メタデータには任意の値を設定できます。<br/>これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| salesItems | [List&lt;EzSalesItem&gt;](#ezsalesitem) |  |  | [] | 2 ~ 10 items | 商品グループに含める商品<br>このグループ内の商品の順序付きリストです。GS2-Limit カウンターを使って先頭から順に購入可能かを判定し、最初に購入可能と判定された商品が表示されます。いずれも該当しない場合、リストの最後の商品がフォールバックとして使用されます。 |


**関連するモデル:**
EzDisplayItem - 陳列する商品



---

### EzConfig

コンフィグ設定<br>

トランザクションの変数に適用する設定値

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 64文字 | 名前<br>トランザクションテンプレートで置換される変数名です。入手アクションパラメータ内のプレースホルダーに対応します。 |
| value | string |  |  |  |  ~ 51200文字 | 値<br>トランザクションテンプレート内の対応する変数名に置換される値です。 |

**関連するメソッド:**
buy - 陳列棚の商品を購入する
randomShowcaseBuy - ランダム陳列棚の商品を購入する


---

### EzConsumeAction

消費アクション

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


**関連するモデル:**
EzRandomDisplayItem - ランダム陳列棚に陳列された商品
EzSalesItem - 商品



---

### EzVerifyAction

検証アクション

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


**関連するモデル:**
EzRandomDisplayItem - ランダム陳列棚に陳列された商品
EzSalesItem - 商品



---

### EzAcquireAction

入手アクション

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


**関連するモデル:**
EzRandomDisplayItem - ランダム陳列棚に陳列された商品
EzSalesItem - 商品



---

### 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 | 入手アクションの実行結果リスト |

**関連するメソッド:**
buy - 陳列棚の商品を購入する
randomShowcaseBuy - ランダム陳列棚の商品を購入する


---

## メソッド

### buy

陳列棚の商品を購入する<br>

陳列棚から特定の商品を購入します。<br>
プレイヤーが商品を購入すると、システムが購入フロー全体を自動的に処理します。条件のチェック（例: プレイヤーレベル）、コストの消費（例: ジェム100個）、報酬の付与（例: レア剣）がすべて自動で行われます。<br>
これらはすべて1つのトランザクションで処理されるため、支払いだけ行われてアイテムが届かないという状況は発生しません。<br>
プレイヤーがショップの商品の「購入」ボタンをタップした時に使います。たとえば「スターターパック」をジェム500個で購入し、スタミナポーション10個とゴールドチェスト1個を受け取るといった処理に便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| showcaseName | string |  | ✓|  |  ~ 128文字 | 陳列棚名<br>陳列棚固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| displayItemId | string |  | ✓| UUID |  ~ 128文字 | 陳列商品ID<br>陳列商品の一意な名前を保持します。<br/>省略するとシステムによって UUID（Universally Unique Identifier）フォーマットで自動的に割り当てられます。 |
| quantity | int |  | | 1 | 1 ~ 1000 | 購入数量 |
| config | [List&lt;EzConfig&gt;](#ezconfig) |  | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzSalesItem](#ezsalesitem) | 商品|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | 購入処理の実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Showcase(
        showcaseName: "showcase-0001"
    ).DisplayItem(
        displayItemId: "display-item-0001"
    );
    var result = await domain.BuyAsync(
        quantity: null,
        config: null
    );
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Showcase(
        showcaseName: "showcase-0001"
    ).DisplayItem(
        displayItemId: "display-item-0001"
    );
    var future = domain.BuyFuture(
        quantity: null,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Showcase->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Showcase(
        "showcase-0001" // showcaseName
    )->DisplayItem(
        "display-item-0001" // displayItemId
    );
    const auto Future = Domain->Buy(
        // quantity
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


---

### getShowcase

ショップの陳列棚と商品を取得する<br>

特定の陳列棚（ショップページ）と、その陳列棚に表示されている商品の一覧を取得します。<br>
陳列棚はゲーム内のショップ画面のようなものです。たとえば「ジェムショップ」「デイリーセール」「スペシャルオファー」などのページに相当します。<br>
各陳列棚には商品が並んでおり、各商品にはプレイヤーが支払うもの（コスト）と受け取るもの（報酬）が定義されています。<br>
陳列棚はスケジュールイベントに紐づけて特定の期間だけ表示させることもできます。たとえば、クリスマス期間だけ表示される「ホリデーショップ」のような使い方が可能です。<br>
ショップUIの構築に使います。たとえば、プレイヤーがショップ画面を開いた時に、商品一覧を価格と「購入」ボタンとともに表示するのに便利です。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzShowcase](#ezshowcase) | 陳列棚|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Showcase(
        showcaseName: "showcase-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Showcase(
        showcaseName: "showcase-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Showcase->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Showcase(
        "showcase-0001" // showcaseName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


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




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

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

```

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

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

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Showcase->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Showcase(
        "showcase-0001" // showcaseName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Showcase::Model::FShowcase> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

```


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

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

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

---

### getRandomShowcaseDisplayItem

ランダム陳列棚の特定の商品を取得する<br>

ランダム陳列棚に現在表示されている特定の商品の詳細を取得します。<br>
プレイヤーがランダムショップの特定商品をタップした時に詳細表示するのに使います。たとえば、詳細ポップアップでアイテムの説明、価格、「購入」ボタンを表示するのに便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| showcaseName | string |  | ✓|  |  ~ 128文字 | ランダム陳列棚名<br>ランダム陳列棚固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| displayItemName | string |  | ✓| UUID |  ~ 128文字 | ランダム陳列商品名<br>ランダム陳列商品の一意な名前を保持します。<br/>省略するとシステムによって UUID（Universally Unique Identifier）フォーマットで自動的に割り当てられます。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzRandomDisplayItem](#ezrandomdisplayitem) | 商品|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RandomShowcase(
        showcaseName: "showcase-0001"
    ).RandomDisplayItem(
        displayItemName: "display-item-0001"
    );
    var item = await domain.ModelAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RandomShowcase(
        showcaseName: "showcase-0001"
    ).RandomDisplayItem(
        displayItemName: "display-item-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Showcase->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RandomShowcase(
        "showcase-0001" // showcaseName
    )->RandomDisplayItem(
        "display-item-0001" // displayItemName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


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




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

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

```

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

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

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Showcase->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RandomShowcase(
        "showcase-0001" // showcaseName
    )->RandomDisplayItem(
        "display-item-0001" // displayItemName
    );
    
    // イベントハンドリングを開始
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Showcase::Model::FRandomDisplayItem> value) {
            // 値が変化した時に呼び出される
            // value には変更後の値が渡ってくる
        }
    );

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

```


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

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

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

---

### listRandomShowcaseDisplayItems

ランダム陳列棚に現在表示されている商品一覧を取得する<br>

プレイヤーに対してランダム陳列棚に現在表示されている商品を取得します。<br>
ランダム陳列棚は、商品プールからランダムに選ばれた商品が表示されるショップです。「デイリーセール」や「ミステリーショップ」のように、プレイヤーごとに異なる商品が表示されたり、定期的にラインナップが更新されたりします。<br>
たとえば、50種類の商品プールから毎日5つがランダムに選ばれ、深夜0時にリフレッシュされるといった仕組みです。<br>
表示される商品はプレイヤーごとに異なり、同じタイミングでも別のプレイヤーには別の商品が表示される場合があります。<br>
ランダムショップのUI構築に使います。たとえば「本日のセール」として5つのランダム商品と、次のリフレッシュまでのカウントダウンタイマーを表示するのに便利です。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzRandomDisplayItem&gt;](#ezrandomdisplayitem) | ランダム陳列棚の商品リスト|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RandomShowcase(
        showcaseName: "showcase-0001"
    );
    var items = await domain.RandomDisplayItemsAsync(
    ).ToListAsync();

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RandomShowcase(
        showcaseName: "showcase-0001"
    );
    var it = domain.RandomDisplayItems(
    );
    List<EzRandomDisplayItem> items = new List<EzRandomDisplayItem>();
    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->Showcase->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RandomShowcase(
        "showcase-0001" // showcaseName
    );
    const auto It = Domain->RandomDisplayItems(
    );
    TArray<Gs2::UE5::Showcase::Model::FEzRandomDisplayItemPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### randomShowcaseBuy

ランダム陳列棚の商品を購入する<br>

ランダム陳列棚から特定の商品を購入します。<br>
通常の陳列棚での購入と同様に、条件チェック、コストの消費、報酬の付与がすべて1つのトランザクションで自動的に処理されます。<br>
ランダム陳列棚から商品を購入すると、設定によってはその商品が売り切れになり、次のリフレッシュまで新しい商品は表示されません。<br>
プレイヤーがランダムショップの商品の「購入」ボタンをタップした時に使います。たとえば、デイリーセールでリフレッシュ前に割引された「レジェンダリー武器ボックス」を購入するといった処理に便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| showcaseName | string |  | ✓|  |  ~ 128文字 | ランダム陳列棚名<br>ランダム陳列棚固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| displayItemName | string |  | ✓| UUID |  ~ 128文字 | ランダム陳列商品名<br>ランダム陳列商品の一意な名前を保持します。<br/>省略するとシステムによって UUID（Universally Unique Identifier）フォーマットで自動的に割り当てられます。 |
| quantity | int |  | | 1 | 1 ~ 1000 | 購入数量 |
| config | [List&lt;EzConfig&gt;](#ezconfig) |  | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzRandomDisplayItem](#ezrandomdisplayitem) | 購入した商品|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | 購入処理の実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RandomShowcase(
        showcaseName: "showcase-0001"
    ).RandomDisplayItem(
        displayItemName: "display-item-0001"
    );
    var result = await domain.RandomShowcaseBuyAsync(
        quantity: 1,
        config: null
    );
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Showcase.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).RandomShowcase(
        showcaseName: "showcase-0001"
    ).RandomDisplayItem(
        displayItemName: "display-item-0001"
    );
    var future = domain.RandomShowcaseBuyFuture(
        quantity: 1,
        config: null
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Showcase->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->RandomShowcase(
        "showcase-0001" // showcaseName
    )->RandomDisplayItem(
        "display-item-0001" // displayItemName
    );
    const auto Future = Domain->RandomShowcaseBuy(
        1 // quantity
        // config
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }

```


---