> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Ranking2 SDK for Game Engine API Reference
Specifications of models and API references for GS2-Ranking2 SDK for Game Engine
## Models
### EzGlobalRankingData
Global Ranking
Represents a ranked entry in the global ranking for a specific season. Contains the user's score, 0-based index (sorted position), and 1-based rank (which accounts for ties). The rank is calculated as index + 1.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | Season
The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. |
| userId | string | | ✓ | | ~ 128 chars | User ID |
| index | int | | | | 0 ~ 2147483646 | Index
The 0-based unique sorted position of this entry in the ranking. Unlike rank, index is always unique even when scores are tied. Used for index-based reward calculation. |
| rank | int | | | | 0 ~ 2147483646 | Rank
The 1-based ranking position. Players with the same score share the same rank. Calculated as index + 1. Used for rank-based reward calculation. |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | Score |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| updatedAt | long | | * | Current time | | Last Updated Timestamp
Unix time, milliseconds
* Set automatically by the server |
**Related methods:**
getGlobalRankingRank - Get the player's own rank in a global ranking
listGlobalRankings - Get the global ranking leaderboard
---
### EzGlobalRankingReceivedReward
Global Ranking Reward Received History
It is possible to set rewards for global ranking positions.
To set rewards, set the ranking threshold and reward details.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | Season
The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. |
| userId | string | | ✓ | | ~ 128 chars | User ID |
| receivedAt | long | | * | Current time | | Creation Timestamp
Unix time, milliseconds
* Set automatically by the server |
**Related methods:**
getGlobalRankingReceivedReward - Check if the player has claimed a specific global ranking reward
listGlobalRankingReceivedRewards - List the player's global ranking reward claim history
---
### EzGlobalRankingScore
Global Ranking Score
Stores a user's submitted score for a global ranking in a specific season. When the sum mode is enabled, multiple submitted scores are accumulated.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | Season
The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. |
| userId | string | | ✓ | | ~ 128 chars | User ID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | Score
The score value submitted by the user. Must be within the range defined by the ranking model's minimumValue and maximumValue settings. |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| updatedAt | long | | * | Current time | | Last Updated Timestamp
Unix time, milliseconds
* Set automatically by the server |
**Related methods:**
getGlobalRankingScore - Get the player's submitted score for a specific global ranking
listGlobalRankingScores - List the player's submitted scores for global rankings
putGlobalRanking - Submit a score to a global ranking
---
### EzClusterRankingData
Cluster Ranking
Represents a ranked entry in a cluster ranking for a specific season and cluster. Contains the user's score, 0-based index, and 1-based rank within the cluster.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓ | | ~ 1024 chars | Cluster Name
The name of the cluster (guild, gathering, or group) that this season belongs to. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | Season
The season number corresponding to the GS2-Schedule event repeat count. |
| userId | string | | ✓ | | ~ 128 chars | User ID |
| index | int | | | | 0 ~ 2147483646 | Index
The 0-based unique sorted position within the cluster ranking. Always unique even when scores are tied. |
| rank | int | | | | 0 ~ 2147483646 | Rank
The 1-based ranking position within the cluster. Players with the same score share the same rank. Calculated as index + 1. |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | Score |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| updatedAt | long | | * | Current time | | Last Updated Timestamp
Unix time, milliseconds
* Set automatically by the server |
**Related methods:**
getClusterRankingRank - Get the player's own rank in a cluster ranking
listClusterRankings - Get the cluster ranking leaderboard
---
### EzClusterRankingReceivedReward
Cluster Ranking Reward Received History
You can set rewards according to the cluster ranking.
To set rewards, set the ranking threshold and reward details.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓ | | ~ 1024 chars | Cluster Name
The name of the cluster for which the ranking reward was received. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | Season
The season number corresponding to the GS2-Schedule event repeat count. |
| userId | string | | ✓ | | ~ 128 chars | User ID |
| receivedAt | long | | * | Current time | | Creation Timestamp
Unix time, milliseconds
* Set automatically by the server |
**Related methods:**
getClusterRankingReceivedReward - Check if the player has claimed a specific cluster ranking reward
listClusterRankingReceivedRewards - List the player's cluster ranking reward claim history
---
### EzClusterRankingScore
Cluster Ranking Score
Stores a user's submitted score for a cluster ranking in a specific season and cluster. The user's cluster membership is verified based on the cluster type setting before the score is accepted.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓ | | ~ 1024 chars | Cluster Name
The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | Season
The season number corresponding to the GS2-Schedule event repeat count. |
| userId | string | | ✓ | | ~ 128 chars | User ID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | Score
The score value submitted by the user within this cluster. |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| updatedAt | long | | * | Current time | | Last Updated Timestamp
Unix time, milliseconds
* Set automatically by the server |
**Related methods:**
getClusterRankingScore - Get the player's submitted score for a specific cluster ranking
listClusterRankingScores - List the player's submitted scores for cluster rankings
putClusterRanking - Submit a score to a cluster ranking
---
### EzSubscribeRankingData
Subscribe Ranking
Represents a ranked entry in a user's personalized subscribe ranking for a specific season. Contains scores from subscribed users, ranked among the user's friend list. Each entry includes the scorer's user ID to identify who achieved the score.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | Season
The season number corresponding to the GS2-Schedule event repeat count. |
| scorerUserId | string | | ✓ | | ~ 128 chars | Scorer User ID
The user ID of the player who achieved this score. In a subscribe ranking, entries come from subscribed users, so this field identifies which friend's score this entry represents. |
| index | int | | | | 0 ~ 2147483646 | Index
The 0-based unique sorted position within the subscribe ranking. |
| rank | int | | | | 0 ~ 2147483646 | Rank
The 1-based ranking position within the subscribe ranking. Calculated as index + 1. |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | Score |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| updatedAt | long | | * | Current time | | Last Updated Timestamp
Unix time, milliseconds
* Set automatically by the server |
**Related methods:**
getSubscribeRankingRank - Get the player's own rank in a subscribe (friend) ranking
listSubscribeRankings - Get the subscribe (friend) ranking leaderboard
---
### EzSubscribeRankingScore
Subscribe Ranking Score
Stores a user's submitted score for a subscribe ranking in a specific season. This score is visible to users who have subscribed to this user, forming their personalized friend ranking.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | Season
The season number corresponding to the GS2-Schedule event repeat count. |
| userId | string | | ✓ | | ~ 128 chars | User ID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | Score |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| updatedAt | long | | * | Current time | | Last Updated Timestamp
Unix time, milliseconds
* Set automatically by the server |
**Related methods:**
getSubscribeRankingScore - Get the player's submitted score for a specific subscribe ranking
listSubscribeRankingScores - List the player's submitted scores for subscribe rankings
putSubscribeRanking - Submit a score to a subscribe ranking
---
### EzSubscribeUser
Subscribed User Information
Represents a subscription relationship between two users for the subscribe ranking.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| userId | string | | ✓ | | ~ 128 chars | User ID |
| targetUserId | string | | ✓ | | ~ 128 chars | Subscribe Target User ID
The user ID of the player being subscribed to. This player's scores will be included in the subscriber's personalized ranking. |
**Related methods:**
getSubscribe - Check if the player is following a specific user for subscribe rankings
listSubscribes - List users the player is following for subscribe rankings
---
### EzGlobalRankingModel
Global Ranking Model
The global ranking is a model that allows you to create a ranking that targets all players.
You can display the top 1000 rankings.
By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| globalRankingModelId | string | | * | | ~ 1024 chars | Global Ranking GRN
* Set automatically by the server |
| name | string | | ✓ | | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| metadata | string | | | | ~ 1024 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| rankingRewards | [List<EzRankingReward>](#ezrankingreward) | {entryPeriodEventId} != null | | [] | 0 ~ 100 items | Ranking Rewards
List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. |
| entryPeriodEventId | string | | | | ~ 1024 chars | Entry Period Event GRN
GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. |
| accessPeriodEventId | string | | | | ~ 1024 chars | Access Period Event GRN
GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. Typically set to the interval between score entry periods. |
**Related methods:**
getGlobalRankingModel - Get a specific global ranking definition by name
listGlobalRankingModels - List global ranking definitions
receiveGlobalRankingReward - Claim the global ranking reward
---
### EzClusterRankingModel
Cluster Ranking Model
The cluster ranking model enables rankings for players within guilds or gatherings.
You can display the top 1000 rankings.
By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| clusterRankingModelId | string | | * | | ~ 1024 chars | Cluster Ranking GRN
* Set automatically by the server |
| name | string | | ✓ | | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| metadata | string | | | | ~ 1024 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| clusterType | string (enum)
enum {
"Raw",
"Gs2Guild::Guild",
"Gs2Matchmaking::SeasonGathering"
}
| | ✓ | | | Cluster Type
Defines the type of group (cluster) used for ranking segmentation. "Raw" allows arbitrary cluster names without membership verification, "Gs2Guild::Guild" verifies the user belongs to a GS2-Guild guild, and "Gs2Matchmaking::SeasonGathering" verifies membership in a GS2-Matchmaking season gathering."Raw": No verification / "Gs2Guild::Guild": GS2-Guild Guild / "Gs2Matchmaking::SeasonGathering": GS2-Matchmaking Season Gathering / |
| rankingRewards | [List<EzRankingReward>](#ezrankingreward) | {entryPeriodEventId} != null | | [] | 0 ~ 100 items | Ranking Rewards
List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. |
| entryPeriodEventId | string | | | | ~ 1024 chars | Entry Period Event GRN
GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. |
| accessPeriodEventId | string | | | | ~ 1024 chars | Access Period Event GRN
GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. |
**Related methods:**
getClusterRankingModel - Get a specific cluster ranking definition by name
listClusterRankingModels - List cluster ranking definitions
receiveClusterRankingReward - Claim the cluster ranking reward
---
### EzSubscribeRankingModel
Subscribe Ranking Model
A model that aggregates scores of other players that the user has subscribed to and creates a ranking.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| subscribeRankingModelId | string | | * | | ~ 1024 chars | Subscribe Ranking GRN
* Set automatically by the server |
| name | string | | ✓ | | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| metadata | string | | | | ~ 1024 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| entryPeriodEventId | string | | | | ~ 1024 chars | Entry Period Event GRN
GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. |
| accessPeriodEventId | string | | | | ~ 1024 chars | Access Period Event GRN
GS2-Schedule event GRN that defines the period during which ranking results can be viewed. |
**Related methods:**
getSubscribeRankingModel - Get a specific subscribe ranking definition by name
listSubscribeRankingModels - List subscribe ranking definitions
---
### EzRankingReward
Ranking Reward
Set the rewards that can be received during the reference period when the score registration period is set in the ranking.
If the repeat setting is enabled, the most recently ended period ranking will be the target for receiving rewards.
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| thresholdRank | int | | ✓ | | 1 ~ 1001 | Rank Threshold
The rank threshold for this reward tier. Players whose rank (or index, depending on rewardCalculationIndex setting) is at or above this threshold receive this reward. Set to 1001 to define rewards for unranked players (those outside the top 1000). |
| metadata | string | | | | ~ 1024 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | | | [] | 0 ~ 100 items | List of Acquire Actions
List of acquire actions executed when the player claims this ranking reward. These define the actual items, currency, or other resources granted as the reward for achieving this rank threshold. |
**Related models:**
EzGlobalRankingModel - Global Ranking Model
EzClusterRankingModel - Cluster Ranking Model
---
### EzAcquireAction
Acquire Action
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)
enum {
}
| | ✓ | | | Type of Acquire Action |
| request | string | | ✓ | | ~ 524288 chars | JSON string of the request used when executing the action |
**Related methods:**
receiveGlobalRankingReward - Claim the global ranking reward
receiveClusterRankingReward - Claim the cluster ranking reward
**Related models:**
EzRankingReward - Ranking Reward
---
### EzConfig
Configuration
Configuration values applied to transaction variables
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| key | string | | ✓ | | ~ 64 chars | Name |
| value | string | | | | ~ 51200 chars | Value |
**Related methods:**
receiveGlobalRankingReward - Claim the global ranking reward
receiveClusterRankingReward - Claim the cluster ranking reward
---
### EzVerifyActionResult
Verify Action execution result
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)
enum {
}
| | ✓ | | | Type of Verify Action |
| verifyRequest | string | | ✓ | | ~ 524288 chars | JSON string of the request used when executing the action |
| statusCode | int | | | | 0 ~ 999 | Status code |
| verifyResult | string | | | | ~ 1048576 chars | Result content |
**Related models:**
EzTransactionResult - Transaction Execution Result
---
### EzConsumeActionResult
Consume Action execution result
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)
enum {
}
| | ✓ | | | Type of Consume Action |
| consumeRequest | string | | ✓ | | ~ 524288 chars | JSON string of the request used when executing the action |
| statusCode | int | | | | 0 ~ 999 | Status code |
| consumeResult | string | | | | ~ 1048576 chars | Result content |
**Related models:**
EzTransactionResult - Transaction Execution Result
---
### EzAcquireActionResult
Acquire Action execution result
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| action | string (enum)
enum {
}
| | ✓ | | | Type of Acquire Action |
| acquireRequest | string | | ✓ | | ~ 524288 chars | JSON string of the request used when executing the action |
| statusCode | int | | | | 0 ~ 999 | Status code |
| acquireResult | string | | | | ~ 1048576 chars | Result content |
**Related models:**
EzTransactionResult - Transaction Execution Result
---
### EzTransactionResult
Transaction Execution Result
Result of a transaction executed using the server-side automatic execution feature
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string | | ✓ | | 36 ~ 36 chars | Transaction ID |
| verifyResults | [List<EzVerifyActionResult>](#ezverifyactionresult) | | | | 0 ~ 10 items | List of verify action execution results |
| consumeResults | [List<EzConsumeActionResult>](#ezconsumeactionresult) | | | [] | 0 ~ 10 items | List of Consume Action execution results |
| acquireResults | [List<EzAcquireActionResult>](#ezacquireactionresult) | | | [] | 0 ~ 100 items | List of Acquire Action execution results |
**Related methods:**
receiveGlobalRankingReward - Claim the global ranking reward
receiveClusterRankingReward - Claim the cluster ranking reward
---
## Methods
### getGlobalRankingRank
Get the player's own rank in a global ranking
Retrieves the player's own ranking entry, including their rank position and score.
Use this to display the player's position on the leaderboard — for example, showing "Your rank: #42 (15,000 pts)" at the top of the ranking screen, or "You are ranked #42 out of 10,000 players".
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzGlobalRankingData](#ezglobalrankingdata) | Global Ranking|
#### Implementation Example
**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
Get the global ranking leaderboard
Retrieves the global ranking leaderboard entries, showing players ranked by their scores.
Each entry includes the player's user ID, score, rank position, and any attached metadata.
Use this to display the leaderboard — for example, showing "1st: Alice (25,000 pts), 2nd: Bob (22,500 pts), 3rd: Charlie (20,000 pts)" on a ranking screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzGlobalRankingData>](#ezglobalrankingdata) | List of Global Rankings|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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
Get a specific global ranking definition by name
Retrieves a single global ranking model by specifying its name.
The returned information includes the score range, sort order, reward settings, and season/entry period configurations.
Use this to display the rules of a specific ranking — for example, showing "High Score Ranking — Resets monthly, Top 100 get rewards, Higher score = better rank" on a ranking detail screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzGlobalRankingModel](#ezglobalrankingmodel) | Global Ranking Model|
#### Implementation Example
**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;
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### listGlobalRankingModels
List global ranking definitions
Retrieves all global ranking models registered in this Namespace.
A global ranking is a leaderboard where all players in the game compete against each other — for example, "World High Score", "Arena Rating", or "Total Damage Ranking".
Each model defines the ranking rules: score range, sort order (ascending or descending), season schedule, and ranking rewards.
Use this to see what global rankings exist — for example, to display a "Leaderboards" menu showing "High Score Ranking", "Speed Clear Ranking", "PvP Rating" as options.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzGlobalRankingModel>](#ezglobalrankingmodel) | List of Global Ranking Models|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeGlobalRankingModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeGlobalRankingModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### getGlobalRankingReceivedReward
Check if the player has claimed a specific global ranking reward
Retrieves the reward claim record for a specific global ranking and season.
Use this to check if the player has already claimed the reward for a specific ranking season — for example, showing a "Claim Reward" button if unclaimed, or "Already Claimed" if already received.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzGlobalRankingReceivedReward](#ezglobalrankingreceivedreward) | Global Ranking Reward Received History|
#### Implementation Example
**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;
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### listGlobalRankingReceivedRewards
List the player's global ranking reward claim history
Retrieves the player's history of claimed ranking rewards from global rankings.
Each entry shows which ranking and season the reward was claimed for, allowing you to check which rewards have already been collected.
Use this to display reward claim status — for example, showing "High Score Ranking Season 1: Claimed, Season 2: Claimed, Season 3: Not yet claimed" on a ranking rewards screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | | | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzGlobalRankingReceivedReward>](#ezglobalrankingreceivedreward) | List of Global Ranking Rewards Received|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingReceivedRewards(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingReceivedRewards(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingReceivedRewards(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
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
);
// Start event handling
const auto CallbackId = Domain->SubscribeGlobalRankingReceivedRewards(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeGlobalRankingReceivedRewards(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### receiveGlobalRankingReward
Claim the global ranking reward
Claims the ranking reward based on the player's final rank in the specified global ranking and season.
The reward is determined by the player's rank position and the ranking model's reward settings — for example, top 10 players might receive a special item, while top 100 receive gems.
The reward items are automatically granted to the player.
Use this when the player taps "Claim Reward" on the ranking results screen after a season ends.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
| config | [List<EzConfig>](#ezconfig) | | | [] | 0 ~ 32 items | Configuration values applied to transaction variables |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzGlobalRankingModel](#ezglobalrankingmodel) | Global Ranking Model|
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | List of Acquire Actions to be performed when rewards are received|
| transactionId | string | Issued transaction ID|
| stampSheet | string | Stamp sheet used to execute the exchange process|
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations|
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled|
| atomicCommit | bool | Whether to commit the transaction atomically|
| transaction | string | Issued transaction|
| transactionResult | [EzTransactionResult](#eztransactionresult) | Transaction Execution Result|
#### Implementation Example
**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
);
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// You can retry with TransactionException::Retry().
```
**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;
}
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// You can retry with TransactionException::Retry().
```
**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
Get the player's submitted score for a specific global ranking
Retrieves the player's score for a specific global ranking and season.
Use this to display the player's current score on a specific leaderboard — for example, showing "Your score: 15,000 pts (Season 3)" on the ranking detail screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzGlobalRankingScore](#ezglobalrankingscore) | Global Ranking Score|
#### Implementation Example
**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;
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### listGlobalRankingScores
List the player's submitted scores for global rankings
Retrieves all scores the player has submitted to global rankings.
Each score entry shows which ranking it was submitted to and the score value.
Use this to display the player's own scores — for example, showing "Your High Scores: Stage Clear: 15,000 pts, Arena: 2,400 pts" on a profile or ranking overview screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | | | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzGlobalRankingScore>](#ezglobalrankingscore) | List of Global Ranking Scores|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeGlobalRankingScores(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeGlobalRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
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
);
// Start event handling
const auto CallbackId = Domain->SubscribeGlobalRankingScores(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeGlobalRankingScores(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### putGlobalRanking
Submit a score to a global ranking
Registers the player's score to the specified global ranking. You can also attach metadata (e.g., a replay ID or character name used).
If the player has already submitted a score, this updates it based on the ranking's rules (e.g., keep the highest score, or always use the latest).
Use this after the player completes a scored activity — for example, after clearing a stage, submit the clear time or score to the "High Score Ranking".
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Global Ranking Model name
Unique Global Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | Score
The score value submitted by the user. Must be within the range defined by the ranking model's minimumValue and maximumValue settings. |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzGlobalRankingScore](#ezglobalrankingscore) | Registered Global Ranking Score|
#### Implementation Example
**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
Get the player's own rank in a cluster ranking
Retrieves the player's own ranking entry within a specific cluster (group), including their rank position and score.
Use this to display the player's position within their group — for example, showing "Your guild rank: #3 (8,500 pts)" at the top of the guild ranking screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓| | ~ 1024 chars | Cluster Name
The name of the cluster (guild, gathering, or group) that this season belongs to. |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzClusterRankingData](#ezclusterrankingdata) | Cluster Ranking|
#### Implementation Example
**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
Get the cluster ranking leaderboard
Retrieves the leaderboard entries for a specific cluster (group), showing players ranked by their scores within that group.
Each entry includes the player's user ID, score, rank position, and any attached metadata.
Use this to display the group leaderboard — for example, showing the guild ranking "1st: Alice (8,500 pts), 2nd: Bob (7,200 pts), 3rd: Charlie (6,800 pts)" on a guild ranking screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓| | ~ 1024 chars | Cluster Name
The name of the cluster (guild, gathering, or group) that this season belongs to. |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzClusterRankingData>](#ezclusterrankingdata) | List of Cluster Rankings|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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
Get a specific cluster ranking definition by name
Retrieves a single cluster ranking model by specifying its name.
The returned information includes the score range, sort order, cluster type, reward settings, and season/entry period configurations.
Use this to display the rules of a specific cluster ranking — for example, showing "Guild DPS Ranking — Weekly reset, compete within your guild, Top 10 get rewards" on a ranking detail screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzClusterRankingModel](#ezclusterrankingmodel) | Cluster Ranking Model|
#### Implementation Example
**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;
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### listClusterRankingModels
List cluster ranking definitions
Retrieves all cluster ranking models registered in this Namespace.
A cluster ranking is a leaderboard within a specific group (cluster) — for example, rankings within a guild, a region, or a game server.
Unlike global rankings where all players compete together, cluster rankings let players compete within their group, which is useful for guild-based events or regional competitions.
Use this to see what cluster rankings exist — for example, to display "Guild DPS Ranking", "Regional Score Ranking" as options on a ranking screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzClusterRankingModel>](#ezclusterrankingmodel) | List of Cluster Ranking Models|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeClusterRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeClusterRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeClusterRankingModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeClusterRankingModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### getClusterRankingReceivedReward
Check if the player has claimed a specific cluster ranking reward
Retrieves the reward claim record for a specific cluster ranking, cluster, and season.
Use this to check if the player has already claimed the reward — for example, showing a "Claim Reward" button if unclaimed, or "Already Claimed" if already received, on a guild ranking results screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓| | ~ 1024 chars | Cluster Name
The name of the cluster for which the ranking reward was received. |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzClusterRankingReceivedReward](#ezclusterrankingreceivedreward) | Cluster Ranking Reward Received History|
#### Implementation Example
**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;
}
```
##### Value change event handling
**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(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### listClusterRankingReceivedRewards
List the player's cluster ranking reward claim history
Retrieves the player's history of claimed ranking rewards from cluster rankings.
Each entry shows which ranking, cluster, and season the reward was claimed for.
Use this to display reward claim status for group rankings — for example, showing "Guild DPS Ranking Season 1: Claimed, Season 2: Not yet claimed" on a guild ranking rewards screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | | | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | | | ~ 1024 chars | Cluster Name
The name of the cluster for which the ranking reward was received. |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzClusterRankingReceivedReward>](#ezclusterrankingreceivedreward) | List of Cluster Ranking Rewards Received|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingReceivedRewards(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
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"
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingReceivedRewards(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
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
);
// Start event handling
const auto CallbackId = Domain->SubscribeClusterRankingReceivedRewards(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeClusterRankingReceivedRewards(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### receiveClusterRankingReward
Claim the cluster ranking reward
Claims the ranking reward based on the player's final rank in the specified cluster ranking, cluster, and season.
The reward is determined by the player's rank position within their group and the ranking model's reward settings — for example, the top player in each guild might receive a special guild champion item.
The reward items are automatically granted to the player.
Use this when the player taps "Claim Reward" on the group ranking results screen after a season ends.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓| | ~ 1024 chars | Cluster Name
The name of the cluster for which the ranking reward was received. |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
| config | [List<EzConfig>](#ezconfig) | | | [] | 0 ~ 32 items | Configuration values applied to transaction variables |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzClusterRankingModel](#ezclusterrankingmodel) | Cluster Ranking Model|
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | List of Acquire Actions to be performed when rewards are received|
| transactionId | string | Issued transaction ID|
| stampSheet | string | Stamp sheet used to execute the exchange process|
| stampSheetEncryptionKeyId | string | Cryptographic key GRN used for stamp sheet signature calculations|
| autoRunStampSheet | bool | Whether automatic transaction execution is enabled|
| atomicCommit | bool | Whether to commit the transaction atomically|
| transaction | string | Issued transaction|
| transactionResult | [EzTransactionResult](#eztransactionresult) | Transaction Execution Result|
#### Implementation Example
**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
);
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// You can retry with TransactionException::Retry().
```
**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;
}
// In New Experience, stamp sheets are automatically executed at the SDK level.
// If an error occurs, a TransactionException is thrown.
// You can retry with TransactionException::Retry().
```
**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
Get the player's submitted score for a specific cluster ranking
Retrieves the player's score for a specific cluster ranking, cluster, and season.
Use this to display the player's current score within their group — for example, showing "Your score in Dragon Slayers guild: 8,500 pts (Season 2)" on a guild ranking detail screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓| | ~ 1024 chars | Cluster Name
The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzClusterRankingScore](#ezclusterrankingscore) | Cluster Ranking Score|
#### Implementation Example
**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;
}
```
##### Value change event handling
**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(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### listClusterRankingScores
List the player's submitted scores for cluster rankings
Retrieves the player's scores submitted to a specific cluster ranking within a specific cluster (group).
Use this to display the player's own scores within their group — for example, showing "Your Guild DPS Score: 8,500 pts" on a guild ranking screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | | | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | | | ~ 1024 chars | Cluster Name
The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzClusterRankingScore>](#ezclusterrankingscore) | List of Cluster Ranking Scores|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
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"
);
// Start event handling
var callbackId = domain.SubscribeClusterRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
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
);
// Start event handling
const auto CallbackId = Domain->SubscribeClusterRankingScores(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeClusterRankingScores(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### putClusterRanking
Submit a score to a cluster ranking
Registers the player's score to the specified cluster ranking within a specific cluster (group). You can also attach metadata.
The cluster name identifies which group the score belongs to — for example, the guild name for a guild ranking.
Use this after the player completes a scored activity within their group — for example, after clearing a guild raid boss, submit the DPS score to the "Guild DPS Ranking" for the player's guild.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Cluster Ranking Model name
Unique Cluster Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| clusterName | string | | ✓| | ~ 1024 chars | Cluster Name
The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | Score
The score value submitted by the user within this cluster. |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzClusterRankingScore](#ezclusterrankingscore) | Registered Cluster Ranking Score|
#### Implementation Example
**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
Check if the player is following a specific user for subscribe rankings
Retrieves the subscription information for a specific target user.
Use this to check if the player is already following a particular user — for example, showing a "Following" or "Follow" button on another player's profile, or verifying the subscription before displaying their score on the friend leaderboard.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| gameSession | GameSession | | ✓| | | GameSession |
| targetUserId | string | | ✓| | ~ 128 chars | Subscribe Target User ID |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzSubscribeUser](#ezsubscribeuser) | Subscribed User Information|
#### Implementation Example
**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
List users the player is following for subscribe rankings
Retrieves all users that the player has subscribed to (followed) for subscribe rankings.
Subscribe rankings only show scores from followed users, so this list determines who appears on the player's friend leaderboard.
Use this to display the player's "following" list for rankings — for example, showing "Following: Alice, Bob, Charlie" on a friend ranking management screen, or to check how many friends the player is tracking.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzSubscribeUser>](#ezsubscribeuser) | List of Subscribed User Information|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeSubscribes(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribes(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// Start event handling
var callbackId = domain.SubscribeSubscribes(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribes(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// Start event handling
const auto CallbackId = Domain->SubscribeSubscribes(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeSubscribes(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### getSubscribeRankingRank
Get the player's own rank in a subscribe (friend) ranking
Retrieves the player's own ranking entry among their friends, including their rank position and score.
Use this to display the player's position on the friend leaderboard — for example, showing "Your rank among friends: #2 (10,500 pts)" at the top of the friend ranking screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzSubscribeRankingData](#ezsubscriberankingdata) | Subscribe Ranking|
#### Implementation Example
**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
Get the subscribe (friend) ranking leaderboard
Retrieves the friend leaderboard, showing only scores from users the player has subscribed to (followed).
Each entry includes the user ID, score, rank position, and any attached metadata.
Use this to display the friend leaderboard — for example, showing "1st: Alice (12,000 pts), 2nd: You (10,500 pts), 3rd: Bob (9,800 pts)" on a friend ranking screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzSubscribeRankingData>](#ezsubscriberankingdata) | List of Subscribe Rankings|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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
Get a specific subscribe ranking definition by name
Retrieves a single subscribe ranking model by specifying its name.
The returned information includes the score range, sort order, and season/entry period configurations.
Use this to display the rules of a specific subscribe ranking — for example, showing "Friends High Score — Weekly reset, Higher score = better rank" on a ranking detail screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzSubscribeRankingModel](#ezsubscriberankingmodel) | Subscribe Ranking Model|
#### Implementation Example
**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;
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### listSubscribeRankingModels
List subscribe ranking definitions
Retrieves all subscribe ranking models registered in this Namespace.
A subscribe ranking is a friends-only leaderboard — the player only sees scores from users they have subscribed to (followed).
This is perfect for friend competitions — for example, "Friends High Score" or "Friends Weekly Challenge" where players compete only against their friends rather than all players in the game.
Use this to see what subscribe rankings exist — for example, to display "Friends High Score", "Friends Speed Clear" as options on a friend ranking screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzSubscribeRankingModel>](#ezsubscriberankingmodel) | List of Subscribe Ranking Models|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeSubscribeRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribeRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// Start event handling
var callbackId = domain.SubscribeSubscribeRankingModels(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribeRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// Start event handling
const auto CallbackId = Domain->SubscribeSubscribeRankingModels(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeSubscribeRankingModels(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### getSubscribeRankingScore
Get the player's submitted score for a specific subscribe ranking
Retrieves the player's score for a specific subscribe (friend) ranking and season.
Use this to display the player's current score in a specific friend ranking — for example, showing "Your score: 12,000 pts (This week)" on the friend ranking detail screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| season | long | | | | 0 ~ 9223372036854775805 | Season |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzSubscribeRankingScore](#ezsubscriberankingscore) | Subscribe Ranking Score|
#### Implementation Example
**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;
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
var callbackId = domain.Subscribe(
value => {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
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(
);
// Start event handling
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// Called when the value changes
// The "value" is passed the value after the change.
}
);
// Stop event handling
Domain->Unsubscribe(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### listSubscribeRankingScores
List the player's submitted scores for subscribe rankings
Retrieves all scores the player has submitted to subscribe (friend) rankings.
Use this to display the player's own scores in friend rankings — for example, showing "Your Friends High Score: 12,000 pts" on a friend ranking overview screen.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | | | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024 chars | Token specifying the position from which to start acquiring data |
| limit | int | | | 30 | 1 ~ 1000 | Number of data items to retrieve |
#### Result
| | Type | Description |
| --- | --- | --- |
| items | [List<EzSubscribeRankingScore>](#ezsubscriberankingscore) | List of Subscribe Ranking Scores|
| nextPageToken | string | Page token to retrieve the rest of the listing|
#### Implementation Example
**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());
}
```
##### Value change event handling
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeSubscribeRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
domain.UnsubscribeSubscribeRankingScores(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
// Start event handling
var callbackId = domain.SubscribeSubscribeRankingScores(
() => {
// Called when an element of the list changes.
}
);
// Stop event handling
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
);
// Start event handling
const auto CallbackId = Domain->SubscribeSubscribeRankingScores(
[]() {
// Called when an element of the list changes.
}
);
// Stop event handling
Domain->UnsubscribeSubscribeRankingScores(CallbackId);
```
{{% alert title="Warning" color="warning" %}}This event is triggered when the value stored in the SDK's local cache changes.
The local cache is updated only when executing the SDK's API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing jobs via GS2-JobQueue with GS2-Gateway notification enabled.
Therefore, callbacks will not be invoked if the value is changed in any other way.
{{% /alert %}}
---
### putSubscribeRanking
Submit a score to a subscribe ranking
Registers the player's score to the specified subscribe (friend) ranking. You can also attach metadata.
This score will appear on the friend leaderboards of all users who have subscribed to (followed) this player.
Use this after the player completes a scored activity — for example, after clearing a stage, submit the score to the "Friends High Score" ranking so the player's friends can see it.
#### Request
| | Type | Condition | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128 chars | Namespace name
Unique Namespace name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| rankingName | string | | ✓| | ~ 128 chars | Subscribe Ranking Model name
Unique Subscribe Ranking Model name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | Score |
| metadata | string | | | | ~ 512 chars | Metadata
Arbitrary values can be set in the metadata.
Since they do not affect GS2’s behavior, they can be used to store information used in the game. |
#### Result
| | Type | Description |
| --- | --- | --- |
| item | [EzSubscribeRankingScore](#ezsubscriberankingscore) | Registered Subscribe Ranking Score|
#### Implementation Example
**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();
```
---