GS2-Version SDK for Game Engine API リファレンス
モデル
EzAcceptVersion
承認したバージョン
アプリバージョンや、アセットバージョンのようなデータに紐づいたバージョンではなく
同意した利用規約のバージョンのようなユーザ毎にバージョン管理が必要なエンティティで使用します。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| versionName | string | ✓ | ~ 128文字 | バージョン名 この承認レコードが関連付けられているバージョンモデルの名前です。ユーザーの承認を特定のバージョンモデル定義に紐付けます。 | ||
| userId | string | ✓ | ~ 128文字 | ユーザーID | ||
| version | EzVersion | ✓ | バージョン ユーザーが承認または拒否したバージョン番号です。「active」スコープのバージョンモデルで使用される場合、バージョンチェック時にモデルの現在のバージョンと比較されます。 |
EzVersionModel
バージョンモデル
バージョンモデルには、ログインを受け入れるが、バージョンアップ出来ることを通知する警告バージョンと、ログインを受け入れないエラーバージョンを設定できます。
現在のバージョンをクライアントに申告させるのに、署名の有無を指定できます。
署名付きを選択した場合、クライアントは嘘のバージョン申告を出来なくなります。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128文字 | バージョンモデル名 バージョンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||||||||
| metadata | string | ~ 2048文字 | メタデータ メタデータには任意の値を設定できます。 これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 | |||||||||
| warningVersion | EzVersion | {type} == “simple” | ✓※ | バージョンアップを促すバージョン アップグレード通知を表示する最低バージョン閾値です。クライアントのバージョンがこの値を下回る場合、ログインは許可されますがユーザーにアップグレードが促されます。比較はメジャー、マイナー、マイクロの順に階層的に行われます。 ※ type が “simple” であれば 必須 | ||||||||
| errorVersion | EzVersion | {type} == “simple” | ✓※ | バージョンチェックでエラーになるバージョン ログインを許可する最低バージョン閾値です。クライアントのバージョンがこの値を下回る場合、バージョンチェックがエラーとなりログインがブロックされます。比較はメジャー、マイナー、マイクロの順に階層的に行われます。 ※ type が “simple” であれば 必須 | ||||||||
| scope | 文字列列挙型 enum { “passive”, “active” } | ✓ | 判定に使用するバージョン値の種類 バージョンチェックに使用するバージョン値の取得方法を決定します。「passive」はチェック時にクライアントが現在のバージョンを申告する方式、「active」はユーザーが過去に明示的に承認したバージョン(利用規約への同意など)を使用する方式です。
| |||||||||
| currentVersion | EzVersion | {type} == “simple” and {scope} == “active” | ✓※ | 現在のバージョン このバージョンモデルの最新バージョンです。「simple」モードの「active」スコープでのみ使用され、ユーザーがバージョン更新を承認・確認する際に現在のバージョンを通知します。 ※ type が “simple” で かつ scope が “active” であれば 必須 | ||||||||
| needSignature | bool | {scope} == “passive” | ✓※ | 判定するバージョン値に署名検証を必要とするか 有効にすると、クライアントはバージョン申告と共に暗号署名を提供する必要があります。これにより、クライアントがバージョンチェックを回避するために偽のバージョンを申告することを防止します。スコープが「passive」の場合にのみ適用されます。 ※ scope が “passive” であれば 必須 |
EzVersion
バージョン
3階層(メジャー、マイナー、マイクロ)のバージョン番号を表します。バージョンの比較はメジャー、マイナー、マイクロの順に階層的に行われます。バージョンチェックの警告・エラー閾値の定義に使用されます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| major | int | ✓ | 0 ~ 2147483646 | メジャーバージョン バージョン比較で最も優先度の高いコンポーネントです。メジャーバージョンの差異はマイナーバージョンやマイクロバージョンより優先されます。 | ||
| minor | int | ✓ | 0 ~ 2147483646 | マイナーバージョン バージョン比較で2番目に優先されるコンポーネントです。メジャーバージョンが同一の場合にのみ比較されます。 | ||
| micro | int | ✓ | 0 ~ 2147483646 | マイクロバージョン バージョン比較で最も優先度の低いコンポーネントです。メジャーバージョンとマイナーバージョンがともに同一の場合にのみ比較されます。 |
EzStatus
バージョンの状態
バージョンの検証結果を表します。チェックに使用されたバージョンモデルと、クライアントから申告された、またはユーザー承認から記録された現在のバージョンを含みます。バージョンチェック結果の一部として返され、バージョンが最新か、アップグレード警告が必要か、ブロックされるかをクライアントに通知します。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| versionModel | EzVersionModel | ✓ | バージョンモデル このバージョンチェックに使用されたバージョンモデル定義です。チェック結果を決定した警告・エラーバージョン閾値、スコープ、その他の設定を含みます。 | |||
| currentVersion | EzVersion | 現在のバージョン バージョンチェック時に評価されたバージョンです。「passive」スコープの場合はクライアントが申告したバージョン、「active」スコープの場合はユーザーが過去に承認したバージョンです。バージョン情報が利用できない場合は存在しないことがあります。 |
EzTargetVersion
検証するバージョン
バージョンチェックのためにクライアントが送信するバージョン申告を表します。署名なしモードではバージョンを直接指定します。署名ありモードでは、改ざん防止のために暗号署名と共にバージョンがボディに埋め込まれます。
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| versionName | string | ✓ | ~ 128文字 | バージョンモデル名 バージョンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| version | EzVersion | {signature} == "" | ✓※ | バージョン 検証対象のバージョン番号です。署名検証が不要な場合(署名が未提供)に使用されます。署名が提供されている場合、バージョンは署名済みボディから抽出されます。 ※ signature が "" であれば 必須 | ||
| body | string | ~ 1048576文字 | ボディ バージョン情報を含む署名済みペイロードです。署名検証が有効な場合(needSignature が true)に使用されます。ボディには署名と照合可能な形式でバージョンデータが含まれます。 | |||
| signature | string | ~ 256文字 | 署名 ボディの内容を検証するための暗号署名です。提供された場合、サーバーはバージョンモデルで設定された GS2-Key の暗号鍵を使用して署名を検証し、申告されたバージョンを受け入れます。 |
メソッド
getVersionModel
特定のバージョンチェック定義の詳細を取得する
バージョン名を指定して、チェックルールと閾値を含む詳細を取得します。
レスポンスには以下が含まれます:
- スコープ: 「passive」チェック(アプリバージョン — クライアントがバージョンを報告)か「active」チェック(利用規約 — プレイヤーが明示的に同意する必要がある)か
- 警告バージョン: この閾値を下回るとソフトな警告が表示される(例: 「新しいバージョンが利用可能です。アップデートしてください。」)
- エラーバージョン: この閾値を下回るとハードなブロックが適用される(例: 「プレイを続けるにはアップデートが必要です。」)
- 現在のバージョン: 最新バージョン(activeスコープの場合、プレイヤーが同意する必要があるバージョン)
- スケジュール設定: GS2-Schedule と連携している場合、時間経過で変わるバージョン閾値(例: 大型アップデート後に最低バージョンを段階的に引き上げる)
バージョンチェックの詳細を表示したり、カスタムのバージョンチェックUIロジックを構築する際に使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| versionName | string | ✓ | ~ 128文字 | バージョンモデル名 バージョンモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzVersionModel | バージョンモデル |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).VersionModel(
versionName: "version-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).VersionModel(
versionName: "version-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->VersionModel(
"version-0001" // versionName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}値の変更イベントハンドリング
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).VersionModel(
versionName: "version-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).VersionModel(
versionName: "version-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->VersionModel(
"version-0001" // versionName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Version::Model::FVersionModel> value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
listVersionModels
バージョンチェック定義の一覧を取得する
ネームスペースに定義されているすべてのバージョンモデルを取得します。
各バージョンモデルはバージョンチェックルールを表します。たとえば「アプリバージョン」「利用規約」「アセットバージョン」などです。
GS2-Version は2種類のバージョンチェックに対応しています:
- アプリバージョンチェック(passiveスコープ): ゲームクライアントが自身のバージョン(例: “1.2.3”)を報告し、サーバーが最低要求バージョンを満たしているかチェックします。
- クライアントバージョンが「警告」閾値を下回る → アップデートを推奨(プレイは許可)
- クライアントバージョンが「エラー」閾値を下回る → アップデートを強制(プレイをブロック)
- 利用規約チェック(activeスコープ): プレイヤーが現在のバージョンの規約に明示的に同意する必要があります。
- プレイヤーが最新バージョンに同意していない → 利用規約ダイアログを表示
- プレイヤーが既に同意済み → チェック通過
どのバージョンチェックが設定されているかを確認し、適切な起動フロー(バージョンチェック画面、アップデート案内、規約ダイアログなど)を構築する際に使います。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzVersionModel> | バージョンモデルのリスト |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.VersionModelsAsync(
).ToListAsync(); var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.VersionModels(
);
List<EzVersionModel> items = new List<EzVersionModel>();
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->Version->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->VersionModels(
);
TArray<Gs2::UE5::Version::Model::FEzVersionModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeVersionModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeVersionModels(callbackId); var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeVersionModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeVersionModels(callbackId); const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeVersionModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeVersionModels(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
accept
バージョンを承認する(利用規約に同意する)
プレイヤーが指定されたバージョンを承認(同意)したことを記録します。
利用規約、プライバシーポリシー、その他の法的な同意事項の「同意する」ボタンに対応します。
一般的な流れ:
- CheckVersion が「terms_of_service」についてエラーを返す(プレイヤーが最新バージョンに同意していないため)
- ゲームが利用規約の全文を表示するダイアログを表示する
- プレイヤーが内容を読んで「同意する」をタップする
- ゲームが表示されたバージョン番号で Accept を呼び出す
- 次回の CheckVersion 呼び出しで規約チェックが通過する
重要: 必ずプレイヤーに実際に表示されたバージョン番号を渡してください。プレイヤーが規約を読んでいる間にサーバー上で規約が更新された場合、古いバージョンを渡すとエラーになります。これにより、プレイヤーが常に最新の規約に同意することが保証されます。
バージョンを指定しない場合は最新バージョンが使用されます。ただし、競合状態を防ぐためにバージョンを明示的に指定することを推奨します。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| versionName | string | ✓ | ~ 128文字 | バージョン名 この承認レコードが関連付けられているバージョンモデルの名前です。ユーザーの承認を特定のバージョンモデル定義に紐付けます。 | ||
| version | EzVersion | 承認したバージョン |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzAcceptVersion | 承認したバージョン |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
|---|---|---|
| AcceptVersionInvalidException | BadRequestException | 承認プロセスの途中でサーバーバージョンが更新された結果、エラーとなりました |
実装例
try {
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "eula"
);
var result = await domain.AcceptAsync(
version: new Gs2.Unity.Gs2Version.Model.EzVersion {
Major = 2,
Minor = 2,
Micro = 2,
}
);
var item = await result.ModelAsync();
} catch(Gs2.Gs2Version.Exception.AcceptVersionInvalidException e) {
// Error as a result of an updated server version during the approval process
} var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "eula"
);
var future = domain.AcceptFuture(
version: new Gs2.Unity.Gs2Version.Model.EzVersion {
Major = 2,
Minor = 2,
Micro = 2,
}
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Version.Exception.AcceptVersionInvalidException)
{
// Error as a result of an updated server version during the approval process
}
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->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->AcceptVersion(
"eula" // versionName
);
const auto Future = Domain->Accept(
MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
->WithMajor(2)
->WithMinor(2)
->WithMicro(2)
) // version
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Version::Error::FAcceptVersionInvalidError::Class))
{
// Error as a result of an updated server version during the approval process
}
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();delete
バージョン承認レコードを削除する
指定されたバージョンモデルに対するプレイヤーの承認または拒否レコードを削除します。
削除後、次回の CheckVersion 呼び出しでは、プレイヤーがこのバージョンチェックに一度も応答していないものとして扱われます。
ユースケース:
- プレイヤーがオプションの同意を取り消せるようにする(例: データ収集同意の撤回)
- テストやデバッグ目的で承認状態をリセットする
- バージョン番号を変更せずにプレイヤーに更新された規約を再読させたい場合に再承認を強制する
activeスコープのチェック(利用規約)の場合、承認レコードを削除すると、プレイヤーは次回ログイン時またはバージョンチェック時に再度同意を求められます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| versionName | string | ✓ | ~ 128文字 | バージョン名 この承認レコードが関連付けられているバージョンモデルの名前です。ユーザーの承認を特定のバージョンモデル定義に紐付けます。 |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzAcceptVersion | 削除した承認バージョン |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "eula"
);
var result = await domain.DeleteAsync(
); var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "eula"
);
var future = domain.DeleteFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->AcceptVersion(
"eula" // versionName
);
const auto Future = Domain->Delete(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();list
プレイヤーが承認または拒否したバージョンの一覧を取得する
現在のプレイヤーのすべてのバージョン承認/拒否レコードを取得します。
各レコードには、プレイヤーがどのバージョンモデルに対して応答したか、どのバージョンを承認または拒否したかが含まれます。
主に利用規約やプライバシーポリシーの管理に使います。たとえば:
- プレイヤーが既に同意した規約とそのバージョンを表示する
- プレイヤーが更新された規約に再同意する必要があるかチェックする
- プレイヤーが同意した内容を確認できる「規約・ポリシー」設定画面を表示する
アプリバージョンチェック(passiveスコープ)では承認レコードは使われません。クライアントが報告したバージョンを直接比較してチェックされます。このリストにはactiveスコープのチェック(プレイヤーが明示的に承認/拒否した)のレコードのみが含まれます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024文字 | データの取得を開始する位置を指定するトークン | |||
| limit | int | 30 | 1 ~ 1000 | データの取得件数 |
Result
| 型 | 説明 | |
|---|---|---|
| items | List<EzAcceptVersion> | 承認したバージョンのリスト |
| nextPageToken | string | リストの続きを取得するためのページトークン |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.AcceptVersionsAsync(
).ToListAsync(); var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.AcceptVersions(
);
List<EzAcceptVersion> items = new List<EzAcceptVersion>();
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->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->AcceptVersions(
);
TArray<Gs2::UE5::Version::Model::FEzAcceptVersionPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}値の変更イベントハンドリング
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeAcceptVersions(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeAcceptVersions(callbackId); var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeAcceptVersions(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeAcceptVersions(callbackId); const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeAcceptVersions(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeAcceptVersions(CallbackId);Warning
このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
reject
バージョンを拒否する(任意の規約を辞退する)
プレイヤーが指定されたバージョンを拒否(辞退)したことを記録します。
「辞退する」「結構です」ボタンに対応しますが、同意が必須でないオプションの規約にのみ使用できます。
バージョンモデルの承認要件が「optional」に設定されている場合にのみ使用可能です。承認が必須(mandatory)の場合、プレイヤーは同意する必要があり、拒否オプションはありません。
オプション規約のユースケース:
- 任意のデータ収集同意: 「ゲーム改善のために利用データを収集してもよろしいですか?」→ 同意する / 辞退する
- 任意のマーケティング通知: 「プロモーションメールの受信を希望しますか?」→ 同意する / 辞退する
- 任意のベータ機能: 「実験的な機能を試してみますか?」→ 同意する / 辞退する
プレイヤーが拒否しても、拒否したことが記録されるため、プロンプトを見て応答したことがわかります。次回の CheckVersion ではバージョンチェックが通過し(オプションのため)、ゲームは拒否レコードを確認して動作を調整できます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| versionName | string | ✓ | ~ 128文字 | バージョン名 この承認レコードが関連付けられているバージョンモデルの名前です。ユーザーの承認を特定のバージョンモデル定義に紐付けます。 | ||
| version | EzVersion | 否認したバージョン |
Result
| 型 | 説明 | |
|---|---|---|
| item | EzAcceptVersion | 否認したバージョン |
Error
このAPIには特別な例外が定義されています。
GS2-SDK for GameEngine ではゲーム内でハンドリングが必要そうなエラーは一般的な例外から派生した特殊化した例外を用意することでハンドリングしやすくしています。
一般的なエラーの種類や、ハンドリング方法は こちら のドキュメントを参考にしてください。
| 型 | 基底クラス | 説明 |
|---|---|---|
| AcceptVersionInvalidException | BadRequestException | 承認プロセスの途中でサーバーバージョンが更新された結果、エラーとなりました |
実装例
try {
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "version-0001"
);
var result = await domain.RejectAsync(
version: null
);
var item = await result.ModelAsync();
} catch(Gs2.Gs2Version.Exception.AcceptVersionInvalidException e) {
// Error as a result of an updated server version during the approval process
} var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).AcceptVersion(
versionName: "version-0001"
);
var future = domain.RejectFuture(
version: null
);
yield return future;
if (future.Error != null)
{
if (future.Error is Gs2.Gs2Version.Exception.AcceptVersionInvalidException)
{
// Error as a result of an updated server version during the approval process
}
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->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->AcceptVersion(
"version-0001" // versionName
);
const auto Future = Domain->Reject(
// version
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
auto e = Future->GetTask().Error();
if (e->IsChildOf(Gs2::Version::Error::FAcceptVersionInvalidError::Class))
{
// Error as a result of an updated server version during the approval process
}
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();checkVersion
すべてのバージョンチェックを一括実行する
ゲームクライアントのバージョンとプレイヤーの規約同意状況を、ネームスペース内のすべてのバージョンモデルに対してチェックします。
ゲーム起動時に呼び出して、プレイヤーが先に進めるか、アップデートや規約同意が必要かを判定するメインAPIです。
一般的な起動フロー:
- ゲームが起動し、クライアントの現在のバージョン(アプリバージョン、アセットバージョンなど)を渡して CheckVersion を呼び出す
- サーバーが各バージョンモデルをチェックし、2つのリストを返す:
- warnings: チェックは通過したがクライアントが推奨バージョンを下回っている(「アップデートがあります」ダイアログを表示)
- errors: チェックに失敗 — クライアントが古すぎる、または規約に未同意(プレイヤーをブロック)
- エラーがある場合、適切な画面を表示:
- アプリバージョンのエラー → 「App Store / Google Play からアップデートしてください」と表示しリダイレクト
- 利用規約のエラー → 規約ダイアログを表示し、プレイヤーが同意したら Accept を呼び出す
- 警告のみ(エラーなし)の場合、プレイヤーを先に進めつつ、任意でアップデート推奨を表示
- 警告もエラーもなければ、プレイヤーは通常通りゲームに入る
targetVersions パラメータには、passiveスコープのチェック(アプリバージョンなど)用にクライアントの現在のバージョン番号を渡します。activeスコープのチェック(利用規約など)はプレイヤーの同意履歴に基づいて自動的に評価されます。
Request
| 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128文字 | ネームスペース名 ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 | ||
| gameSession | GameSession | ✓ | GameSession | |||
| targetVersions | List<EzTargetVersion> | [] | 0 ~ 1000 items | 検証するバージョンリスト |
Result
| 型 | 説明 | |
|---|---|---|
| projectToken | string | サインインしたプロジェクトトークン |
| warnings | List<EzStatus> | バージョンの検証結果 警告のリスト |
| errors | List<EzStatus> | バージョンの検証結果 エラーのリスト |
実装例
var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Checker(
);
var result = await domain.CheckVersionAsync(
targetVersions: new List<Gs2.Unity.Gs2Version.Model.EzTargetVersion> {
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
VersionName = "app",
Version =
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
Major = 1,
Minor = 2,
Micro = 3,
},
},
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
VersionName = "asset",
Version =
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
Major = 1,
Minor = 2,
Micro = 3,
},
},
}
);
var projectToken = result.ProjectToken;
var warnings = result.Warnings;
var errors = result.Errors; var domain = gs2.Version.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Checker(
);
var future = domain.CheckVersionFuture(
targetVersions: new List<Gs2.Unity.Gs2Version.Model.EzTargetVersion> {
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
VersionName = "app",
Version =
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
Major = 1,
Minor = 2,
Micro = 3,
},
},
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
VersionName = "asset",
Version =
new Gs2.Unity.Gs2Version.Model.EzTargetVersion() {
Major = 1,
Minor = 2,
Micro = 3,
},
},
}
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var projectToken = future.Result.ProjectToken;
var warnings = future.Result.Warnings;
var errors = future.Result.Errors; const auto Domain = Gs2->Version->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Checker(
);
const auto Future = Domain->CheckVersion(
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Version::Model::FEzTargetVersion>>>();
v->Add(
MakeShared<Gs2::UE5::Version::Model::FEzTargetVersion>()
->WithVersionName(TOptional<FString>("app"))
->WithVersion(MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
->WithMajor(TOptional<int32>(1))
->WithMinor(TOptional<int32>(2))
->WithMicro(TOptional<int32>(3))
);
);
v->Add(
MakeShared<Gs2::UE5::Version::Model::FEzTargetVersion>()
->WithVersionName(TOptional<FString>("asset"))
->WithVersion(MakeShared<Gs2::UE5::Version::Model::FEzVersion>()
->WithMajor(TOptional<int32>(1))
->WithMinor(TOptional<int32>(2))
->WithMicro(TOptional<int32>(3))
);
);
return v;
}() // targetVersions
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();
const auto ProjectToken = Result->ProjectToken;
const auto Warnings = Result->Warnings;
const auto Errors = Result->Errors;