> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Ranking2 SDK for Game Engine API リファレンス
ゲームエンジン向け GS2-Ranking2 SDK の モデルの仕様 と API のリファレンス
## モデル
### EzGlobalRankingData
グローバルランキング
特定シーズンのグローバルランキングにおけるランキングエントリを表します。ユーザーのスコア、0始まりのインデックス（ソート位置）、1始まりの順位（同点を考慮）を含みます。順位はインデックス + 1 で計算されます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン
GS2-Schedule イベントの繰り返し回数に対応するシーズン番号です。新しいランキング期間ごとに増加します。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| index | int | | | | 0 ~ 2147483646 | インデックス
ランキング内のこのエントリの0始まりの一意のソート位置です。順位とは異なり、スコアが同点でもインデックスは常に一意です。インデックスベースの報酬計算に使用されます。 |
| rank | int | | | | 0 ~ 2147483646 | 順位
1始まりのランキング順位です。同スコアのプレイヤーは同じ順位を共有します。インデックス + 1 で計算されます。順位ベースの報酬計算に使用されます。 |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | スコア |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getGlobalRankingRank - グローバルランキングでのプレイヤー自身の順位を取得する
listGlobalRankings - グローバルランキングのリーダーボードを取得する
---
### EzGlobalRankingReceivedReward
グローバルランキング報酬受け取り履歴
グローバルランキングでの順位に対して報酬を設定できます。
報酬を設定するには 順位閾値 と 報酬の内容 を設定します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン
GS2-Schedule イベントの繰り返し回数に対応するシーズン番号です。新しいランキング期間ごとに増加します。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| receivedAt | long | | ※ | 現在時刻 | | 作成日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getGlobalRankingReceivedReward - 特定のグローバルランキング報酬を受け取り済みか確認する
listGlobalRankingReceivedRewards - プレイヤーのグローバルランキング報酬受け取り履歴の一覧を取得する
---
### EzGlobalRankingScore
グローバルランキングスコア
特定シーズンのグローバルランキングにおけるユーザーの登録スコアを保存します。合算モードが有効な場合、複数の登録スコアが累積されます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン
GS2-Schedule イベントの繰り返し回数に対応するシーズン番号です。新しいランキング期間ごとに増加します。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | スコア
ユーザーが登録したスコア値です。ランキングモデルの minimumValue と maximumValue で定義された範囲内である必要があります。 |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getGlobalRankingScore - 特定のグローバルランキングに登録したプレイヤーのスコアを取得する
listGlobalRankingScores - グローバルランキングに登録したプレイヤーのスコア一覧を取得する
putGlobalRanking - グローバルランキングにスコアを登録する
---
### EzClusterRankingData
クラスターランキング
特定シーズン・クラスターにおけるクラスターランキングのランキングエントリを表します。クラスター内のユーザーのスコア、0始まりのインデックス、1始まりの順位を含みます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓ | | ~ 1024文字 | クラスター名
このシーズンが属するクラスター（ギルド、ギャザリング、またはグループ）の名前です。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン
GS2-Schedule イベントの繰り返し回数に対応するシーズン番号です。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| index | int | | | | 0 ~ 2147483646 | インデックス
クラスターランキング内の0始まりの一意のソート位置です。スコアが同点でも常に一意です。 |
| rank | int | | | | 0 ~ 2147483646 | 順位
クラスター内の1始まりのランキング順位です。同スコアのプレイヤーは同じ順位を共有します。インデックス + 1 で計算されます。 |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | スコア |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getClusterRankingRank - クラスターランキングでのプレイヤー自身の順位を取得する
listClusterRankings - クラスターランキングのリーダーボードを取得する
---
### EzClusterRankingReceivedReward
クラスターランキング報酬受け取り履歴
クラスターランキングの順位に応じた報酬を設定できます。
報酬を設定するには 順位閾値 と 報酬の内容 を設定します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓ | | ~ 1024文字 | クラスター名
ランキング報酬を受け取ったクラスターの名前です。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン
GS2-Schedule イベントの繰り返し回数に対応するシーズン番号です。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| receivedAt | long | | ※ | 現在時刻 | | 作成日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getClusterRankingReceivedReward - 特定のクラスターランキング報酬を受け取り済みか確認する
listClusterRankingReceivedRewards - プレイヤーのクラスターランキング報酬受け取り履歴の一覧を取得する
---
### EzClusterRankingScore
クラスターランキングスコア
特定シーズン・クラスターにおけるユーザーの登録スコアを保存します。スコアの受付前に、クラスタータイプ設定に基づいてユーザーのクラスター所属が検証されます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓ | | ~ 1024文字 | クラスター名
このスコアが属するクラスター（ギルド、ギャザリング、または任意のグループ）の名前です。クラスタータイプ設定に基づいてユーザーの所属が検証されます。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン
GS2-Schedule イベントの繰り返し回数に対応するシーズン番号です。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | スコア
このクラスター内でユーザーが登録したスコア値です。 |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getClusterRankingScore - 特定のクラスターランキングに登録したプレイヤーのスコアを取得する
listClusterRankingScores - クラスターランキングに登録したプレイヤーのスコア一覧を取得する
putClusterRanking - クラスターランキングにスコアを登録する
---
### EzSubscribeRankingData
購読ランキング
特定シーズンのユーザーのパーソナライズされた購読ランキングにおけるランキングエントリを表します。購読ユーザーのスコアを含み、フレンドリスト内でランク付けされます。各エントリにはスコアを達成したユーザーIDが含まれます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン
GS2-Schedule イベントの繰り返し回数に対応するシーズン番号です。 |
| scorerUserId | string | | ✓ | | ~ 128文字 | スコアを獲得したユーザーID
このスコアを達成したプレイヤーのユーザーIDです。購読ランキングでは購読ユーザーのスコアがエントリとなるため、このフィールドはどのフレンドのスコアかを識別します。 |
| index | int | | | | 0 ~ 2147483646 | インデックス
購読ランキング内の0始まりの一意のソート位置です。 |
| rank | int | | | | 0 ~ 2147483646 | 順位
購読ランキング内の1始まりのランキング順位です。インデックス + 1 で計算されます。 |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | スコア |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getSubscribeRankingRank - 購読（フレンド）ランキングでのプレイヤー自身の順位を取得する
listSubscribeRankings - 購読（フレンド）ランキングのリーダーボードを取得する
---
### EzSubscribeRankingScore
購読ランキングスコア
特定シーズンの購読ランキングにおけるユーザーの登録スコアを保存します。このスコアは、このユーザーを購読しているユーザーに表示され、パーソナライズされたフレンドランキングを形成します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | シーズン
GS2-Schedule イベントの繰り返し回数に対応するシーズン番号です。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | スコア |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| updatedAt | long | | ※ | 現在時刻 | | 最終更新日時
UNIX 時間・ミリ秒
※ サーバーが自動で設定 |
**関連するメソッド:**
getSubscribeRankingScore - 特定の購読ランキングに登録したプレイヤーのスコアを取得する
listSubscribeRankingScores - 購読ランキングに登録したプレイヤーのスコア一覧を取得する
putSubscribeRanking - 購読ランキングにスコアを登録する
---
### EzSubscribeUser
購読対象ユーザー情報
購読ランキングにおける2ユーザー間の購読関係を表します。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| userId | string | | ✓ | | ~ 128文字 | ユーザーID |
| targetUserId | string | | ✓ | | ~ 128文字 | 購読対象ユーザーID
購読対象のプレイヤーのユーザーIDです。このプレイヤーのスコアが購読者のパーソナライズされたランキングに含まれます。 |
**関連するメソッド:**
getSubscribe - 特定のユーザーを購読ランキング用にフォローしているか確認する
listSubscribes - 購読ランキング用にフォローしているユーザーの一覧を取得する
---
### EzGlobalRankingModel
グローバルランキングモデル
グローバルランキングは全てのプレイヤーを対象としたランキングを実現するためのモデルです。
上位1000位までのランキングを表示することができます。
GS2-Schedule の繰り返しイベントと関連づけると、繰り返し回数に応じてランキングをリセットすることができます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| globalRankingModelId | string | | ※ | | ~ 1024文字 | グローバルランキングGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 1024文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| rankingRewards | [List<EzRankingReward>](#ezrankingreward) | {entryPeriodEventId} != null | | [] | 0 ~ 100 items | ランキング報酬リスト
各シーズン終了時のランキング順位に基づいて付与される報酬のリストです。スコア登録可能期間イベントが設定されている場合のみ利用可能です。各報酬は順位閾値と実行する入手アクションを定義します。 |
| entryPeriodEventId | string | | | | ~ 1024文字 | スコア登録可能期間イベントGRN
スコアを登録できる期間を定義する GS2-Schedule のイベントGRNです。繰り返しイベントと関連づけると、繰り返しサイクルごとにランキングがリセットされ、シーズン制ランキングを実現できます。 |
| accessPeriodEventId | string | | | | ~ 1024文字 | ランキングデータアクセス可能期間イベントGRN
ランキング結果の閲覧と報酬の受け取りが可能な期間を定義する GS2-Schedule のイベントGRNです。通常、スコア登録期間の間のインターバルに設定します。 |
**関連するメソッド:**
getGlobalRankingModel - 名前を指定してグローバルランキング定義を取得する
listGlobalRankingModels - グローバルランキング定義の一覧を取得する
receiveGlobalRankingReward - グローバルランキング報酬を受け取る
---
### EzClusterRankingModel
クラスターランキングモデル
クラスターランキングはギルドやギャザリング内のプレイヤーを対象としたランキングを実現するためのモデルです。
上位1000位までのランキングを表示することができます。
GS2-Schedule の繰り返しイベントと関連づけると、繰り返し回数に応じてランキングをリセットすることができます。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| clusterRankingModelId | string | | ※ | | ~ 1024文字 | クラスターランキングGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 1024文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| clusterType | 文字列列挙型
enum {
"Raw",
"Gs2Guild::Guild",
"Gs2Matchmaking::SeasonGathering"
}
| | ✓ | | | クラスタータイプ
ランキングのセグメンテーションに使用するグループ（クラスター）の種類を定義します。「Raw」は所属検証なしで任意のクラスター名を指定でき、「Gs2Guild::Guild」はGS2-Guildギルドへの所属を検証し、「Gs2Matchmaking::SeasonGathering」はGS2-Matchmakingシーズンギャザリングへの所属を検証します。"Raw": 検証なし / "Gs2Guild::Guild": GS2-Guild ギルド / "Gs2Matchmaking::SeasonGathering": GS2-Matchmaking シーズンギャザリング / |
| rankingRewards | [List<EzRankingReward>](#ezrankingreward) | {entryPeriodEventId} != null | | [] | 0 ~ 100 items | ランキング報酬リスト
各シーズン終了時のランキング順位に基づいて付与される報酬のリストです。スコア登録可能期間イベントが設定されている場合のみ利用可能です。 |
| entryPeriodEventId | string | | | | ~ 1024文字 | スコア登録可能期間イベントGRN
スコアを登録できる期間を定義する GS2-Schedule のイベントGRNです。繰り返しイベントと関連づけると、シーズン制ランキングを実現できます。 |
| accessPeriodEventId | string | | | | ~ 1024文字 | ランキングデータアクセス可能期間イベントGRN
ランキング結果の閲覧と報酬の受け取りが可能な期間を定義する GS2-Schedule のイベントGRNです。 |
**関連するメソッド:**
getClusterRankingModel - 名前を指定してクラスターランキング定義を取得する
listClusterRankingModels - クラスターランキング定義の一覧を取得する
receiveClusterRankingReward - クラスターランキング報酬を受け取る
---
### EzSubscribeRankingModel
購読ランキングモデル
購読した他プレイヤーのスコアを集計し、ランキングを作成するモデルです。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| subscribeRankingModelId | string | | ※ | | ~ 1024文字 | 購読ランキングGRN
※ サーバーが自動で設定 |
| name | string | | ✓ | | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| metadata | string | | | | ~ 1024文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| entryPeriodEventId | string | | | | ~ 1024文字 | スコア登録可能期間イベントGRN
スコアを登録できる期間を定義する GS2-Schedule のイベントGRNです。繰り返しイベントと関連づけると、シーズン制ランキングを実現できます。 |
| accessPeriodEventId | string | | | | ~ 1024文字 | ランキングデータアクセス可能期間イベントGRN
ランキング結果の閲覧が可能な期間を定義する GS2-Schedule のイベントGRNです。 |
**関連するメソッド:**
getSubscribeRankingModel - 名前を指定して購読ランキング定義を取得する
listSubscribeRankingModels - 購読ランキング定義の一覧を取得する
---
### EzRankingReward
ランキング報酬
スコアの登録期間が設定されたランキングで、登録期間外で参照期間内の時に受け取れる報酬を設定します。
繰り返し設定が有効な場合、直近に期間を終えたランキングが報酬の受け取り対象となります。
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| thresholdRank | int | | ✓ | | 1 ~ 1001 | 順位閾値
この報酬ティアの順位閾値です。順位（またはインデックス、rewardCalculationIndex の設定に依存）がこの閾値以上のプレイヤーがこの報酬を受け取ります。1001に設定すると、ランク外（上位1000位外）のプレイヤー向けの報酬を定義できます。 |
| metadata | string | | | | ~ 1024文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | | | [] | 0 ~ 100 items | 入手アクションリスト
プレイヤーがこのランキング報酬を受け取る際に実行される入手アクションのリストです。この順位閾値を達成した報酬として付与されるアイテム、通貨、その他のリソースを定義します。 |
**関連するモデル:**
EzGlobalRankingModel - グローバルランキングモデル
EzClusterRankingModel - クラスターランキングモデル
---
### EzAcquireAction
入手アクション
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 入手アクションで実行するアクションの種類 |
| request | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
**関連するメソッド:**
receiveGlobalRankingReward - グローバルランキング報酬を受け取る
receiveClusterRankingReward - クラスターランキング報酬を受け取る
**関連するモデル:**
EzRankingReward - ランキング報酬
---
### EzConfig
コンフィグ設定
トランザクションの変数に適用する設定値
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string | | ✓ | | ~ 64文字 | 名前 |
| value | string | | | | ~ 51200文字 | 値 |
**関連するメソッド:**
receiveGlobalRankingReward - グローバルランキング報酬を受け取る
receiveClusterRankingReward - クラスターランキング報酬を受け取る
---
### EzVerifyActionResult
検証アクションの実行結果
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 検証アクションで実行するアクションの種類 |
| verifyRequest | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int | | | | 0 ~ 999 | ステータスコード |
| verifyResult | string | | | | ~ 1048576文字 | 結果内容 |
**関連するモデル:**
EzTransactionResult - トランザクション実行結果
---
### EzConsumeActionResult
消費アクションの実行結果
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 消費アクションで実行するアクションの種類 |
| consumeRequest | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int | | | | 0 ~ 999 | ステータスコード |
| consumeResult | string | | | | ~ 1048576文字 | 結果内容 |
**関連するモデル:**
EzTransactionResult - トランザクション実行結果
---
### EzAcquireActionResult
入手アクションの実行結果
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 文字列列挙型
enum {
}
| | ✓ | | | 入手アクションで実行するアクションの種類 |
| acquireRequest | string | | ✓ | | ~ 524288文字 | アクション実行時に使用されるリクエストのJSON文字列 |
| statusCode | int | | | | 0 ~ 999 | ステータスコード |
| acquireResult | string | | | | ~ 1048576文字 | 結果内容 |
**関連するモデル:**
EzTransactionResult - トランザクション実行結果
---
### EzTransactionResult
トランザクション実行結果
サーバーサイドでのトランザクションの自動実行機能を利用して実行されたトランザクションの実行結果
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string | | ✓ | | 36 ~ 36文字 | トランザクションID |
| verifyResults | [List<EzVerifyActionResult>](#ezverifyactionresult) | | | | 0 ~ 10 items | 検証アクションの実行結果リスト |
| consumeResults | [List<EzConsumeActionResult>](#ezconsumeactionresult) | | | [] | 0 ~ 10 items | 消費アクションの実行結果リスト |
| acquireResults | [List<EzAcquireActionResult>](#ezacquireactionresult) | | | [] | 0 ~ 100 items | 入手アクションの実行結果リスト |
**関連するメソッド:**
receiveGlobalRankingReward - グローバルランキング報酬を受け取る
receiveClusterRankingReward - クラスターランキング報酬を受け取る
---
## メソッド
### getGlobalRankingRank
グローバルランキングでのプレイヤー自身の順位を取得する
プレイヤー自身のランキングエントリを取得します。順位とスコアが含まれます。
リーダーボードでのプレイヤーの位置を表示するのに使います。たとえば、ランキング画面の上部で「あなたの順位: 第42位（15,000点）」と表示したり、「あなたは10,000人中42位です」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGlobalRankingData](#ezglobalrankingdata) | グローバルランキング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
gameSession: GameSession
);
var result = await domain.GetGlobalRankingRankAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var future = domain.GetGlobalRankingRankFuture(
);
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto Future = Domain->GetGlobalRankingRank(
);
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();
```
---
### listGlobalRankings
グローバルランキングのリーダーボードを取得する
グローバルランキングのリーダーボードエントリを取得し、スコア順にランク付けされたプレイヤーを表示します。
各エントリには、プレイヤーのユーザーID、スコア、順位、添付されたメタデータが含まれます。
リーダーボードを表示するのに使います。たとえば、ランキング画面で「1位: Alice（25,000点）、2位: Bob（22,500点）、3位: Charlie（20,000点）」のように表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzGlobalRankingData>](#ezglobalrankingdata) | グローバルランキングのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var items = await domain.GlobalRankingsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var it = domain.GlobalRankings(
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankings(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### getGlobalRankingModel
名前を指定してグローバルランキング定義を取得する
名前を指定して、グローバルランキングモデルを1件取得します。
取得できる情報には、スコア範囲、ソート順、報酬設定、シーズン/エントリー期間の設定が含まれます。
特定のランキングのルールを表示するのに使います。たとえば、ランキング詳細画面で「ハイスコアランキング — 月次リセット、上位100名に報酬、スコアが高いほど上位」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGlobalRankingModel](#ezglobalrankingmodel) | グローバルランキングモデル|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listGlobalRankingModels
グローバルランキング定義の一覧を取得する
このネームスペースに登録されているすべてのグローバルランキングモデルを取得します。
グローバルランキングは、ゲーム内の全プレイヤーが競い合うリーダーボードです。たとえば「世界ハイスコア」「アリーナレーティング」「総ダメージランキング」などです。
各モデルはランキングのルールを定義します: スコア範囲、ソート順（昇順または降順）、シーズンスケジュール、ランキング報酬。
どんなグローバルランキングがあるか確認するのに使います。たとえば「リーダーボード」メニューで「ハイスコアランキング」「スピードクリアランキング」「PvPレーティング」の選択肢を表示する場合に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzGlobalRankingModel>](#ezglobalrankingmodel) | グローバルランキングモデルのリスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.GlobalRankingModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.GlobalRankingModels(
);
List items = new List();
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->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->GlobalRankingModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGlobalRankingModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeGlobalRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGlobalRankingModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeGlobalRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeGlobalRankingModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeGlobalRankingModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### getGlobalRankingReceivedReward
特定のグローバルランキング報酬を受け取り済みか確認する
特定のグローバルランキングとシーズンの報酬受け取り記録を取得します。
プレイヤーが特定のランキングシーズンの報酬をすでに受け取ったか確認するのに使います。たとえば、未受取なら「報酬を受け取る」ボタンを表示し、受取済みなら「受取済み」と表示する場合に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGlobalRankingReceivedReward](#ezglobalrankingreceivedreward) | グローバルランキング報酬受け取り履歴|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listGlobalRankingReceivedRewards
プレイヤーのグローバルランキング報酬受け取り履歴の一覧を取得する
グローバルランキングからプレイヤーが受け取ったランキング報酬の履歴を取得します。
各エントリには、どのランキングとシーズンの報酬を受け取ったかが表示され、どの報酬がすでに回収済みか確認できます。
報酬の受け取り状況を表示するのに使います。たとえば、ランキング報酬画面で「ハイスコアランキング シーズン1: 受取済、シーズン2: 受取済、シーズン3: 未受取」のように表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | | | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzGlobalRankingReceivedReward>](#ezglobalrankingreceivedreward) | グローバルランキング報酬受け取り履歴のリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.GlobalRankingReceivedRewardsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.GlobalRankingReceivedRewards(
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankingReceivedRewards(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGlobalRankingReceivedRewards(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeGlobalRankingReceivedRewards(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGlobalRankingReceivedRewards(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeGlobalRankingReceivedRewards(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeGlobalRankingReceivedRewards(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeGlobalRankingReceivedRewards(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### receiveGlobalRankingReward
グローバルランキング報酬を受け取る
指定したグローバルランキングとシーズンでのプレイヤーの最終順位に基づいてランキング報酬を受け取ります。
報酬はプレイヤーの順位とランキングモデルの報酬設定によって決まります。たとえば、上位10名は特別アイテム、上位100名はジェムを受け取るといった設定が可能です。
報酬アイテムはプレイヤーに自動的に付与されます。
シーズン終了後にランキング結果画面でプレイヤーが「報酬を受け取る」をタップした時に使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
| config | [List<EzConfig>](#ezconfig) | | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGlobalRankingModel](#ezglobalrankingmodel) | グローバルランキングモデル|
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | 報酬受け取り時に実行される入手アクションのリスト|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | 交換処理の実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var result = await domain.ReceiveGlobalRankingRewardAsync(
config: null
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var future = domain.ReceiveGlobalRankingRewardFuture(
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
const auto Future = Domain->ReceiveGlobalRankingReward(
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
---
### getGlobalRankingScore
特定のグローバルランキングに登録したプレイヤーのスコアを取得する
特定のグローバルランキングとシーズンのプレイヤーのスコアを取得します。
特定のリーダーボードでプレイヤーの現在のスコアを表示するのに使います。たとえば、ランキング詳細画面で「あなたのスコア: 15,000点（シーズン3）」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGlobalRankingScore](#ezglobalrankingscore) | グローバルランキングスコア|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingScore(
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listGlobalRankingScores
グローバルランキングに登録したプレイヤーのスコア一覧を取得する
プレイヤーがグローバルランキングに登録したすべてのスコアを取得します。
各スコアエントリには、どのランキングに登録されたか、そのスコア値が表示されます。
プレイヤー自身のスコアを表示するのに使います。たとえば、プロフィール画面やランキング概要画面で「あなたのハイスコア: ステージクリア: 15,000点、アリーナ: 2,400点」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | | | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzGlobalRankingScore>](#ezglobalrankingscore) | グローバルランキングスコアのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.GlobalRankingScoresAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.GlobalRankingScores(
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankingScores(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGlobalRankingScores(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeGlobalRankingScores(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeGlobalRankingScores(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeGlobalRankingScores(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeGlobalRankingScores(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeGlobalRankingScores(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### putGlobalRanking
グローバルランキングにスコアを登録する
指定したグローバルランキングにプレイヤーのスコアを登録します。メタデータ（例: リプレイIDや使用キャラクター名）を添付することもできます。
プレイヤーがすでにスコアを登録している場合、ランキングのルールに基づいて更新されます（例: 最高スコアを保持、または常に最新を使用）。
プレイヤーがスコア対象のアクティビティを完了した後に使います。たとえば、ステージをクリアした後にクリアタイムやスコアを「ハイスコアランキング」に登録する場合です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | グローバルランキングモデル名
グローバルランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | スコア
ユーザーが登録したスコア値です。ランキングモデルの minimumValue と maximumValue で定義された範囲内である必要があります。 |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzGlobalRankingScore](#ezglobalrankingscore) | 登録したグローバルランキングスコア|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var result = await domain.PutGlobalRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var future = domain.PutGlobalRankingFuture(
score: 100L,
metadata: null
);
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutGlobalRanking(
100L // score
// metadata
);
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();
```
---
### getClusterRankingRank
クラスターランキングでのプレイヤー自身の順位を取得する
特定のクラスター（グループ）内でのプレイヤー自身のランキングエントリを取得します。順位とスコアが含まれます。
グループ内でのプレイヤーの位置を表示するのに使います。たとえば、ギルドランキング画面の上部で「あなたのギルド内順位: 第3位（8,500点）」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓| | ~ 1024文字 | クラスター名
このシーズンが属するクラスター（ギルド、ギャザリング、またはグループ）の名前です。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzClusterRankingData](#ezclusterrankingdata) | クラスターランキング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
gameSession: GameSession
);
var result = await domain.GetClusterRankingRankAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var future = domain.GetClusterRankingRankFuture(
);
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
nullptr, // season
"user-0001" // userId
);
const auto Future = Domain->GetClusterRankingRank(
);
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();
```
---
### listClusterRankings
クラスターランキングのリーダーボードを取得する
特定のクラスター（グループ）のリーダーボードエントリを取得し、そのグループ内でスコア順にランク付けされたプレイヤーを表示します。
各エントリには、プレイヤーのユーザーID、スコア、順位、添付されたメタデータが含まれます。
グループのリーダーボードを表示するのに使います。たとえば、ギルドランキング画面で「1位: Alice（8,500点）、2位: Bob（7,200点）、3位: Charlie（6,800点）」のように表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓| | ~ 1024文字 | クラスター名
このシーズンが属するクラスター（ギルド、ギャザリング、またはグループ）の名前です。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzClusterRankingData>](#ezclusterrankingdata) | クラスターランキングのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var items = await domain.ClusterRankingsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var it = domain.ClusterRankings(
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankings(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### getClusterRankingModel
名前を指定してクラスターランキング定義を取得する
名前を指定して、クラスターランキングモデルを1件取得します。
取得できる情報には、スコア範囲、ソート順、クラスタータイプ、報酬設定、シーズン/エントリー期間の設定が含まれます。
特定のクラスターランキングのルールを表示するのに使います。たとえば、ランキング詳細画面で「ギルドDPSランキング — 週次リセット、ギルド内で競争、上位10名に報酬」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzClusterRankingModel](#ezclusterrankingmodel) | クラスターランキングモデル|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listClusterRankingModels
クラスターランキング定義の一覧を取得する
このネームスペースに登録されているすべてのクラスターランキングモデルを取得します。
クラスターランキングは、特定のグループ（クラスター）内のリーダーボードです。たとえば、ギルド内ランキング、地域別ランキング、ゲームサーバー内ランキングなどです。
全プレイヤーが競い合うグローバルランキングと違い、クラスターランキングではグループ内で競い合います。ギルドイベントや地域対抗戦に便利です。
どんなクラスターランキングがあるか確認するのに使います。たとえば、ランキング画面で「ギルドDPSランキング」「地域スコアランキング」の選択肢を表示する場合に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzClusterRankingModel>](#ezclusterrankingmodel) | クラスターランキングモデルのリスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.ClusterRankingModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.ClusterRankingModels(
);
List items = new List();
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->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->ClusterRankingModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeClusterRankingModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeClusterRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeClusterRankingModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeClusterRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeClusterRankingModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeClusterRankingModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### getClusterRankingReceivedReward
特定のクラスターランキング報酬を受け取り済みか確認する
特定のクラスターランキング、クラスター、シーズンの報酬受け取り記録を取得します。
プレイヤーがすでに報酬を受け取ったか確認するのに使います。たとえば、ギルドランキング結果画面で未受取なら「報酬を受け取る」ボタンを表示し、受取済みなら「受取済み」と表示する場合に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓| | ~ 1024文字 | クラスター名
ランキング報酬を受け取ったクラスターの名前です。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzClusterRankingReceivedReward](#ezclusterrankingreceivedreward) | クラスターランキング報酬受け取り履歴|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listClusterRankingReceivedRewards
プレイヤーのクラスターランキング報酬受け取り履歴の一覧を取得する
クラスターランキングからプレイヤーが受け取ったランキング報酬の履歴を取得します。
各エントリには、どのランキング、クラスター、シーズンの報酬を受け取ったかが表示されます。
グループランキングの報酬受け取り状況を表示するのに使います。たとえば、ギルドランキング報酬画面で「ギルドDPSランキング シーズン1: 受取済、シーズン2: 未受取」のように表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | | | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | | | ~ 1024文字 | クラスター名
ランキング報酬を受け取ったクラスターの名前です。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzClusterRankingReceivedReward>](#ezclusterrankingreceivedreward) | クラスターランキング報酬受け取り履歴のリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var items = await domain.ClusterRankingReceivedRewardsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var it = domain.ClusterRankingReceivedRewards(
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankingReceivedRewards(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeClusterRankingReceivedRewards(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeClusterRankingReceivedRewards(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeClusterRankingReceivedRewards(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeClusterRankingReceivedRewards(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeClusterRankingReceivedRewards(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeClusterRankingReceivedRewards(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### receiveClusterRankingReward
クラスターランキング報酬を受け取る
指定したクラスターランキング、クラスター、シーズンでのプレイヤーの最終順位に基づいてランキング報酬を受け取ります。
報酬はグループ内でのプレイヤーの順位とランキングモデルの報酬設定によって決まります。たとえば、各ギルドの1位のプレイヤーが特別なギルドチャンピオンアイテムを受け取るといった設定が可能です。
報酬アイテムはプレイヤーに自動的に付与されます。
シーズン終了後にグループランキング結果画面でプレイヤーが「報酬を受け取る」をタップした時に使います。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓| | ~ 1024文字 | クラスター名
ランキング報酬を受け取ったクラスターの名前です。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
| config | [List<EzConfig>](#ezconfig) | | | [] | 0 ~ 32 items | トランザクションの変数に適用する設定値 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzClusterRankingModel](#ezclusterrankingmodel) | クラスターランキングモデル|
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | 報酬受け取り時に実行される入手アクションのリスト|
| transactionId | string | 発行されたトランザクションID|
| stampSheet | string | 交換処理の実行に使用するスタンプシート|
| stampSheetEncryptionKeyId | string | スタンプシートの署名計算に使用した暗号鍵GRN|
| autoRunStampSheet | bool | トランザクションの自動実行が有効か|
| atomicCommit | bool | トランザクションをアトミックにコミットするか|
| transaction | string | 発行されたトランザクション|
| transactionResult | [EzTransactionResult](#eztransactionresult) | トランザクション実行結果|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var result = await domain.ReceiveClusterRankingRewardAsync(
config: null
);
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var future = domain.ReceiveClusterRankingRewardFuture(
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience ではスタンプシートはSDKレベルで自動的に実行されます。
// エラーが発生すると TransactionException がスローされます。
// TransactionException::Retry() でリトライが可能です。
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
const auto Future = Domain->ReceiveClusterRankingReward(
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
---
### getClusterRankingScore
特定のクラスターランキングに登録したプレイヤーのスコアを取得する
特定のクラスターランキング、クラスター、シーズンのプレイヤーのスコアを取得します。
グループ内でのプレイヤーの現在のスコアを表示するのに使います。たとえば、ギルドランキング詳細画面で「Dragon Slayersギルドでのあなたのスコア: 8,500点（シーズン2）」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓| | ~ 1024文字 | クラスター名
このスコアが属するクラスター（ギルド、ギャザリング、または任意のグループ）の名前です。クラスタータイプ設定に基づいてユーザーの所属が検証されます。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzClusterRankingScore](#ezclusterrankingscore) | クラスターランキングスコア|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingScore(
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listClusterRankingScores
クラスターランキングに登録したプレイヤーのスコア一覧を取得する
特定のクラスター（グループ）内の特定のクラスターランキングに登録したプレイヤーのスコアを取得します。
グループ内でのプレイヤー自身のスコアを表示するのに使います。たとえば、ギルドランキング画面で「あなたのギルドDPSスコア: 8,500点」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | | | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | | | ~ 1024文字 | クラスター名
このスコアが属するクラスター（ギルド、ギャザリング、または任意のグループ）の名前です。クラスタータイプ設定に基づいてユーザーの所属が検証されます。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzClusterRankingScore>](#ezclusterrankingscore) | クラスターランキングスコアのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var items = await domain.ClusterRankingScoresAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var it = domain.ClusterRankingScores(
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankingScores(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeClusterRankingScores(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeClusterRankingScores(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeClusterRankingScores(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeClusterRankingScores(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeClusterRankingScores(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeClusterRankingScores(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### putClusterRanking
クラスターランキングにスコアを登録する
特定のクラスター（グループ）内の指定したクラスターランキングにプレイヤーのスコアを登録します。メタデータを添付することもできます。
クラスター名はスコアがどのグループに属するかを識別します。たとえば、ギルドランキングの場合はギルド名です。
プレイヤーがグループ内のスコア対象アクティビティを完了した後に使います。たとえば、ギルドレイドボスをクリアした後にDPSスコアをプレイヤーのギルドの「ギルドDPSランキング」に登録する場合です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | クラスターランキングモデル名
クラスターランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| clusterName | string | | ✓| | ~ 1024文字 | クラスター名
このスコアが属するクラスター（ギルド、ギャザリング、または任意のグループ）の名前です。クラスタータイプ設定に基づいてユーザーの所属が検証されます。 |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | スコア
このクラスター内でユーザーが登録したスコア値です。 |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzClusterRankingScore](#ezclusterrankingscore) | 登録したクラスターランキングスコア|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var result = await domain.PutClusterRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var future = domain.PutClusterRankingFuture(
score: 100L,
metadata: null
);
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutClusterRanking(
100L // score
// metadata
);
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();
```
---
### getSubscribe
特定のユーザーを購読ランキング用にフォローしているか確認する
特定の対象ユーザーの購読情報を取得します。
プレイヤーが特定のユーザーをすでにフォローしているか確認するのに使います。たとえば、他のプレイヤーのプロフィールで「フォロー中」「フォロー」ボタンを表示したり、フレンドリーダーボードにスコアを表示する前に購読を確認する場合に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| targetUserId | string | | ✓| | ~ 128文字 | 購読対象のユーザーID |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSubscribeUser](#ezsubscribeuser) | 購読対象ユーザー情報|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
rankingName: "ranking-0001"
).SubscribeUser(
targetUserId: "user-0002"
);
var result = await domain.GetSubscribeAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
rankingName: "ranking-0001"
).SubscribeUser(
targetUserId: "user-0002"
);
var future = domain.GetSubscribeFuture(
);
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Subscribe(
"ranking-0001" // rankingName
)->SubscribeUser(
"user-0002" // targetUserId
);
const auto Future = Domain->GetSubscribe(
);
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();
```
---
### listSubscribes
購読ランキング用にフォローしているユーザーの一覧を取得する
購読ランキングのためにプレイヤーが購読（フォロー）しているすべてのユーザーを取得します。
購読ランキングはフォローしたユーザーのスコアのみ表示されるため、この一覧がプレイヤーのフレンドリーダーボードに誰が表示されるかを決定します。
ランキング用の「フォロー中」リストを表示するのに使います。たとえば、フレンドランキング管理画面で「フォロー中: Alice、Bob、Charlie」と表示したり、プレイヤーが何人のフレンドを追跡しているか確認する場合に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzSubscribeUser>](#ezsubscribeuser) | 購読対象ユーザー情報のリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.SubscribesAsync(
rankingName: "ranking-0001"
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Subscribes(
rankingName: "ranking-0001"
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Subscribes(
"ranking-0001" // rankingName
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSubscribes(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSubscribes(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSubscribes(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSubscribes(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeSubscribes(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeSubscribes(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### getSubscribeRankingRank
購読（フレンド）ランキングでのプレイヤー自身の順位を取得する
フレンド間でのプレイヤー自身のランキングエントリを取得します。順位とスコアが含まれます。
フレンドリーダーボードでのプレイヤーの位置を表示するのに使います。たとえば、フレンドランキング画面の上部で「フレンド内順位: 第2位（10,500点）」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSubscribeRankingData](#ezsubscriberankingdata) | 購読ランキング|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
).SubscribeRankingData(
scorerUserId: null
);
var result = await domain.GetSubscribeRankingRankAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
).SubscribeRankingData(
scorerUserId: null
);
var future = domain.GetSubscribeRankingRankFuture(
);
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
nullptr, // season
"user-0001" // userId
)->SubscribeRankingData(
nullptr // scorerUserId
);
const auto Future = Domain->GetSubscribeRankingRank(
);
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();
```
---
### listSubscribeRankings
購読（フレンド）ランキングのリーダーボードを取得する
フレンドリーダーボードを取得します。プレイヤーが購読（フォロー）しているユーザーのスコアのみが表示されます。
各エントリには、ユーザーID、スコア、順位、添付されたメタデータが含まれます。
フレンドリーダーボードを表示するのに使います。たとえば、フレンドランキング画面で「1位: Alice（12,000点）、2位: あなた（10,500点）、3位: Bob（9,800点）」のように表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzSubscribeRankingData>](#ezsubscriberankingdata) | 購読ランキングのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
);
var items = await domain.SubscribeRankingsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
);
var it = domain.SubscribeRankings(
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->SubscribeRankings(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### getSubscribeRankingModel
名前を指定して購読ランキング定義を取得する
名前を指定して、購読ランキングモデルを1件取得します。
取得できる情報には、スコア範囲、ソート順、シーズン/エントリー期間の設定が含まれます。
特定の購読ランキングのルールを表示するのに使います。たとえば、ランキング詳細画面で「フレンドハイスコア — 週次リセット、スコアが高いほど上位」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSubscribeRankingModel](#ezsubscriberankingmodel) | 購読ランキングモデル|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listSubscribeRankingModels
購読ランキング定義の一覧を取得する
このネームスペースに登録されているすべての購読ランキングモデルを取得します。
購読ランキングは、フレンド限定のリーダーボードです。プレイヤーは自分が購読（フォロー）したユーザーのスコアのみ表示されます。
フレンド同士の競争に最適です。たとえば「フレンドハイスコア」「フレンドウィークリーチャレンジ」のように、ゲーム全体ではなくフレンド間でのみ競い合うランキングです。
どんな購読ランキングがあるか確認するのに使います。たとえば、フレンドランキング画面で「フレンドハイスコア」「フレンドスピードクリア」の選択肢を表示する場合に便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzSubscribeRankingModel>](#ezsubscriberankingmodel) | 購読ランキングモデルのリスト|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.SubscribeRankingModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.SubscribeRankingModels(
);
List items = new List();
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->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->SubscribeRankingModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSubscribeRankingModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSubscribeRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSubscribeRankingModels(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSubscribeRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeSubscribeRankingModels(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeSubscribeRankingModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### getSubscribeRankingScore
特定の購読ランキングに登録したプレイヤーのスコアを取得する
特定の購読（フレンド）ランキングとシーズンのプレイヤーのスコアを取得します。
特定のフレンドランキングでのプレイヤーの現在のスコアを表示するのに使います。たとえば、フレンドランキング詳細画面で「あなたのスコア: 12,000点（今週）」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| season | long | | | | 0 ~ 9223372036854775805 | シーズン |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSubscribeRankingScore](#ezsubscriberankingscore) | 購読ランキングスコア|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
)->SubscribeRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
// イベントハンドリングを開始
var callbackId = domain.Subscribe(
value => {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
)->SubscribeRankingScore(
);
// イベントハンドリングを開始
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 値が変化した時に呼び出される
// value には変更後の値が渡ってくる
}
);
// イベントハンドリングを停止
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### listSubscribeRankingScores
購読ランキングに登録したプレイヤーのスコア一覧を取得する
プレイヤーが購読（フレンド）ランキングに登録したすべてのスコアを取得します。
フレンドランキングでのプレイヤー自身のスコアを表示するのに使います。たとえば、フレンドランキング概要画面で「あなたのフレンドハイスコア: 12,000点」と表示するのに便利です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | | | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024文字 | データの取得を開始する位置を指定するトークン |
| limit | int | | | 30 | 1 ~ 1000 | データの取得件数 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| items | [List<EzSubscribeRankingScore>](#ezsubscriberankingscore) | 購読ランキングスコアのリスト|
| nextPageToken | string | リストの続きを取得するためのページトークン|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.SubscribeRankingScoresAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.SubscribeRankingScores(
);
List items = new List();
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->SubscribeRankingScores(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 値の変更イベントハンドリング
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSubscribeRankingScores(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSubscribeRankingScores(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
// イベントハンドリングを開始
var callbackId = domain.SubscribeSubscribeRankingScores(
() => {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
domain.UnsubscribeSubscribeRankingScores(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
// イベントハンドリングを開始
const auto CallbackId = Domain->SubscribeSubscribeRankingScores(
[]() {
// リストの要素が変化した時に呼び出される
}
);
// イベントハンドリングを停止
Domain->UnsubscribeSubscribeRankingScores(CallbackId);
```
{{% alert title="Warning" color="warning" %}}このイベントはSDKがもつローカルキャッシュの値が変更された時に呼び出されます。
ローカルキャッシュは SDK が持つ API の実行、または GS2-Gateway の通知を有効にした GS2-Distributor 経由でのスタンプシートの実行、または GS2-Gateway の通知を有効にした GS2-JobQueue の実行によって変化したもののみが対象となります。
そのため、これらの方法以外で値が変更されてもコールバックは呼び出されません。
{{% /alert %}}
---
### putSubscribeRanking
購読ランキングにスコアを登録する
指定した購読（フレンド）ランキングにプレイヤーのスコアを登録します。メタデータを添付することもできます。
このスコアは、このプレイヤーを購読（フォロー）しているすべてのユーザーのフレンドリーダーボードに表示されます。
プレイヤーがスコア対象のアクティビティを完了した後に使います。たとえば、ステージをクリアした後にスコアを「フレンドハイスコア」ランキングに登録し、プレイヤーのフレンドが確認できるようにする場合です。
#### Request
| | 型 | 有効化条件 | 必須 | デフォルト | 値の制限 | 説明 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128文字 | ネームスペース名
ネームスペース固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| rankingName | string | | ✓| | ~ 128文字 | 購読ランキングモデル名
購読ランキングモデル固有の名前。英数字および -(ハイフン) _(アンダースコア) .(ピリオド)で指定します。 |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | スコア |
| metadata | string | | | | ~ 512文字 | メタデータ
メタデータには任意の値を設定できます。
これらの値は GS2 の動作には影響しないため、ゲーム内で利用する情報の保存先として使用できます。 |
#### Result
| | 型 | 説明 |
| --- | --- | --- |
| item | [EzSubscribeRankingScore](#ezsubscriberankingscore) | 登録した購読ランキングスコア|
#### 実装例
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var result = await domain.PutSubscribeRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var future = domain.PutSubscribeRankingFuture(
score: 100L,
metadata: null
);
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->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutSubscribeRanking(
100L // score
// metadata
);
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();
```
---