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

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

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



## モデル

### EzMessage

メッセージ<br>

ゲームプレイヤー毎に用意されるメッセージボックスに届けられたメッセージデータ。<br>

メッセージには開封状態がある他、開封時に実行する入手アクションを設定することができます。<br>
メッセージには有効期限を設定でき、有効期限が切れたメッセージは、未読状態、開封後の既読状態にかかわらず、自動的に削除されます。<br>
添付された報酬を受け取っていない場合でも削除されます。

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| messageId | string |  | ※ |  |  ~ 1024文字 | メッセージGRN<br>※ サーバーが自動で設定 |
| name | string |  | ✓ | UUID |  ~ 36文字 | メッセージ名<br>メッセージの一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各メッセージを識別するために使用されます。 |
| metadata | string |  | ✓ |  |  ~ 4096文字 | メタデータ<br>メッセージのタイトル、本文、送信者情報、表示パラメータなどを含むJSON文字列など、メッセージの内容を表す任意のデータです。GS2はこの値を解釈せず、メッセージUIの描画のためにゲームクライアントにそのまま渡されます。最大4096文字です。 |
| isRead | bool |  |  | false |  | 既読状態<br>メッセージがユーザーによって開封されたかどうかを示します。メッセージが開封されると、このフラグがtrueに設定され、readAcquireActions が実行されて添付報酬が配布され、readAt タイムスタンプが記録されます。ネームスペースで isAutomaticDeletingEnabled が設定されている場合、既読後にメッセージは削除されます。 |
| readAcquireActions | [List&lt;EzAcquireAction&gt;](#ezacquireaction) |  |  | [] | 0 ~ 100 items | 開封時入手アクション<br>ユーザーがこのメッセージを開封した際に実行される入手アクションのリストです。アイテム、通貨、リソースなどの報酬をメッセージに添付するために使用されます。複数のアクションを組み合わせて異なる種類の報酬を同時に付与できます。メッセージあたり最大100アクションです。 |
| receivedAt | long |  | ※ | 現在時刻 |  | 作成日時<br>UNIX 時間・ミリ秒<br>※ サーバーが自動で設定 |
| readAt | long |  |  | 0 |  | 開封日時<br>UNIX 時間・ミリ秒 |
| expiresAt | long |  |  |  |  | 有効期限日時<br>UNIX 時間・ミリ秒 |

**関連するメソッド:**
batchRead - 複数のメッセージを一括開封してまとめて報酬を受け取る
delete - プレゼントボックスからメッセージを削除する
get - 特定のメッセージの詳細を取得する
list - プレイヤーのプレゼントボックスにあるメッセージの一覧を取得する
read - メッセージを開封して報酬を受け取る
receiveGlobalMessage - 全プレイヤー宛てのメッセージを受信する


---

### EzConfig

コンフィグ設定<br>

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

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string |  | ✓ |  |  ~ 64文字 | 名前 |
| value | string |  |  |  |  ~ 51200文字 | 値 |


---

### EzAcquireAction

入手アクション<br>

報酬としてメッセージに添付される単一の入手アクションを表します。アクションタイプ（例：インベントリへのアイテム追加、通貨増加）とそのリクエストパラメータで構成されます。メッセージが開封されると、これらのアクションがトランザクションに組み立てられ、実行されてユーザーに報酬が配布されます。

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


**関連するモデル:**
EzMessage - メッセージ



---

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

**関連するメソッド:**
batchRead - 複数のメッセージを一括開封してまとめて報酬を受け取る
read - メッセージを開封して報酬を受け取る


---

## メソッド

### batchRead

複数のメッセージを一括開封してまとめて報酬を受け取る<br>

最大10件のメッセージを一度に開封し、添付されたすべての報酬を1回の操作で付与します。<br>
指定したメッセージのいずれかがすでに開封済みの場合、エラーが返されどのメッセージも処理されません。これにより報酬の二重受け取りが確実に防止されます。<br>
プレゼントボックス画面の「一括開封」「すべて受け取る」ボタンに使います。プレイヤーがボタン1つで保留中の報酬をまとめて受け取れます。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzMessage&gt;](#ezmessage) | メッセージのリスト|
| 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>
一般的なエラーの種類や、ハンドリング方法は [こちら]() のドキュメントを参考にしてください。

| 型 | 基底クラス | 説明 |
| --- | --- | --- |
| MessageExpiredException | NotFoundException | メッセージが有効期限が切れています |

#### 実装例




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

try {
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var result = await domain.BatchReadAsync(
        messageNames: new List<string> {
            "message-0001",
            "message-0002",
        }
    );
} catch(Gs2.Gs2Inbox.Exception.MessageExpiredException e) {
    // Message has expired
}
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.BatchReadFuture(
        messageNames: new List<string> {
            "message-0001",
            "message-0002",
        }
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Inbox.Exception.MessageExpiredException)
        {
            // Message has expired
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->BatchRead(
        []
        {
            auto v = TOptional<TArray<FString>>();
            v->Add("message-0001");
            v->Add("message-0002");
            return v;
        }() // messageNames
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Inbox::Error::FMessageExpiredError::Class))
        {
            // Message has expired
        }
        return false;
    }

