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> | [] | 開封時に実行する入手アクション | ||
receivedAt | long | ✓ | 作成日時 | ||
readAt | long | ✓ | 0 | 開封日時 | |
expiresAt | long | 有効期限日時 |
EzConfig
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
key | string | ✓ | ~ 64文字 | 名前 | |
value | string | ~ 51200文字 | 値 |
EzAcquireAction
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
action | enum [] | ✓ | ~ 128文字 | スタンプシートを使用して実行するアクションの種類 | |
request | string | ✓ | ~ 1048576文字 | リクエストのJSON |
メソッド
delete
メッセージを削除する
プレゼントボックスの設定でメッセージを開封したときに自動的に削除するオプションを付けていない場合は、このAPIを使用して明示的にメッセージを削除する必要があります。
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
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.Delete(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
const auto Domain = Gs2->Inbox->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->Message(
"message-0001" // messageName
);
const auto Future = Domain->Delete(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
get
メッセージを取得
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
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.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Inbox->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->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.Model();
yield return future;
var item = future.Result;
const auto Domain = Gs2->Inbox->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->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 | ✓ | ~ 32文字 | ネームスペース名 | |
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(
AccessToken
);
const auto It = Domain->Messages( // isRead
);
for (auto Item : *It)
{
}
値の変更イベントハンドリング
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(
AccessToken
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeMessages(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeMessages(CallbackId);
Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
read
メッセージを既読にする
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
messageName | string | ✓ | UUID | ~ 36文字 | メッセージ名 |
accessToken | string | ✓ | ~ 128文字 | ユーザーID |
Result
型 | 説明 | |
---|---|---|
item | EzMessage | メッセージ |
transactionId | string | 発行されたスタンプシートのトランザクションID |
stampSheet | string | スタンプシート |
stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN |
autoRunStampSheet | bool | スタンプシートの自動実行が有効か |
実装例
var domain = gs2.Inbox.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Message(
messageName: "message-0001"
);
var result = await domain.ReadAsync(
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry().
var domain = gs2.Inbox.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Message(
messageName: "message-0001"
);
var future = domain.Read(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// you can retry with TransactionException::Retry().
const auto Domain = Gs2->Inbox->Namespace(
"namespace-0001" // namespaceName
)->Me(
AccessToken
)->Message(
"message-0001" // messageName
);
const auto Future = Domain->Read(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
receiveGlobalMessage
グローバルメッセージを受信する
Request
型 | 必須 | デフォルト | 値の制限 | 説明 | |
---|---|---|---|---|---|
namespaceName | string | ✓ | ~ 32文字 | ネームスペース名 | |
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.ReceiveGlobalMessage(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.Model();
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(
AccessToken
);
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 (!TestFalse(WHAT, Future2->GetTask().IsError())) return false;
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;
});