GS2-Inbox SDK for Game Engine API リファレンス
モデル
EzMessage
メッセージ
ゲームプレイヤー毎に用意されるメッセージボックスに届けられたメッセージデータ。
メッセージには開封状態がある他、開封時に実行する入手アクションを設定することができます。
メッセージには有効期限を設定でき、有効期限が切れたメッセージは、未読状態、開封後の既読状態にかかわらず、自動的に削除されます。
添付された報酬を受け取っていない場合でも削除されます。
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
messageId | string | ✓ | ~ 1024文字 | メッセージGRN | |
name | string | ✓ | UUID | ~ 36文字 | メッセージ名 |
metadata | string | ✓ | ~ 4096文字 | メッセージの内容に相当するメタデータ | |
isRead | bool | ✓ | false | 既読状態 | |
readAcquireActions | List<EzAcquireAction> | [] | ~ 100 items | 開封時に実行する入手アクション | |
receivedAt | long | ✓ | 現在時刻 | 作成日時 (UNIX時間 単位:ミリ秒) | |
readAt | long | ✓ | 0 | 開封日時 (UNIX時間 単位:ミリ秒) | |
expiresAt | long | 有効期限日時 (UNIX時間 単位:ミリ秒) |
EzConfig
コンフィグ設定
トランザクションの変数に適用する設定値
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
key | string | ✓ | ~ 64文字 | 名前 | |
value | string | ~ 51200文字 | 値 |
EzAcquireAction
入手アクション
EzVerifyActionResult
検証アクションの実行結果
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
action | enum { } | ✓ | ~ 128文字 | 検証アクションで実行するアクションの種類 | |
verifyRequest | string | ✓ | ~ 1048576文字 | リクエストのJSON | |
statusCode | int | ~ 999 | ステータスコード | ||
verifyResult | string | ~ 1048576文字 | 結果内容 |
action に指定する列挙型の定義
定義 | 説明 |
---|
EzConsumeActionResult
消費アクションの実行結果
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
action | enum { } | ✓ | ~ 128文字 | 消費アクションで実行するアクションの種類 | |
consumeRequest | string | ✓ | ~ 1048576文字 | リクエストのJSON | |
statusCode | int | ~ 999 | ステータスコード | ||
consumeResult | string | ~ 1048576文字 | 結果内容 |
action に指定する列挙型の定義
定義 | 説明 |
---|
EzAcquireActionResult
入手アクションの実行結果
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
action | enum { } | ✓ | ~ 128文字 | 入手アクションで実行するアクションの種類 | |
acquireRequest | string | ✓ | ~ 1048576文字 | リクエストのJSON | |
statusCode | int | ~ 999 | ステータスコード | ||
acquireResult | string | ~ 1048576文字 | 結果内容 |
action に指定する列挙型の定義
定義 | 説明 |
---|
EzTransactionResult
トランザクション実行結果
サーバーサイドでのトランザクションの自動実行機能を利用して実行されたトランザクションの実行結果
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
transactionId | string | ✓ | 36 ~ 36文字 | トランザクションID | |
verifyResults | List<EzVerifyActionResult> | ~ 10 items | 検証アクションの実行結果リスト | ||
consumeResults | List<EzConsumeActionResult> | ~ 10 items | 消費アクションの実行結果リスト | ||
acquireResults | List<EzAcquireActionResult> | ~ 100 items | 入手アクションの実行結果リスト |
メソッド
delete
メッセージを削除する
プレゼントボックスの設定でメッセージを開封したときに自動的に削除するオプションを付けていない場合は、このAPIを使用して明示的にメッセージを削除する必要があります。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
messageName | string | ✓ | UUID | ~ 36文字 | メッセージ名 |
Result
型 | 説明 | |
---|---|---|
item | EzMessage | 削除されたメッセージ |
実装例
var domain = gs2.Inbox.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Message(
messageName: "message-0001"
);
var result = await domain.DeleteAsync(
);
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;
}
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
メッセージを取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
messageName | string | ✓ | UUID | ~ 36文字 | メッセージ名 |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
item | EzMessage | メッセージ |
実装例
var domain = gs2.Inbox.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Message(
messageName: "message-0001"
);
var item = await domain.ModelAsync();
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;
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;
}
値の変更イベントハンドリング
var domain = gs2.Inbox.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Message(
messageName: "message-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
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;
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);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
list
プレゼントボックス に届いているメッセージの一覧を取得
メッセージは最新のメッセージから順番に取得できます。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID | |
isRead | bool | 既読状態 | |||
pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | ||
limit | int | ✓ | 30 | 1 ~ 1000 | データの取得件数 |
Result
型 | 説明 | |
---|---|---|
items | List<EzMessage> | メッセージのリスト |
nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
var domain = gs2.Inbox.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.MessagesAsync(
).ToListAsync();
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;
}
}
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());
}
値の変更イベントハンドリング
var domain = gs2.Inbox.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeMessages(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeMessages(callbackId);
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;
}
}
const auto Domain = Gs2->Inbox->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeMessages(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeMessages(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
read
メッセージを既読にする
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
messageName | string | ✓ | UUID | ~ 36文字 | メッセージ名 |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
item | EzMessage | メッセージ |
transactionId | string | 発行されたトランザクションID |
stampSheet | string | スタンプシート |
stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN |
autoRunStampSheet | bool | トランザクションの自動実行が有効か |
atomicCommit | bool | トランザクションをアトミックにコミットするか |
transaction | string | 発行されたトランザクション |
transactionResult | EzTransactionResult | トランザクション実行結果 |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
型 | 基底クラス | 説明 |
---|---|---|
MessageExpiredException | NotFoundException | メッセージが有効期限が切れています |
実装例
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.MessageExpired e) {
// Message has expired
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
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() でリトライが可能です。
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
グローバルメッセージを受信する
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 | |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
item | List<EzMessage> | 受信したメッセージ一覧 |
実装例
var domain = gs2.Inbox.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.ReceiveGlobalMessageAsync(
);
var item = await result.ModelAsync();
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;
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 | ネームスペース名 |
userId | string | ユーザーID |
messageName | string | メッセージ名 |
実装例
gs2.Inbox.OnReceiveNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
var messageName = notification.MessageName;
};
gs2.Inbox.OnReceiveNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var userId = notification.UserId;
var messageName = notification.MessageName;
};
Gs2->Inbox->OnReceiveNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto UserId = Notification->UserIdValue;
const auto MessageName = Notification->MessageNameValue;
});