```


---

### delete

プレゼントボックスからメッセージを削除する<br>

開封済みかどうかに関わらず、プレイヤーのプレゼントボックスからメッセージを完全に削除します。<br>
プレゼントボックスの設定でメッセージ開封時に自動削除するように設定している場合は、手動で呼ぶ必要はありません。<br>
ただし、自動削除が無効の場合（開封済みメッセージがプレゼントボックスに残り続ける設定）は、このAPIでプレイヤーが受信箱を整理できるようにします。<br>
各メッセージの「削除」「破棄」ボタンに使います。たとえば、古い開封済みメッセージを不要なものとして削除するのに便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| messageName | string |  | ✓| UUID |  ~ 36文字 | メッセージ名<br>メッセージの一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各メッセージを識別するために使用されます。 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzMessage](#ezmessage) | 削除されたメッセージ|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var result = await domain.DeleteAsync(
    );

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.DeleteFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    const auto Future = Domain->Delete(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
    const auto Result = Future->GetTask().Result();

```


---

### get

特定のメッセージの詳細を取得する<br>

プレイヤーのプレゼントボックスにある特定のメッセージの全詳細を取得します。メタデータ（タイトル、本文など）、既読状態、添付された報酬、有効期限が含まれます。<br>
メッセージの詳細画面を表示するのに使います。たとえば「メンテナンス補填 — ご不便をおかけし申し訳ありません！お詫びにジェム100個をお送りします。[開封する]」のような画面です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| messageName | string |  | ✓| UUID |  ~ 36文字 | メッセージ名<br>メッセージの一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各メッセージを識別するために使用されます。 |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzMessage](#ezmessage) | メッセージ|

#### 実装例




**Unity (UniTask)**
```csharp
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var item = await domain.ModelAsync();

```

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

```

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

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### list

プレイヤーのプレゼントボックスにあるメッセージの一覧を取得する<br>

プレイヤーのプレゼントボックス（ギフトボックス / 受信箱）にあるすべてのメッセージを、新しい順に取得します。<br>
各メッセージにはプレイヤーが開封して受け取れる報酬（アイテム、通貨など）を含められます。<br>
既読状態でフィルタリングすることもできます。たとえば、未開封のメッセージのみや開封済みのみを表示できます。<br>
「プレゼントボックス」「ギフト」画面を構築するのに使います。たとえば「メンテナンス補填（ジェム x100）」「デイリーログインボーナス（ゴールド x500）」のようなリストに「開封」ボタンをつけて表示する画面に便利です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓|  |  | GameSession |
| isRead | bool |  | |  |  | 既読状態 |
| pageToken | string |  | |  |  ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int |  | | 30 | 1 ~ 1000 | データの取得件数 |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| items | [List&lt;EzMessage&gt;](#ezmessage) | メッセージのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|

#### 実装例




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

```

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

```


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




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

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

```

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

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

```

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

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

```


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

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

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

---

### read

メッセージを開封して報酬を受け取る<br>

指定したメッセージを開封し、添付された報酬（アイテム、通貨など）をプレイヤーに付与します。<br>
メッセージは既読になり、報酬の付与が1回の操作で行われます。すでに開封済みの場合は、報酬の二重受け取りを防ぐためにエラーが返されます。<br>
報酬が添付されていないメッセージの場合は、単純に既読としてマークされます。<br>
プレゼントボックスの各メッセージの「開封」「受け取る」ボタンに使います。たとえば、プレイヤーが「開封」をタップすると「ジェム x100」を受け取る、といった動作です。

#### Request

|  | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string |  | ✓|  |  ~ 128文字 | ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| messageName | string |  | ✓| UUID |  ~ 36文字 | メッセージ名<br>メッセージの一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各メッセージを識別するために使用されます。 |
| gameSession | GameSession | | ✓|  |  | GameSession |

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [EzMessage](#ezmessage) | メッセージ|
| 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>
一般的なエラーの種類や、ハンドリング方法は [こちら]() のドキュメントを参考にしてください。

| 型 | 基底クラス | 説明 |
| --- | --- | --- |
| MessageExpiredException | NotFoundException | メッセージが有効期限が切れています |

#### 実装例




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

try {
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var result = await domain.ReadAsync(
    );
} catch(Gs2.Gs2Inbox.Exception.MessageExpiredException e) {
    // Message has expired
}
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Message(
        messageName: "message-0001"
    );
    var future = domain.ReadFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        if (future.Error is Gs2.Gs2Inbox.Exception.MessageExpiredException)
        {
            // Message has expired
        }
        onError.Invoke(future.Error, null);
        yield break;
    }
    // New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
    // エラーが発生すると TransactionException がスローされます。
    // TransactionException::Retry() でリトライが可能です。

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Message(
        "message-0001" // messageName
    );
    const auto Future = Domain->Read(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        auto e = Future->GetTask().Error();
        if (e->IsChildOf(Gs2::Inbox::Error::FMessageExpiredError::Class))
        {
            // Message has expired
        }
        return false;
    }

```


---

### receiveGlobalMessage

全プレイヤー宛てのメッセージを受信する<br>

グローバルメッセージ（メンテナンス補填やイベント報酬など、全プレイヤーに一括送信されたメッセージ）を確認し、まだ受け取っていないものをプレイヤーのプレゼントボックスに届けます。<br>
各グローバルメッセージはプレイヤーの受信箱の個別メッセージに変換されます。すでに受信済みのメッセージはスキップされるため、複数回呼んでも安全です。<br>
プレイヤーがプレゼントボックス画面を開いた時やログイン時に呼んで、すべてのグローバルメッセージを確実に受け取れるようにしてください。<br>
プレゼントボックスの初期化の一部として使います。メッセージ一覧を取得する前に呼ぶことで、プレイヤーがすべてのギフトを確認できるようになります。

#### Request

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

#### Result

|  | 型 | 説明 |
| --- | --- | --- |
| item | [List&lt;EzMessage&gt;](#ezmessage) | 受信したメッセージ一覧|

#### 実装例




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

```

**Unity (Vanilla)**
```cs
    var domain = gs2.Inbox.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var future = domain.ReceiveGlobalMessageFuture(
    );
    yield return future;
    if (future.Error != null)
    {
        onError.Invoke(future.Error, null);
        yield break;
    }
    var future2 = future.Result.ModelFuture();
    yield return future2;
    if (future2.Error != null)
    {
        onError.Invoke(future2.Error, null);
        yield break;
    }
    var result = future2.Result;

```

**Unreal Engine 5**
```cpp
    const auto Domain = Gs2->Inbox->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto Future = Domain->ReceiveGlobalMessage(
    );
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        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();

```


---

## イベントハンドラ

### OnReceiveNotification

メッセージを受信した時に使用するプッシュ通知

 | 名前 | 型 | 説明 |
| --- | --- | --- |
| namespaceName | string |ネームスペース名<br>ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。|
| userId | string |ユーザーID|
| messageName | string |メッセージ名<br>メッセージの一意な名前を保持します。<br>名前は UUID（Universally Unique Identifier）フォーマットで自動的に生成され、各メッセージを識別するために使用されます。|

#### 実装例





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

    gs2.Inbox.OnReceiveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var messageName = notification.MessageName;
    };
```

**Unity (Vanilla)**
```cs

    gs2.Inbox.OnReceiveNotification += notification =>
    {
        var namespaceName = notification.NamespaceName;
        var userId = notification.UserId;
        var messageName = notification.MessageName;
    };
```

**Unreal Engine 5**
```cpp

    Gs2->Inbox->OnReceiveNotification().AddLambda([](const auto Notification)
    {
        const auto NamespaceName = Notification->NamespaceNameValue;
        const auto UserId = Notification->UserIdValue;
        const auto MessageName = Notification->MessageNameValue;
    });
```


---