GS2-Chat SDK for Game Engine API リファレンス
モデル
EzRoom
ルーム
ルームはチャットのメッセージを届けられる範囲を表しています。
GS2-Chat のルームには参加という概念はありません。
そのため、メッセージを受信するにはルームの名前を知っているだけでよく、ルームへの参加やメンバー登録は必要ありません。
ルームのメッセージを閲覧できるゲームプレイヤーを限定したい場合は2つの方法があります。
1つ目はルームにパスワードを設定することです。
2つ目はルームに設定可能なホワイトリストでゲームプレイヤーのユーザーIDを設定することで限定ができます。
パスワードを設定した場合、パスワードを知らなければゲームの管理者でもメッセージの取得が出来なくなることに注意してください。
これは日本国憲法で定められた通信の秘密に該当する可能性があるためです。
ルームを購読すると、ルームに対して新しいメッセージが送信された際に GS2-Gateway のプッシュ通知を受けることが可能です。
この通知機能を利用することで、ルームに対してポーリングすることなく新しいメッセージの有無を知ることが可能となります。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | UUID | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | |
| metadata | string | ~ 1024文字 | メタデータ メタデータには任意の値を設定できます。 これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 | |||
| whiteListUserIds | List<string> | [] | 0 ~ 1000 items | ルームにアクセス可能なユーザーIDリスト 設定すると、リストに含まれるユーザーのみがルームのメッセージを取得・投稿できるようになります。空の場合、ユーザーIDによるアクセス制限は適用されません(ただしパスワードは別途必要な場合があります)。 |
EzMessage
メッセージ
メッセージはルームに投稿されたデータです。
カテゴリというフィールドを持ちますので、メッセージの分類が可能です。
たとえば、カテゴリが 0 の場合は通常のテキストメッセージとして解釈し、1 の場合はスタンプ(ステッカー)として処理するようにクライアントを実行することができます。
投稿されたメッセージは投稿後、Chat Namespace の messageLifeTimeDays で設定したメッセージ保持期間が経過すると自動的に削除されます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | UUID | ~ 36文字 | メッセージ名 メッセージの一意な名前を保持します。 名前はUUID(Universally Unique Identifier)フォーマットで自動的に生成され、各メッセージを識別するために使用されます。 | |
| roomName | string | ✓ | UUID | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | |
| userId | string | ✓ | ~ 128文字 | ユーザーID | ||
| category | int | 0 | 0 ~ 2147483645 | メッセージの種類を分類したい時の種類番号 メッセージを分類するための数値です。例えば、0 は通常のテキストメッセージ、1 はスタンプ(ステッカー)、その他の値はカスタムメッセージタイプとして使用できます。カテゴリーにより、メッセージに適用される CategoryModel のルールが決まります。 | ||
| metadata | string | ✓ | ~ 1024文字 | メタデータ メタデータには任意の値を設定できます。 これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 | ||
| createdAt | long | ※ | 現在時刻 | 作成日時 UNIX 時間・ミリ秒 ※ サーバーが自動で設定 |
EzSubscribe
ルーム購読
ルームを購読することで、そのルームに対する新着メッセージの存在を即座に知ることが出来るようになります。
購読する際にはメッセージのカテゴリを指定できます。
この機能をうまく利用すれば重要度の高いメッセージのみ受信するような設定も可能です。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| userId | string | ✓ | ~ 128文字 | ユーザーID | ||
| roomName | string | ✓ | ~ 128文字 | 購読するルーム名 購読するチャットルームの名前です。購読すると、このルームに新しいメッセージが投稿されるたびに GS2-Gateway 経由でプッシュ通知が送信されます。 | ||
| notificationTypes | List<EzNotificationType> | [] | 0 ~ 100 items | 新着メッセージ通知を受け取るカテゴリリスト プッシュ通知をトリガーするメッセージカテゴリーをフィルタリングします。空の場合、すべてのカテゴリーで通知が送信されます。各エントリーはカテゴリー番号とオプションのモバイルプッシュ通知転送を指定します。 |
EzCategoryModel
カテゴリーモデル
カテゴリーモデルは、チャットルームに投稿されるメッセージを分類するためのカテゴリーを定義します。
各カテゴリーは数値で識別され、カテゴリーごとにプレイヤーのアクセストークンを使った投稿を許可するか拒否するかを設定できます。
これにより、サーバーのみが投稿可能なシステムアナウンスカテゴリーなどのユースケースを実現できます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| category | int | ✓ | 0 ~ 2147483645 | カテゴリー メッセージカテゴリーの数値識別子です。このカテゴリー番号で投稿されたメッセージは、プレイヤーの投稿を許可するかなど、このモデルで定義されたルールに従います。 | ||||||||
| rejectAccessTokenPost | 文字列列挙型 enum { “Enabled”, “Disabled” } | プレイヤーのアクセストークンを利用した投稿を拒否する 有効にすると、このカテゴリーではサーバーサイドの API 呼び出し(ユーザーID指定)のみがメッセージを投稿できます。プレイヤーが直接投稿すべきでないシステムアナウンスやサーバー生成メッセージに有用です。
|
EzNotificationType
通知タイプ
新着メッセージ通知を受け取るカテゴリの設定
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| category | int | 0 | 0 ~ 2147483646 | 新着メッセージ通知を受け取るカテゴリ 通知をフィルタリングするためのカテゴリーの数値識別子です。このカテゴリーに一致するメッセージのみが、購読に対するプッシュ通知をトリガーします。 | ||
| enableTransferMobilePushNotification | bool | false | オフラインだった時にモバイルプッシュ通知に転送するか 有効にすると、通知時に受信先デバイスがオフラインだった場合、モバイルプッシュ通知サービスに転送されます。これにより、ゲームが実行されていない場合でもプレイヤーに新着メッセージを通知できます。 |
メソッド
createRoom
チャットルームを作成する
プレイヤーがメッセージをやり取りできる新しいチャットルームを作成します。
ネームスペースの設定でプレイヤーによるルーム作成が許可されている必要があります。許可されていない場合は失敗します。
ルームにパスワードを設定することもできます。パスワードを設定した場合、メッセージの投稿・取得にはパスワードの入力が必要です。
ホワイトリストにユーザーIDを設定して、アクセスできるプレイヤーを制限することも可能です。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| name | string | UUID | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | GameSession ルームのオーナーのユーザーIDです。設定すると、オーナーのみがルームを削除できるようになります。オーナーの設定は任意です。 | ||||
| metadata | string | ~ 1024文字 | メタデータ メタデータには任意の値を設定できます。 これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 | |||
| password | string | ~ 128文字 | ルームにアクセスするために必要となるパスワード 設定すると、メッセージの取得・投稿時にパスワードの入力が必要になります。設定したパスワードは二度と参照できません。通信の秘密に該当する可能性があるため、ゲーム管理者でもパスワードを知らなければメッセージにアクセスできなくなります。 | |||
| whiteListUserIds | List<string> | [] | 0 ~ 1000 items | ルームにアクセス可能なユーザーIDリスト 設定すると、リストに含まれるユーザーのみがルームのメッセージを取得・投稿できるようになります。空の場合、ユーザーIDによるアクセス制限は適用されません(ただしパスワードは別途必要な場合があります)。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzRoom | 作成したルーム |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
|---|---|---|
| NoAccessPrivilegesException | BadRequestException | ルームに設定されたホワイトリストにログイン中のユーザーが含まれていません |
実装例
try {
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var result = await domain.CreateRoomAsync(
name: "room-0001",
metadata: null,
password: null,
whiteListUserIds: null
);
var item = await result.ModelAsync();
} catch(Gs2.Gs2Chat.Exception.NoAccessPrivilegesException e) {
// The whitelist configured for the room does not contain any currently logged in user.
} var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var future = domain.CreateRoomFuture(
name: "room-0001",
metadata: null,
password: null,
whiteListUserIds: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Chat.Exception.NoAccessPrivilegesException)
{
// The whitelist configured for the room does not contain any currently logged in user.
}
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->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto Future = Domain->CreateRoom(
"room-0001" // name
// metadata
// password
// whiteListUserIds
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Chat::Error::FNoAccessPrivilegesError::Class))
{
// The whitelist configured for the room does not contain any currently logged in user.
}
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();deleteRoom
チャットルームを削除する
プレイヤーが作成したチャットルームを削除します。
ルームを作成したプレイヤー(オーナー)のみが削除できます。
ルーム内のすべてのメッセージも一緒に削除されます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | UUID | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | |
| gameSession | GameSession | GameSession ルームのオーナーのユーザーIDです。設定すると、オーナーのみがルームを削除できるようになります。オーナーの設定は任意です。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzRoom | 削除したルーム |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
|---|---|---|
| NoAccessPrivilegesException | BadRequestException | ルームに設定されたホワイトリストにログイン中のユーザーが含まれていません |
実装例
try {
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
var result = await domain.DeleteRoomAsync(
);
} catch(Gs2.Gs2Chat.Exception.NoAccessPrivilegesException e) {
// The whitelist configured for the room does not contain any currently logged in user.
} var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
var future = domain.DeleteRoomFuture(
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Chat.Exception.NoAccessPrivilegesException)
{
// The whitelist configured for the room does not contain any currently logged in user.
}
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Room(
"room-0001", // roomName
nullptr // password
);
const auto Future = Domain->DeleteRoom(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Chat::Error::FNoAccessPrivilegesError::Class))
{
// The whitelist configured for the room does not contain any currently logged in user.
}
return false;
}
const auto Result = Future->GetTask().Result();getRoom
チャットルームの情報を取得する
指定したチャットルームのメタデータや作成日時などの情報を取得します。
ルームにパスワードが設定されていても、パスワードなしで取得できます。
プレイヤーがルームに入る前に、ルームの詳細(ルーム名やトピックなど)を表示する際に使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | UUID | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzRoom | ルーム |
実装例
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).User(
userId: null
).Room(
roomName: "room-0001",
password: null
);
var item = await domain.ModelAsync(); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).User(
userId: null
).Room(
roomName: "room-0001",
password: null
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->User(
nullptr // userId
)->Room(
"room-0001", // roomName
nullptr // password
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}値の変更イベントハンドリング
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).User(
userId: null
).Room(
roomName: "room-0001",
password: null
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).User(
userId: null
).Room(
roomName: "room-0001",
password: null
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->User(
nullptr // userId
)->Room(
"room-0001", // roomName
nullptr // password
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Chat::Model::FRoom> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
getMessage
メッセージ名を指定してメッセージを1件取得する
メッセージ名(ID)を指定して、チャットルーム内のメッセージを1件取得します。
通知をタップしたときなど、特定のメッセージの詳細を表示する際に使います。
ルームにパスワードが設定されている場合は、パスワードの入力が必要です。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| messageName | string | ✓ | UUID | ~ 36文字 | メッセージ名 メッセージの一意な名前を保持します。 名前はUUID(Universally Unique Identifier)フォーマットで自動的に生成され、各メッセージを識別するために使用されます。 | |
| gameSession | GameSession | GameSession | ||||
| password | string | ~ 128文字 | パスワード |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzMessage | メッセージ |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
|---|---|---|
| NoAccessPrivilegesException | BadRequestException | ルームに設定されたホワイトリストにログイン中のユーザーが含まれていません |
| PasswordRequiredException | BadRequestException | ルームにアクセスするためにはパスワードの設定が必要です |
| PasswordIncorrectException | BadRequestException | ルームに設定されたパスワードと指定されたパスワードが一致しません |
実装例
try {
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
).Message(
messageName: "message-0001"
);
var item = await domain.ModelAsync();
} catch(Gs2.Gs2Chat.Exception.NoAccessPrivilegesException e) {
// The whitelist configured for the room does not contain any currently logged in user.
} catch(Gs2.Gs2Chat.Exception.PasswordRequiredException e) {
// A password must be set to access the room.
} catch(Gs2.Gs2Chat.Exception.PasswordIncorrectException e) {
// The password set for the room does not match the password specified.
} var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
).Message(
messageName: "message-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Room(
"room-0001", // roomName
nullptr // password
)->Message(
"message-0001" // messageName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Chat::Error::FNoAccessPrivilegesError::Class))
{
// The whitelist configured for the room does not contain any currently logged in user.
}
if (e->IsChildOf(Gs2::Chat::Error::FPasswordRequiredError::Class))
{
// A password must be set to access the room.
}
if (e->IsChildOf(Gs2::Chat::Error::FPasswordIncorrectError::Class))
{
// The password set for the room does not match the password specified.
}
return false;
}値の変更イベントハンドリング
try {
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
).Message(
messageName: "message-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
} catch(Gs2.Gs2Chat.Exception.NoAccessPrivilegesException e) {
// The whitelist configured for the room does not contain any currently logged in user.
} catch(Gs2.Gs2Chat.Exception.PasswordRequiredException e) {
// A password must be set to access the room.
} catch(Gs2.Gs2Chat.Exception.PasswordIncorrectException e) {
// The password set for the room does not match the password specified.
} var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
).Message(
messageName: "message-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Room(
"room-0001", // roomName
nullptr // password
)->Message(
"message-0001" // messageName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Chat::Model::FMessage> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listLatestMessages
チャットルームの最新メッセージを取得する
チャットルーム内の最新のメッセージを、新しい順に取得します。
プレイヤーがチャット画面を開いたときに直近のやり取りを表示する際に使います。
ルームにパスワードが設定されている場合は、パスワードの入力が必要です。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | UUID | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | |
| gameSession | GameSession | ✓ | GameSession | |||
| limit | int | 30 | 1 ~ 1000 | データの取得件数 | ||
| password | string | ~ 128文字 | ルームにアクセスするために必要となるパスワード 設定すると、メッセージの取得・投稿時にパスワードの入力が必要になります。設定したパスワードは二度と参照できません。通信の秘密に該当する可能性があるため、ゲーム管理者でもパスワードを知らなければメッセージにアクセスできなくなります。 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzMessage> | メッセージのリスト |
| nextPageToken | string | リストの続きを取得するためのページトークン |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
|---|---|---|
| NoAccessPrivilegesException | BadRequestException | ルームに設定されたホワイトリストにログイン中のユーザーが含まれていません |
| PasswordRequiredException | BadRequestException | ルームにアクセスするためにはパスワードの設定が必要です |
| PasswordIncorrectException | BadRequestException | ルームに設定されたパスワードと指定されたパスワードが一致しません |
実装例
try {
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
var items = await domain.LatestMessagesAsync(
).ToListAsync();
} catch(Gs2.Gs2Chat.Exception.NoAccessPrivilegesException e) {
// The whitelist configured for the room does not contain any currently logged in user.
} catch(Gs2.Gs2Chat.Exception.PasswordRequiredException e) {
// A password must be set to access the room.
} catch(Gs2.Gs2Chat.Exception.PasswordIncorrectException e) {
// The password set for the room does not match the password specified.
} var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
var it = domain.LatestMessages(
);
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->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Room(
"room-0001", // roomName
nullptr // password
);
const auto It = Domain->LatestMessages(
);
TArray<Gs2::UE5::Chat::Model::FEzMessagePtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}listMessages
チャットルームのメッセージを取得する(指定時刻以降)
startAt に指定した時刻以降に投稿されたメッセージを、古い順に取得します。
前回の確認以降の新着メッセージを取得したいとき(再接続時やチャット画面を開いたときなど)に使います。
ネームスペースの設定で指定された保持期間内のメッセージのみ取得できます。
ルームにパスワードが設定されている場合は、パスワードの入力が必要です。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | UUID | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | |
| gameSession | GameSession | ✓ | GameSession | |||
| startAt | long | 現在時刻から1時間前の絶対時刻 | メッセージの取得を開始する時刻 UNIX 時間・ミリ秒 | |||
| limit | int | 30 | 1 ~ 1000 | データの取得件数 | ||
| password | string | ~ 128文字 | ルームにアクセスするために必要となるパスワード 設定すると、メッセージの取得・投稿時にパスワードの入力が必要になります。設定したパスワードは二度と参照できません。通信の秘密に該当する可能性があるため、ゲーム管理者でもパスワードを知らなければメッセージにアクセスできなくなります。 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzMessage> | メッセージのリスト |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
|---|---|---|
| NoAccessPrivilegesException | BadRequestException | ルームに設定されたホワイトリストにログイン中のユーザーが含まれていません |
| PasswordRequiredException | BadRequestException | ルームにアクセスするためにはパスワードの設定が必要です |
| PasswordIncorrectException | BadRequestException | ルームに設定されたパスワードと指定されたパスワードが一致しません |
実装例
try {
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
var items = await domain.MessagesAsync(
).ToListAsync();
} catch(Gs2.Gs2Chat.Exception.NoAccessPrivilegesException e) {
// The whitelist configured for the room does not contain any currently logged in user.
} catch(Gs2.Gs2Chat.Exception.PasswordRequiredException e) {
// A password must be set to access the room.
} catch(Gs2.Gs2Chat.Exception.PasswordIncorrectException e) {
// The password set for the room does not match the password specified.
} var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
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->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Room(
"room-0001", // roomName
nullptr // password
);
const auto It = Domain->Messages(
);
TArray<Gs2::UE5::Chat::Model::FEzMessagePtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
try {
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeMessages(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeMessages(callbackId);
} catch(Gs2.Gs2Chat.Exception.NoAccessPrivilegesException e) {
// The whitelist configured for the room does not contain any currently logged in user.
} catch(Gs2.Gs2Chat.Exception.PasswordRequiredException e) {
// A password must be set to access the room.
} catch(Gs2.Gs2Chat.Exception.PasswordIncorrectException e) {
// The password set for the room does not match the password specified.
} var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeMessages(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeMessages(callbackId); const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Room(
"room-0001", // roomName
nullptr // password
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeMessages(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeMessages(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
post
チャットルームにメッセージを投稿する
指定したチャットルームにメッセージを送信します。カテゴリ の数値を付けることで、メッセージの種類を区別できます(例: 0 はテキスト、1 はスタンプ)。
メッセージの内容は metadata に自由な形式の文字列として保存されます。テキスト、JSON など、ゲームに合わせたデータを格納できます。
ルームにパスワードが設定されている場合は、パスワードの入力が必要です。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | ~ 128文字 | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| category | int | 0 | 0 ~ 2147483645 | メッセージの種類を分類したい時の種類番号 メッセージを分類するための数値です。例えば、0 は通常のテキストメッセージ、1 はスタンプ(ステッカー)、その他の値はカスタムメッセージタイプとして使用できます。カテゴリーにより、メッセージに適用される CategoryModel のルールが決まります。 | ||
| metadata | string | ✓ | ~ 1024文字 | メタデータ メタデータには任意の値を設定できます。 これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 | ||
| password | string | ~ 128文字 | パスワード |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzMessage | 投稿したメッセージ |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
|---|---|---|
| NoAccessPrivilegesException | BadRequestException | ルームに設定されたホワイトリストにログイン中のユーザーが含まれていません |
| PasswordRequiredException | BadRequestException | ルームにアクセスするためにはパスワードの設定が必要です |
| PasswordIncorrectException | BadRequestException | ルームに設定されたパスワードと指定されたパスワードが一致しません |
実装例
try {
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
var result = await domain.PostAsync(
metadata: "MESSAGE_0001",
category: null
);
var item = await result.ModelAsync();
} catch(Gs2.Gs2Chat.Exception.NoAccessPrivilegesException e) {
// The whitelist configured for the room does not contain any currently logged in user.
} catch(Gs2.Gs2Chat.Exception.PasswordRequiredException e) {
// A password must be set to access the room.
} catch(Gs2.Gs2Chat.Exception.PasswordIncorrectException e) {
// The password set for the room does not match the password specified.
} var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Room(
roomName: "room-0001",
password: null
);
var future = domain.PostFuture(
metadata: "MESSAGE_0001",
category: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Chat.Exception.NoAccessPrivilegesException)
{
// The whitelist configured for the room does not contain any currently logged in user.
}
if (future.Error is Gs2.Gs2Chat.Exception.PasswordRequiredException)
{
// A password must be set to access the room.
}
if (future.Error is Gs2.Gs2Chat.Exception.PasswordIncorrectException)
{
// The password set for the room does not match the password specified.
}
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->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Room(
"room-0001", // roomName
nullptr // password
);
const auto Future = Domain->Post(
"MESSAGE_0001" // metadata
// category
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Chat::Error::FNoAccessPrivilegesError::Class))
{
// The whitelist configured for the room does not contain any currently logged in user.
}
if (e->IsChildOf(Gs2::Chat::Error::FPasswordRequiredError::Class))
{
// A password must be set to access the room.
}
if (e->IsChildOf(Gs2::Chat::Error::FPasswordIncorrectError::Class))
{
// The password set for the room does not match the password specified.
}
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();listSubscribeRooms
プレイヤーが購読中のルーム一覧を取得する
新着メッセージ通知を受け取るために購読しているチャットルームの一覧を取得します。
チャットUIで「購読中のルーム」リストを表示し、プレイヤーが気になるルームにすぐアクセスできるようにする際に使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | |||
| limit | int | 30 | 1 ~ 1000 | データの取得件数 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzSubscribe> | ルーム購読のリスト |
| nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.SubscribesAsync(
).ToListAsync(); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Subscribes(
);
List<EzSubscribe> items = new List<EzSubscribe>();
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->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Subscribes(
);
TArray<Gs2::UE5::Chat::Model::FEzSubscribePtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSubscribes(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSubscribes(callbackId); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSubscribes(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSubscribes(callbackId); const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeSubscribes(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeSubscribes(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
subscribe
チャットルームを購読する
チャットルームを購読して、新しいメッセージが投稿されたときに通知を受け取れるようにします。
カテゴリの条件を設定することで、どのメッセージで通知を受け取るかをフィルタリングできます。
たとえば「カテゴリ1(スタンプ)のときだけ通知する」「すべてのカテゴリで通知する」といった設定が可能です。
通知を受けたときにプレイヤーがオフラインの場合、モバイルプッシュ通知として転送することもできます(ネームスペースの設定に依存)。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | ~ 128文字 | 購読するルーム名 購読するチャットルームの名前です。購読すると、このルームに新しいメッセージが投稿されるたびに GS2-Gateway 経由でプッシュ通知が送信されます。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| notificationTypes | List<EzNotificationType> | [] | 0 ~ 100 items | 新着メッセージ通知を受け取るカテゴリリスト プッシュ通知をトリガーするメッセージカテゴリーをフィルタリングします。空の場合、すべてのカテゴリーで通知が送信されます。各エントリーはカテゴリー番号とオプションのモバイルプッシュ通知転送を指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzSubscribe | ルーム購読 |
実装例
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
roomName: "room-0001"
);
var result = await domain.SubscribeAsync(
notificationTypes: new List<Gs2.Unity.Gs2Chat.Model.EzNotificationType> {
new Gs2.Unity.Gs2Chat.Model.EzNotificationType {
},
}
);
var item = await result.ModelAsync(); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
roomName: "room-0001"
);
var future = domain.SubscribeFuture(
notificationTypes: new List<Gs2.Unity.Gs2Chat.Model.EzNotificationType> {
new Gs2.Unity.Gs2Chat.Model.EzNotificationType {
},
}
);
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->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Subscribe(
"room-0001" // roomName
);
const auto Future = Domain->Subscribe(
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Chat::Model::FEzNotificationType>>>();
v->Add(
MakeShared<Gs2::UE5::Chat::Model::FEzNotificationType>());
return v;
}() // notificationTypes
);
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();unsubscribe
チャットルームの購読を解除する
指定したチャットルームの新着メッセージ通知の受け取りを停止します。
グループから抜けたときや、設定画面で通知をオフにしたときなど、プレイヤーがルームのフォローをやめる際に使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | ~ 128文字 | 購読するルーム名 購読するチャットルームの名前です。購読すると、このルームに新しいメッセージが投稿されるたびに GS2-Gateway 経由でプッシュ通知が送信されます。 | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzSubscribe | 解除した購読 |
実装例
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
roomName: "room-0001"
);
var result = await domain.UnsubscribeAsync(
); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
roomName: "room-0001"
);
var future = domain.UnsubscribeFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Subscribe(
"room-0001" // roomName
);
const auto Future = Domain->Unsubscribe(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();updateSubscribeSetting
購読中のルームの通知設定を変更する
すでに購読しているルームで、どのカテゴリのメッセージで通知を受け取るかを変更します。
たとえば、最初はすべてのカテゴリで購読していたものを、設定画面から「スタンプのみ」に変更するといった使い方ができます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| roomName | string | ✓ | ~ 128文字 | 購読するルーム名 購読するチャットルームの名前です。購読すると、このルームに新しいメッセージが投稿されるたびに GS2-Gateway 経由でプッシュ通知が送信されます。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| notificationTypes | List<EzNotificationType> | [] | 0 ~ 100 items | 新着メッセージ通知を受け取るカテゴリリスト プッシュ通知をトリガーするメッセージカテゴリーをフィルタリングします。空の場合、すべてのカテゴリーで通知が送信されます。各エントリーはカテゴリー番号とオプションのモバイルプッシュ通知転送を指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzSubscribe | 更新した購読 |
実装例
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
roomName: "room-0001"
);
var result = await domain.UpdateSubscribeSettingAsync(
notificationTypes: new List<Gs2.Unity.Gs2Chat.Model.EzNotificationType> {
new Gs2.Unity.Gs2Chat.Model.EzNotificationType() {},
}
);
var item = await result.ModelAsync(); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
roomName: "room-0001"
);
var future = domain.UpdateSubscribeSettingFuture(
notificationTypes: new List<Gs2.Unity.Gs2Chat.Model.EzNotificationType> {
new Gs2.Unity.Gs2Chat.Model.EzNotificationType() {},
}
);
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->Chat->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Subscribe(
"room-0001" // roomName
);
const auto Future = Domain->UpdateSubscribeSetting(
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Chat::Model::FEzNotificationType>>>();
v->Add(
MakeShared<Gs2::UE5::Chat::Model::FEzNotificationType>() {});
return v;
}() // notificationTypes
);
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();getCategoryModel
カテゴリ番号を指定してメッセージカテゴリ定義を取得する
カテゴリ番号を指定して、メッセージカテゴリ定義を1件取得します。
取得できる情報には、プレイヤーがこのカテゴリへの投稿を制限されているかどうかが含まれます
(サーバー側のシステムメッセージ専用カテゴリなどに利用できます)。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| category | int | ✓ | 0 ~ 2147483645 | カテゴリー メッセージカテゴリーの数値識別子です。このカテゴリー番号で投稿されたメッセージは、プレイヤーの投稿を許可するかなど、このモデルで定義されたルールに従います。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzCategoryModel | カテゴリーモデル |
実装例
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
category: 0
);
var item = await domain.ModelAsync(); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
category: 0
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->CategoryModel(
0 // category
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}値の変更イベントハンドリング
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
category: 0
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
category: 0
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
)->CategoryModel(
0 // category
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Chat::Model::FCategoryModel> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listCategoryModels
メッセージカテゴリ定義の一覧を取得する
このネームスペースに登録されているすべてのメッセージカテゴリ定義を取得します。
カテゴリを使うとメッセージの種類を分類できます。たとえば、カテゴリ0を通常テキスト、カテゴリ1をスタンプに割り当てるといった使い方です。
カテゴリごとに投稿権限を制御することもできます(例: システムアナウンスはサーバーからのみ投稿可能)。
チャットUIでカテゴリ選択を表示したり、利用可能なメッセージタイプを確認する際に使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzCategoryModel> | カテゴリーモデルのリスト |
実装例
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.CategoryModelsAsync(
).ToListAsync(); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.CategoryModels(
);
List<EzCategoryModel> items = new List<EzCategoryModel>();
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->Chat->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->CategoryModels(
);
TArray<Gs2::UE5::Chat::Model::FEzCategoryModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeCategoryModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeCategoryModels(callbackId); var domain = gs2.Chat.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeCategoryModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeCategoryModels(callbackId); const auto Domain = Gs2->Chat->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeCategoryModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeCategoryModels(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
イベントハンドラ
OnPostNotification
購読しているルームに新しい投稿がされたときに使用するプッシュ通知
| 名前 | 型 | 説明 |
|---|---|---|
| namespaceName | string | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| roomName | string | ルーム名 ルーム固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string | ユーザーID |
| category | int | メッセージの種類を分類したい時の種類番号 メッセージを分類するための数値です。例えば、0 は通常のテキストメッセージ、1 はスタンプ(ステッカー)、その他の値はカスタムメッセージタイプとして使用できます。カテゴリーにより、メッセージに適用される CategoryModel のルールが決まります。 |
| createdAt | long | 作成日時 UNIX 時間・ミリ秒 ※ サーバーが自動で設定 |
実装例
gs2.Chat.OnPostNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var roomName = notification.RoomName;
var userId = notification.UserId;
var category = notification.Category;
var createdAt = notification.CreatedAt;
}; gs2.Chat.OnPostNotification += notification =>
{
var namespaceName = notification.NamespaceName;
var roomName = notification.RoomName;
var userId = notification.UserId;
var category = notification.Category;
var createdAt = notification.CreatedAt;
}; Gs2->Chat->OnPostNotification().AddLambda([](const auto Notification)
{
const auto NamespaceName = Notification->NamespaceNameValue;
const auto RoomName = Notification->RoomNameValue;
const auto UserId = Notification->UserIdValue;
const auto Category = Notification->CategoryValue;
const auto CreatedAt = Notification->CreatedAtValue;
});