> For the complete documentation index, see [llms.txt](/llms.txt)
# GS2-Ranking2 SDK for Game Engine API 레퍼런스
게임 엔진용 GS2-Ranking2 SDK의 모델 사양과 API 레퍼런스
## 모델
### EzGlobalRankingData
글로벌 랭킹
특정 시즌의 글로벌 랭킹에서의 랭킹 엔트리를 나타냅니다. 사용자의 스코어, 0부터 시작하는 인덱스(정렬 위치), 1부터 시작하는 순위(동점을 고려)를 포함합니다. 순위는 인덱스 + 1로 계산됩니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | 시즌
GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. 새로운 랭킹 기간마다 증가합니다. |
| userId | string | | ✓ | | ~ 128자 | 사용자ID |
| index | int | | | | 0 ~ 2147483646 | 인덱스
랭킹 내 이 엔트리의 0부터 시작하는 고유한 정렬 위치입니다. 순위와 달리, 스코어가 동점이어도 인덱스는 항상 고유합니다. 인덱스 기반 보상 계산에 사용됩니다. |
| rank | int | | | | 0 ~ 2147483646 | 순위
1부터 시작하는 랭킹 순위입니다. 스코어가 같은 플레이어는 동일한 순위를 공유합니다. 인덱스 + 1로 계산됩니다. 순위 기반 보상 계산에 사용됩니다. |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | 스코어 |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| updatedAt | long | | ※ | 현재 시각 | | 최종 갱신일시
UNIX 시간・밀리초
※ 서버가 자동으로 설정 |
**관련 메서드:**
getGlobalRankingRank - 글로벌 랭킹에서 플레이어 자신의 순위 조회
listGlobalRankings - 글로벌 랭킹의 리더보드 조회
---
### EzGlobalRankingReceivedReward
글로벌 랭킹 보상 수령 이력
글로벌 랭킹의 순위에 대해 보상을 설정할 수 있습니다.
보상을 설정하려면 순위 임계값과 보상 내용을 설정합니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | 시즌
GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. 새로운 랭킹 기간마다 증가합니다. |
| userId | string | | ✓ | | ~ 128자 | 사용자ID |
| receivedAt | long | | ※ | 현재 시각 | | 생성일시
UNIX 시간・밀리초
※ 서버가 자동으로 설정 |
**관련 메서드:**
getGlobalRankingReceivedReward - 특정 글로벌 랭킹 보상을 수령했는지 확인
listGlobalRankingReceivedRewards - 플레이어의 글로벌 랭킹 보상 수령 이력 목록 조회
---
### EzGlobalRankingScore
글로벌 랭킹 스코어
특정 시즌의 글로벌 랭킹에서 사용자의 등록 스코어를 저장합니다. 합산 모드가 활성화된 경우, 여러 개의 등록 스코어가 누적됩니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | 시즌
GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. 새로운 랭킹 기간마다 증가합니다. |
| userId | string | | ✓ | | ~ 128자 | 사용자ID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | 스코어
사용자가 등록한 스코어 값입니다. 랭킹 모델의 minimumValue와 maximumValue로 정의된 범위 내에 있어야 합니다. |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| updatedAt | long | | ※ | 현재 시각 | | 최종 갱신일시
UNIX 시간・밀리초
※ 서버가 자동으로 설정 |
**관련 메서드:**
getGlobalRankingScore - 특정 글로벌 랭킹에 등록한 플레이어의 점수 조회
listGlobalRankingScores - 글로벌 랭킹에 등록한 플레이어의 점수 목록 조회
putGlobalRanking - 글로벌 랭킹에 점수 등록
---
### EzClusterRankingData
클러스터 랭킹
특정 시즌·클러스터에서의 클러스터 랭킹의 랭킹 엔트리를 나타냅니다. 클러스터 내 사용자의 스코어, 0부터 시작하는 인덱스, 1부터 시작하는 순위를 포함합니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓ | | ~ 1024자 | 클러스터 이름
이 시즌이 속한 클러스터(길드, 게더링, 또는 그룹)의 이름입니다. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | 시즌
GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. |
| userId | string | | ✓ | | ~ 128자 | 사용자ID |
| index | int | | | | 0 ~ 2147483646 | 인덱스
클러스터 랭킹 내에서 0부터 시작하는 고유한 정렬 위치입니다. 스코어가 동점이어도 항상 고유합니다. |
| rank | int | | | | 0 ~ 2147483646 | 순위
클러스터 내에서 1부터 시작하는 랭킹 순위입니다. 스코어가 같은 플레이어는 동일한 순위를 공유합니다. 인덱스 + 1로 계산됩니다. |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | 스코어 |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| updatedAt | long | | ※ | 현재 시각 | | 최종 갱신일시
UNIX 시간・밀리초
※ 서버가 자동으로 설정 |
**관련 메서드:**
getClusterRankingRank - 클러스터 랭킹에서 플레이어 자신의 순위 조회
listClusterRankings - 클러스터 랭킹의 리더보드 조회
---
### EzClusterRankingReceivedReward
클러스터 랭킹 보상 수령 이력
클러스터 랭킹 순위에 따른 보상을 설정할 수 있습니다.
보상을 설정하려면 순위 임계값과 보상 내용을 설정합니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓ | | ~ 1024자 | 클러스터 이름
랭킹 보상을 수령한 클러스터의 이름입니다. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | 시즌
GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. |
| userId | string | | ✓ | | ~ 128자 | 사용자ID |
| receivedAt | long | | ※ | 현재 시각 | | 생성일시
UNIX 시간・밀리초
※ 서버가 자동으로 설정 |
**관련 메서드:**
getClusterRankingReceivedReward - 특정 클러스터 랭킹 보상을 수령했는지 확인
listClusterRankingReceivedRewards - 플레이어의 클러스터 랭킹 보상 수령 이력 목록 조회
---
### EzClusterRankingScore
클러스터 랭킹 스코어
특정 시즌·클러스터에서의 사용자 등록 스코어를 저장합니다. 스코어 접수 전에 클러스터 타입 설정에 따라 사용자의 클러스터 소속이 검증됩니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓ | | ~ 1024자 | 클러스터 이름
이 스코어가 속한 클러스터(길드, 개더링, 또는 임의의 그룹)의 이름입니다. 클러스터 타입 설정에 따라 사용자의 소속이 검증됩니다. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | 시즌
GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. |
| userId | string | | ✓ | | ~ 128자 | 사용자ID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | 스코어
이 클러스터 내에서 사용자가 등록한 스코어 값입니다. |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| updatedAt | long | | ※ | 현재 시각 | | 최종 갱신일시
UNIX 시간・밀리초
※ 서버가 자동으로 설정 |
**관련 메서드:**
getClusterRankingScore - 특정 클러스터 랭킹에 등록한 플레이어의 점수 조회
listClusterRankingScores - 클러스터 랭킹에 등록한 플레이어의 점수 목록 조회
putClusterRanking - 클러스터 랭킹에 점수 등록
---
### EzSubscribeRankingData
구독 랭킹
특정 시즌의 사용자별 맞춤 구독 랭킹에서의 랭킹 엔트리를 나타냅니다. 구독한 사용자의 점수를 포함하며, 친구 목록 내에서 순위가 매겨집니다. 각 엔트리에는 점수를 달성한 사용자ID가 포함됩니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | 시즌
GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. |
| scorerUserId | string | | ✓ | | ~ 128자 | 점수를 획득한 사용자ID
이 점수를 달성한 플레이어의 사용자ID입니다. 구독 랭킹에서는 구독한 사용자의 점수가 엔트리가 되므로, 이 필드는 어느 친구의 점수인지를 식별합니다. |
| index | int | | | | 0 ~ 2147483646 | 인덱스
구독 랭킹 내에서 0부터 시작하는 고유한 정렬 위치입니다. |
| rank | int | | | | 0 ~ 2147483646 | 순위
구독 랭킹 내에서 1부터 시작하는 랭킹 순위입니다. 인덱스 + 1로 계산됩니다. |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | 스코어 |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| updatedAt | long | | ※ | 현재 시각 | | 최종 갱신일시
UNIX 시간・밀리초
※ 서버가 자동으로 설정 |
**관련 메서드:**
getSubscribeRankingRank - 구독(친구) 랭킹에서 플레이어 자신의 순위 조회
listSubscribeRankings - 구독(친구) 랭킹의 리더보드 조회
---
### EzSubscribeRankingScore
구독 랭킹 스코어
특정 시즌의 구독 랭킹에서 사용자가 등록한 점수를 저장합니다. 이 점수는 이 사용자를 구독하고 있는 사용자에게 표시되어 맞춤형 친구 랭킹을 구성합니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | ✓ | | 0 ~ 9223372036854775805 | 시즌
GS2-Schedule 이벤트의 반복 횟수에 대응하는 시즌 번호입니다. |
| userId | string | | ✓ | | ~ 128자 | 사용자ID |
| score | long | | ✓ | | 0 ~ 9223372036854775805 | 스코어 |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| updatedAt | long | | ※ | 현재 시각 | | 최종 갱신일시
UNIX 시간・밀리초
※ 서버가 자동으로 설정 |
**관련 메서드:**
getSubscribeRankingScore - 특정 구독 랭킹에 등록한 플레이어의 점수 조회
listSubscribeRankingScores - 구독 랭킹에 등록한 플레이어의 점수 목록 조회
putSubscribeRanking - 구독 랭킹에 점수 등록
---
### EzSubscribeUser
구독 대상 사용자 정보
구독 랭킹에서 두 사용자 간의 구독 관계를 나타냅니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| rankingName | string | | ✓ | | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| userId | string | | ✓ | | ~ 128자 | 사용자ID |
| targetUserId | string | | ✓ | | ~ 128자 | 구독 대상 사용자 ID
구독 대상 플레이어의 사용자 ID입니다. 이 플레이어의 스코어가 구독자의 개인화된 랭킹에 포함됩니다. |
**관련 메서드:**
getSubscribe - 특정 사용자를 구독 랭킹용으로 팔로우하고 있는지 확인
listSubscribes - 구독 랭킹용으로 팔로우하고 있는 사용자 목록 조회
---
### EzGlobalRankingModel
글로벌 랭킹 모델
글로벌 랭킹은 모든 플레이어를 대상으로 한 랭킹을 구현하기 위한 모델입니다.
상위 1000위까지의 랭킹을 표시할 수 있습니다.
GS2-Schedule의 반복 이벤트와 연결하면 반복 횟수에 따라 랭킹을 초기화할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| globalRankingModelId | string | | ※ | | ~ 1024자 | 글로벌 랭킹 GRN
※ 서버가 자동으로 설정 |
| name | string | | ✓ | | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string | | | | ~ 1024자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| rankingRewards | [List<EzRankingReward>](#ezrankingreward) | {entryPeriodEventId} != null | | [] | 0 ~ 100 items | 랭킹 보상 목록
각 시즌 종료 시의 랭킹 순위에 따라 지급되는 보상 목록입니다. 스코어 등록 가능 기간 이벤트가 설정되어 있는 경우에만 이용할 수 있습니다. 각 보상은 순위 임계값과 실행할 입수 액션을 정의합니다. |
| entryPeriodEventId | string | | | | ~ 1024자 | 스코어 등록 가능 기간 이벤트 GRN
스코어를 등록할 수 있는 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. 반복 이벤트와 연결하면 반복 사이클마다 랭킹이 초기화되어 시즌제 랭킹을 구현할 수 있습니다. |
| accessPeriodEventId | string | | | | ~ 1024자 | 랭킹 데이터 접근 가능 기간 이벤트 GRN
랭킹 결과의 열람과 보상 수령이 가능한 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. 일반적으로 스코어 등록 기간 사이의 간격으로 설정합니다. |
**관련 메서드:**
getGlobalRankingModel - 이름을 지정하여 글로벌 랭킹 정의 조회
listGlobalRankingModels - 글로벌 랭킹 정의 목록 조회
receiveGlobalRankingReward - 글로벌 랭킹 보상 받기
---
### EzClusterRankingModel
클러스터 랭킹 모델
클러스터 랭킹은 길드나 게더링 내의 플레이어를 대상으로 하는 랭킹을 구현하기 위한 모델입니다.
상위 1000위까지의 랭킹을 표시할 수 있습니다.
GS2-Schedule의 반복 이벤트와 연동하면 반복 횟수에 따라 랭킹을 초기화할 수 있습니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| clusterRankingModelId | string | | ※ | | ~ 1024자 | 클러스터 랭킹 GRN
※ 서버가 자동으로 설정 |
| name | string | | ✓ | | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string | | | | ~ 1024자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| clusterType | 문자열 열거형
enum {
"Raw",
"Gs2Guild::Guild",
"Gs2Matchmaking::SeasonGathering"
}
| | ✓ | | | 클러스터 타입
랭킹의 세그멘테이션에 사용하는 그룹(클러스터)의 종류를 정의합니다. "Raw"는 소속 검증 없이 임의의 클러스터 이름을 지정할 수 있으며, "Gs2Guild::Guild"는 GS2-Guild 길드에 대한 소속을 검증하고, "Gs2Matchmaking::SeasonGathering"은 GS2-Matchmaking 시즌 개더링에 대한 소속을 검증합니다.Raw: 검증 없음 / Gs2Guild::Guild: GS2-Guild 길드 / Gs2Matchmaking::SeasonGathering: GS2-Matchmaking 시즌 개더링 / |
| rankingRewards | [List<EzRankingReward>](#ezrankingreward) | {entryPeriodEventId} != null | | [] | 0 ~ 100 items | 랭킹 보상 목록
각 시즌 종료 시의 랭킹 순위에 따라 지급되는 보상 목록입니다. 스코어 등록 가능 기간 이벤트가 설정되어 있는 경우에만 이용할 수 있습니다. |
| entryPeriodEventId | string | | | | ~ 1024자 | 스코어 등록 가능 기간 이벤트 GRN
스코어를 등록할 수 있는 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. 반복 이벤트와 연결하면 시즌제 랭킹을 구현할 수 있습니다. |
| accessPeriodEventId | string | | | | ~ 1024자 | 랭킹 데이터 접근 가능 기간 이벤트 GRN
랭킹 결과의 열람과 보상 수령이 가능한 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. |
**관련 메서드:**
getClusterRankingModel - 이름을 지정하여 클러스터 랭킹 정의를 조회
listClusterRankingModels - 클러스터 랭킹 정의 목록 조회
receiveClusterRankingReward - 클러스터 랭킹 보상 수령
---
### EzSubscribeRankingModel
구독 랭킹 모델
구독한 다른 플레이어의 점수를 집계하여 랭킹을 작성하는 모델입니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| subscribeRankingModelId | string | | ※ | | ~ 1024자 | 구독 랭킹 GRN
※ 서버가 자동으로 설정 |
| name | string | | ✓ | | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| metadata | string | | | | ~ 1024자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| entryPeriodEventId | string | | | | ~ 1024자 | 스코어 등록 가능 기간 이벤트 GRN
스코어를 등록할 수 있는 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. 반복 이벤트와 연결하면 시즌제 랭킹을 구현할 수 있습니다. |
| accessPeriodEventId | string | | | | ~ 1024자 | 랭킹 데이터 접근 가능 기간 이벤트 GRN
랭킹 결과를 열람할 수 있는 기간을 정의하는 GS2-Schedule의 이벤트 GRN입니다. |
**관련 메서드:**
getSubscribeRankingModel - 이름을 지정하여 구독 랭킹 정의를 조회
listSubscribeRankingModels - 구독 랭킹 정의 목록 조회
---
### EzRankingReward
랭킹 보상
점수 등록 기간이 설정된 랭킹에서, 등록 기간 외 참조 기간 내에 받을 수 있는 보상을 설정합니다.
반복 설정이 유효한 경우, 가장 최근에 종료된 기간의 랭킹이 보상 수령 대상이 됩니다.
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| thresholdRank | int | | ✓ | | 1 ~ 1001 | 순위 임계값
이 보상 티어의 순위 임계값입니다. 순위(또는 인덱스, rewardCalculationIndex 설정에 따라 다름)가 이 임계값 이상인 플레이어가 이 보상을 받습니다. 1001로 설정하면 랭크 외(상위 1000위 밖) 플레이어를 위한 보상을 정의할 수 있습니다. |
| metadata | string | | | | ~ 1024자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | | | [] | 0 ~ 100 items | 입수 액션 리스트
플레이어가 이 랭킹 보상을 수령할 때 실행되는 입수 액션의 목록입니다. 이 순위 임계값을 달성한 보상으로 지급되는 아이템, 화폐, 기타 리소스를 정의합니다. |
**관련 모델:**
EzGlobalRankingModel - 글로벌 랭킹 모델
EzClusterRankingModel - 클러스터 랭킹 모델
---
### EzAcquireAction
입수 액션
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형
enum {
}
| | ✓ | | | 입수 액션에서 실행할 액션의 종류 |
| request | string | | ✓ | | ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
**관련 메서드:**
receiveGlobalRankingReward - 글로벌 랭킹 보상 받기
receiveClusterRankingReward - 클러스터 랭킹 보상 수령
**관련 모델:**
EzRankingReward - 랭킹 보상
---
### EzConfig
컨피그 설정
트랜잭션의 변수에 적용하는 설정 값
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| key | string | | ✓ | | ~ 64자 | 이름 |
| value | string | | | | ~ 51200자 | 값 |
**관련 메서드:**
receiveGlobalRankingReward - 글로벌 랭킹 보상 받기
receiveClusterRankingReward - 클러스터 랭킹 보상 수령
---
### EzVerifyActionResult
검증 액션 실행 결과
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형
enum {
}
| | ✓ | | | 검증 액션에서 실행할 액션의 종류 |
| verifyRequest | string | | ✓ | | ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
| statusCode | int | | | | 0 ~ 999 | 상태 코드 |
| verifyResult | string | | | | ~ 1048576자 | 결과 내용 |
**관련 모델:**
EzTransactionResult - 트랜잭션 실행 결과
---
### EzConsumeActionResult
소비 액션 실행 결과
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형
enum {
}
| | ✓ | | | 소비 액션에서 실행할 액션의 종류 |
| consumeRequest | string | | ✓ | | ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
| statusCode | int | | | | 0 ~ 999 | 상태 코드 |
| consumeResult | string | | | | ~ 1048576자 | 결과 내용 |
**관련 모델:**
EzTransactionResult - 트랜잭션 실행 결과
---
### EzAcquireActionResult
획득 액션 실행 결과
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| action | 문자열 열거형
enum {
}
| | ✓ | | | 입수 액션에서 실행할 액션의 종류 |
| acquireRequest | string | | ✓ | | ~ 524288자 | 액션 실행 시 사용되는 요청의 JSON 문자열 |
| statusCode | int | | | | 0 ~ 999 | 상태 코드 |
| acquireResult | string | | | | ~ 1048576자 | 결과 내용 |
**관련 모델:**
EzTransactionResult - 트랜잭션 실행 결과
---
### EzTransactionResult
트랜잭션 실행 결과
서버 사이드에서 트랜잭션 자동 실행 기능을 이용하여 실행된 트랜잭션의 실행 결과
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| transactionId | string | | ✓ | | 36 ~ 36자 | 트랜잭션 ID |
| verifyResults | [List<EzVerifyActionResult>](#ezverifyactionresult) | | | | 0 ~ 10 items | 검증 액션의 실행 결과 목록 |
| consumeResults | [List<EzConsumeActionResult>](#ezconsumeactionresult) | | | [] | 0 ~ 10 items | 소비 액션의 실행 결과 목록 |
| acquireResults | [List<EzAcquireActionResult>](#ezacquireactionresult) | | | [] | 0 ~ 100 items | 획득 액션 실행 결과 리스트 |
**관련 메서드:**
receiveGlobalRankingReward - 글로벌 랭킹 보상 받기
receiveClusterRankingReward - 클러스터 랭킹 보상 수령
---
## 메서드
### getGlobalRankingRank
글로벌 랭킹에서 플레이어 자신의 순위 조회
플레이어 자신의 랭킹 항목을 조회합니다. 순위와 점수가 포함됩니다.
리더보드에서 플레이어의 위치를 표시할 때 사용합니다. 예를 들어 랭킹 화면 상단에서 "당신의 순위: 42위(15,000점)"과 같이 표시하거나, "10,000명 중 42위입니다"와 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzGlobalRankingData](#ezglobalrankingdata) | 글로벌 랭킹|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
gameSession: GameSession
);
var result = await domain.GetGlobalRankingRankAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var future = domain.GetGlobalRankingRankFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto Future = Domain->GetGlobalRankingRank(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// 변경된 값 / 결과 값을 취득
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
).global_ranking_season(
null,
null
).global_ranking_data(
null
)
var async_result = await domain.get_global_ranking_rank(
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---
### listGlobalRankings
글로벌 랭킹의 리더보드 조회
글로벌 랭킹의 리더보드 항목을 조회하여 점수순으로 순위가 매겨진 플레이어를 표시합니다.
각 항목에는 플레이어의 사용자 ID, 점수, 순위, 첨부된 메타데이터가 포함됩니다.
리더보드를 표시할 때 사용합니다. 예를 들어 랭킹 화면에서 "1위: Alice(25,000점), 2위: Bob(22,500점), 3위: Charlie(20,000점)"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzGlobalRankingData>](#ezglobalrankingdata) | 글로벌 랭킹 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var items = await domain.GlobalRankingsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: null,
userId: "user-0001"
);
var it = domain.GlobalRankings(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankings(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### getGlobalRankingModel
이름을 지정하여 글로벌 랭킹 정의 조회
이름을 지정하여 글로벌 랭킹 모델을 1건 조회합니다.
조회할 수 있는 정보에는 스코어 범위, 정렬 순서, 보상 설정, 시즌/참가 기간 설정이 포함됩니다.
특정 랭킹의 규칙을 표시할 때 사용합니다. 예를 들어, 랭킹 상세 화면에서 "하이스코어 랭킹 — 매월 리셋, 상위 100명에게 보상, 스코어가 높을수록 상위"와 같이 표시하는 경우에 편리합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzGlobalRankingModel](#ezglobalrankingmodel) | 글로벌 랭킹 모델|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### listGlobalRankingModels
글로벌 랭킹 정의 목록 조회
이 네임스페이스에 등록된 모든 글로벌 랭킹 모델을 조회합니다.
글로벌 랭킹은 게임 내 모든 플레이어가 서로 경쟁하는 리더보드입니다. 예를 들어 "월드 하이스코어", "아레나 레이팅", "총 데미지 랭킹" 등이 있습니다.
각 모델은 랭킹 규칙을 정의합니다: 스코어 범위, 정렬 순서(오름차순 또는 내림차순), 시즌 스케줄, 랭킹 보상.
어떤 글로벌 랭킹이 있는지 확인할 때 사용합니다. 예를 들어 "리더보드" 메뉴에서 "하이스코어 랭킹", "스피드클리어 랭킹", "PvP 레이팅"의 선택지를 표시하는 경우에 편리합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzGlobalRankingModel>](#ezglobalrankingmodel) | 글로벌 랭킹 모델 목록|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.GlobalRankingModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.GlobalRankingModels(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->GlobalRankingModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeGlobalRankingModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeGlobalRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeGlobalRankingModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeGlobalRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeGlobalRankingModels(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeGlobalRankingModels(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### getGlobalRankingReceivedReward
특정 글로벌 랭킹 보상을 수령했는지 확인
특정 글로벌 랭킹과 시즌의 보상 수령 기록을 조회합니다.
플레이어가 특정 랭킹 시즌의 보상을 이미 수령했는지 확인할 때 사용합니다. 예를 들어, 미수령이면 "보상 받기" 버튼을 표시하고, 수령완료면 "수령완료"라고 표시하는 경우에 편리합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzGlobalRankingReceivedReward](#ezglobalrankingreceivedreward) | 글로벌 랭킹 보상 수령 이력|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
).global_ranking_season(
0,
null
).global_ranking_received_reward(
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
).global_ranking_season(
0,
null
).global_ranking_received_reward(
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### listGlobalRankingReceivedRewards
플레이어의 글로벌 랭킹 보상 수령 이력 목록 조회
글로벌 랭킹에서 플레이어가 수령한 랭킹 보상의 이력을 조회합니다.
각 항목에는 어떤 랭킹과 시즌의 보상을 수령했는지가 표시되며, 어떤 보상이 이미 회수되었는지 확인할 수 있습니다.
보상 수령 현황을 표시할 때 사용합니다. 예를 들어, 랭킹 보상 화면에서 "하이스코어 랭킹 시즌1: 수령완료, 시즌2: 수령완료, 시즌3: 미수령"과 같이 표시하는 경우에 편리합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | | | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzGlobalRankingReceivedReward>](#ezglobalrankingreceivedreward) | 글로벌 랭킹 보상 수령 이력 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.GlobalRankingReceivedRewardsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.GlobalRankingReceivedRewards(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankingReceivedRewards(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeGlobalRankingReceivedRewards(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeGlobalRankingReceivedRewards(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeGlobalRankingReceivedRewards(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeGlobalRankingReceivedRewards(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeGlobalRankingReceivedRewards(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeGlobalRankingReceivedRewards(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### receiveGlobalRankingReward
글로벌 랭킹 보상 받기
지정한 글로벌 랭킹과 시즌에서의 플레이어의 최종 순위에 따라 랭킹 보상을 받습니다.
보상은 플레이어의 순위와 랭킹 모델의 보상 설정에 따라 결정됩니다. 예를 들어, 상위 10명은 특별 아이템을, 상위 100명은 젬을 받도록 설정할 수 있습니다.
보상 아이템은 플레이어에게 자동으로 지급됩니다.
시즌 종료 후 랭킹 결과 화면에서 플레이어가 "보상 받기"를 탭했을 때 사용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
| config | [List<EzConfig>](#ezconfig) | | | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzGlobalRankingModel](#ezglobalrankingmodel) | 글로벌 랭킹 모델|
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | 보상 수령 시 실행되는 입수 액션 목록|
| transactionId | string | 발행된 트랜잭션 ID|
| stampSheet | string | 교환 처리 실행에 사용하는 스탬프 시트|
| stampSheetEncryptionKeyId | string | 스탬프 시트의 서명 계산에 사용한 암호화 키 GRN|
| autoRunStampSheet | bool | 트랜잭션 자동 실행이 활성화되어 있는지 여부|
| atomicCommit | bool | 트랜잭션을 원자적으로 커밋할지 여부|
| transaction | string | 발행된 트랜잭션|
| transactionResult | [EzTransactionResult](#eztransactionresult) | 트랜잭션 실행 결과|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var result = await domain.ReceiveGlobalRankingRewardAsync(
config: null
);
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다.
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingReceivedReward(
);
var future = domain.ReceiveGlobalRankingRewardFuture(
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다.
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingReceivedReward(
);
const auto Future = Domain->ReceiveGlobalRankingReward(
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
).global_ranking_season(
0,
null
).global_ranking_received_reward(
)
var async_result = await domain.receive_global_ranking_reward(
null # config
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---
### getGlobalRankingScore
특정 글로벌 랭킹에 등록한 플레이어의 점수 조회
특정 글로벌 랭킹과 시즌의 플레이어 점수를 조회합니다.
특정 리더보드에서 플레이어의 현재 점수를 표시할 때 사용합니다. 예를 들어 랭킹 상세 화면에서 "당신의 점수: 15,000점(시즌 3)"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzGlobalRankingScore](#ezglobalrankingscore) | 글로벌 랭킹 스코어|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
).global_ranking_season(
0,
null
).global_ranking_score(
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
).GlobalRankingScore(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
)->GlobalRankingScore(
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
).global_ranking_season(
0,
null
).global_ranking_score(
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### listGlobalRankingScores
글로벌 랭킹에 등록한 플레이어의 점수 목록 조회
플레이어가 글로벌 랭킹에 등록한 모든 점수를 조회합니다.
각 점수 항목에는 어떤 랭킹에 등록되었는지와 점수 값이 표시됩니다.
플레이어 자신의 점수를 표시할 때 사용합니다. 예를 들어 프로필 화면이나 랭킹 개요 화면에서 "당신의 하이스코어: 스테이지 클리어: 15,000점, 아레나: 2,400점"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | | | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzGlobalRankingScore>](#ezglobalrankingscore) | 글로벌 랭킹 스코어 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.GlobalRankingScoresAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.GlobalRankingScores(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->GlobalRankingScores(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeGlobalRankingScores(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeGlobalRankingScores(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeGlobalRankingScores(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeGlobalRankingScores(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeGlobalRankingScores(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeGlobalRankingScores(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### putGlobalRanking
글로벌 랭킹에 점수 등록
지정한 글로벌 랭킹에 플레이어의 점수를 등록합니다. 메타데이터(예: 리플레이 ID나 사용한 캐릭터 이름)를 첨부할 수도 있습니다.
플레이어가 이미 점수를 등록한 경우, 랭킹의 규칙에 따라 갱신됩니다(예: 최고 점수를 유지하거나 항상 최신 점수를 사용).
플레이어가 점수 대상 활동을 완료한 후에 사용합니다. 예를 들어 스테이지를 클리어한 후 클리어 타임이나 점수를 "하이스코어 랭킹"에 등록하는 경우입니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 글로벌 랭킹 모델 이름
글로벌 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | 스코어
사용자가 등록한 스코어 값입니다. 랭킹 모델의 minimumValue와 maximumValue로 정의된 범위 내에 있어야 합니다. |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzGlobalRankingScore](#ezglobalrankingscore) | 등록한 글로벌 랭킹 스코어|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var result = await domain.PutGlobalRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).GlobalRankingModel(
rankingName: "ranking-0001"
).GlobalRankingSeason(
season: 0,
userId: "user-0001"
);
var future = domain.PutGlobalRankingFuture(
score: 100L,
metadata: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->GlobalRankingModel(
"ranking-0001" // rankingName
)->GlobalRankingSeason(
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutGlobalRanking(
100L // score
// metadata
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// 변경된 값 / 결과 값을 취득
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).global_ranking_model(
"ranking-0001"
).global_ranking_season(
0,
null
)
var async_result = await domain.put_global_ranking(
100, # score
null # metadata
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---
### getClusterRankingRank
클러스터 랭킹에서 플레이어 자신의 순위 조회
특정 클러스터(그룹) 내에서 플레이어 자신의 랭킹 항목을 조회합니다. 순위와 점수가 포함됩니다.
그룹 내에서 플레이어의 위치를 표시할 때 사용합니다. 예를 들어 길드 랭킹 화면 상단에서 "당신의 길드 내 순위: 3위(8,500점)"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓| | ~ 1024자 | 클러스터 이름
이 시즌이 속한 클러스터(길드, 게더링, 또는 그룹)의 이름입니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzClusterRankingData](#ezclusterrankingdata) | 클러스터 랭킹|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
gameSession: GameSession
);
var result = await domain.GetClusterRankingRankAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var future = domain.GetClusterRankingRankFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
nullptr, // season
"user-0001" // userId
);
const auto Future = Domain->GetClusterRankingRank(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// 변경된 값 / 결과 값을 취득
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
).cluster_ranking_season(
"cluster-0001",
null,
null
).cluster_ranking_data(
null
)
var async_result = await domain.get_cluster_ranking_rank(
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---
### listClusterRankings
클러스터 랭킹의 리더보드 조회
특정 클러스터(그룹)의 리더보드 항목을 조회하여 해당 그룹 내에서 점수순으로 순위가 매겨진 플레이어를 표시합니다.
각 항목에는 플레이어의 사용자 ID, 점수, 순위, 첨부된 메타데이터가 포함됩니다.
그룹의 리더보드를 표시할 때 사용합니다. 예를 들어 길드 랭킹 화면에서 "1위: Alice(8,500점), 2위: Bob(7,200점), 3위: Charlie(6,800점)"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓| | ~ 1024자 | 클러스터 이름
이 시즌이 속한 클러스터(길드, 게더링, 또는 그룹)의 이름입니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzClusterRankingData>](#ezclusterrankingdata) | 클러스터 랭킹 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var items = await domain.ClusterRankingsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: null,
userId: "user-0001"
);
var it = domain.ClusterRankings(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankings(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### getClusterRankingModel
이름을 지정하여 클러스터 랭킹 정의를 조회
이름을 지정하여 클러스터 랭킹 모델을 1건 조회합니다.
조회할 수 있는 정보에는 점수 범위, 정렬 순서, 클러스터 타입, 보상 설정, 시즌/참가 기간 설정이 포함됩니다.
특정 클러스터 랭킹의 규칙을 표시할 때 사용합니다. 예를 들어 랭킹 상세 화면에서 "길드 DPS 랭킹 — 주간 리셋, 길드 내에서 경쟁, 상위 10명에게 보상"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzClusterRankingModel](#ezclusterrankingmodel) | 클러스터 랭킹 모델|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### listClusterRankingModels
클러스터 랭킹 정의 목록 조회
이 네임스페이스에 등록된 모든 클러스터 랭킹 모델을 조회합니다.
클러스터 랭킹은 특정 그룹(클러스터) 내의 리더보드입니다. 예를 들어 길드 내 랭킹, 지역별 랭킹, 게임 서버 내 랭킹 등이 있습니다.
모든 플레이어가 함께 경쟁하는 글로벌 랭킹과 달리, 클러스터 랭킹에서는 그룹 내에서 경쟁합니다. 길드 이벤트나 지역 대항전에 유용합니다.
어떤 클러스터 랭킹이 있는지 확인할 때 사용합니다. 예를 들어 랭킹 화면에서 "길드 DPS 랭킹", "지역 점수 랭킹"과 같은 선택지를 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzClusterRankingModel>](#ezclusterrankingmodel) | 클러스터 랭킹 모델 목록|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.ClusterRankingModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.ClusterRankingModels(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->ClusterRankingModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeClusterRankingModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeClusterRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeClusterRankingModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeClusterRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeClusterRankingModels(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeClusterRankingModels(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### getClusterRankingReceivedReward
특정 클러스터 랭킹 보상을 수령했는지 확인
특정 클러스터 랭킹, 클러스터, 시즌의 보상 수령 기록을 조회합니다.
플레이어가 이미 보상을 수령했는지 확인할 때 사용합니다. 예를 들어 길드 랭킹 결과 화면에서 미수령이면 "보상 받기" 버튼을 표시하고, 이미 수령했다면 "수령 완료"라고 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓| | ~ 1024자 | 클러스터 이름
랭킹 보상을 수령한 클러스터의 이름입니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzClusterRankingReceivedReward](#ezclusterrankingreceivedreward) | 클러스터 랭킹 보상 수령 이력|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
).cluster_ranking_season(
"cluster-0001",
0,
null
).cluster_ranking_received_reward(
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
).cluster_ranking_season(
"cluster-0001",
0,
null
).cluster_ranking_received_reward(
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### listClusterRankingReceivedRewards
플레이어의 클러스터 랭킹 보상 수령 이력 목록 조회
클러스터 랭킹에서 플레이어가 수령한 랭킹 보상의 이력을 조회합니다.
각 항목에는 어떤 랭킹, 클러스터, 시즌의 보상을 수령했는지가 표시됩니다.
그룹 랭킹의 보상 수령 상태를 표시할 때 사용합니다. 예를 들어 길드 랭킹 보상 화면에서 "길드 DPS 랭킹 시즌 1: 수령 완료, 시즌 2: 미수령"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | | | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | | | ~ 1024자 | 클러스터 이름
랭킹 보상을 수령한 클러스터의 이름입니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzClusterRankingReceivedReward>](#ezclusterrankingreceivedreward) | 클러스터 랭킹 보상 수령 이력 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var items = await domain.ClusterRankingReceivedRewardsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var it = domain.ClusterRankingReceivedRewards(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankingReceivedRewards(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeClusterRankingReceivedRewards(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeClusterRankingReceivedRewards(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeClusterRankingReceivedRewards(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeClusterRankingReceivedRewards(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeClusterRankingReceivedRewards(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeClusterRankingReceivedRewards(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### receiveClusterRankingReward
클러스터 랭킹 보상 수령
지정한 클러스터 랭킹, 클러스터, 시즌에서 플레이어의 최종 순위에 따라 랭킹 보상을 수령합니다.
보상은 그룹 내에서 플레이어의 순위와 랭킹 모델의 보상 설정에 따라 결정됩니다. 예를 들어 각 길드의 1위 플레이어가 특별한 길드 챔피언 아이템을 받도록 설정할 수 있습니다.
보상 아이템은 플레이어에게 자동으로 지급됩니다.
시즌 종료 후 그룹 랭킹 결과 화면에서 플레이어가 "보상 받기"를 탭했을 때 사용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓| | ~ 1024자 | 클러스터 이름
랭킹 보상을 수령한 클러스터의 이름입니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
| config | [List<EzConfig>](#ezconfig) | | | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzClusterRankingModel](#ezclusterrankingmodel) | 클러스터 랭킹 모델|
| acquireActions | [List<EzAcquireAction>](#ezacquireaction) | 보상 수령 시 실행되는 입수 액션 목록|
| transactionId | string | 발행된 트랜잭션 ID|
| stampSheet | string | 교환 처리 실행에 사용하는 스탬프 시트|
| stampSheetEncryptionKeyId | string | 스탬프 시트의 서명 계산에 사용한 암호화 키 GRN|
| autoRunStampSheet | bool | 트랜잭션 자동 실행이 활성화되어 있는지 여부|
| atomicCommit | bool | 트랜잭션을 원자적으로 커밋할지 여부|
| transaction | string | 발행된 트랜잭션|
| transactionResult | [EzTransactionResult](#eztransactionresult) | 트랜잭션 실행 결과|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var result = await domain.ReceiveClusterRankingRewardAsync(
config: null
);
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다.
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingReceivedReward(
);
var future = domain.ReceiveClusterRankingRewardFuture(
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다.
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingReceivedReward(
);
const auto Future = Domain->ReceiveClusterRankingReward(
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
).cluster_ranking_season(
"cluster-0001",
0,
null
).cluster_ranking_received_reward(
)
var async_result = await domain.receive_cluster_ranking_reward(
null # config
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---
### getClusterRankingScore
특정 클러스터 랭킹에 등록한 플레이어의 점수 조회
특정 클러스터 랭킹, 클러스터, 시즌의 플레이어 점수를 조회합니다.
그룹 내에서 플레이어의 현재 점수를 표시할 때 사용합니다. 예를 들어 길드 랭킹 상세 화면에서 "Dragon Slayers 길드에서 당신의 점수: 8,500점(시즌 2)"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓| | ~ 1024자 | 클러스터 이름
이 스코어가 속한 클러스터(길드, 개더링, 또는 임의의 그룹)의 이름입니다. 클러스터 타입 설정에 따라 사용자의 소속이 검증됩니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzClusterRankingScore](#ezclusterrankingscore) | 클러스터 랭킹 스코어|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
).cluster_ranking_season(
"cluster-0001",
0,
null
).cluster_ranking_score(
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
).ClusterRankingScore(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
)->ClusterRankingScore(
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
).cluster_ranking_season(
"cluster-0001",
0,
null
).cluster_ranking_score(
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### listClusterRankingScores
클러스터 랭킹에 등록한 플레이어의 점수 목록 조회
특정 클러스터(그룹) 내의 특정 클러스터 랭킹에 등록한 플레이어의 점수를 조회합니다.
그룹 내에서 플레이어 자신의 점수를 표시할 때 사용합니다. 예를 들어 길드 랭킹 화면에서 "당신의 길드 DPS 점수: 8,500점"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | | | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | | | ~ 1024자 | 클러스터 이름
이 스코어가 속한 클러스터(길드, 개더링, 또는 임의의 그룹)의 이름입니다. 클러스터 타입 설정에 따라 사용자의 소속이 검증됩니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzClusterRankingScore>](#ezclusterrankingscore) | 클러스터 랭킹 스코어 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var items = await domain.ClusterRankingScoresAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var it = domain.ClusterRankingScores(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto It = Domain->ClusterRankingScores(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeClusterRankingScores(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeClusterRankingScores(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeClusterRankingScores(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeClusterRankingScores(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeClusterRankingScores(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeClusterRankingScores(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### putClusterRanking
클러스터 랭킹에 점수 등록
특정 클러스터(그룹) 내의 지정한 클러스터 랭킹에 플레이어의 점수를 등록합니다. 메타데이터를 첨부할 수도 있습니다.
클러스터 이름은 점수가 어느 그룹에 속하는지를 식별합니다. 예를 들어 길드 랭킹의 경우 길드 이름입니다.
플레이어가 그룹 내에서 점수 대상 활동을 완료한 후에 사용합니다. 예를 들어 길드 레이드 보스를 클리어한 후 DPS 점수를 플레이어의 길드의 "길드 DPS 랭킹"에 등록하는 경우입니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 클러스터 랭킹 모델 이름
클러스터 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| clusterName | string | | ✓| | ~ 1024자 | 클러스터 이름
이 스코어가 속한 클러스터(길드, 개더링, 또는 임의의 그룹)의 이름입니다. 클러스터 타입 설정에 따라 사용자의 소속이 검증됩니다. |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | 스코어
이 클러스터 내에서 사용자가 등록한 스코어 값입니다. |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzClusterRankingScore](#ezclusterrankingscore) | 등록한 클러스터 랭킹 스코어|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var result = await domain.PutClusterRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).ClusterRankingModel(
rankingName: "ranking-0001"
).ClusterRankingSeason(
clusterName: "cluster-0001",
season: 0,
userId: "user-0001"
);
var future = domain.PutClusterRankingFuture(
score: 100L,
metadata: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->ClusterRankingModel(
"ranking-0001" // rankingName
)->ClusterRankingSeason(
"cluster-0001", // clusterName
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutClusterRanking(
100L // score
// metadata
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// 변경된 값 / 결과 값을 취득
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).cluster_ranking_model(
"ranking-0001"
).cluster_ranking_season(
"cluster-0001",
0,
null
)
var async_result = await domain.put_cluster_ranking(
100, # score
null # metadata
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---
### getSubscribe
특정 사용자를 구독 랭킹용으로 팔로우하고 있는지 확인
특정 대상 사용자의 구독 정보를 조회합니다.
플레이어가 특정 사용자를 이미 팔로우하고 있는지 확인할 때 사용합니다. 예를 들어, 다른 플레이어의 프로필에서 "팔로우 중"/"팔로우" 버튼을 표시하거나, 친구 리더보드에 스코어를 표시하기 전에 구독 여부를 확인하는 경우에 편리합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓| | | GameSession |
| targetUserId | string | | ✓| | ~ 128자 | 구독 대상 사용자 ID |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzSubscribeUser](#ezsubscribeuser) | 구독 대상 사용자 정보|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
rankingName: "ranking-0001"
).SubscribeUser(
targetUserId: "user-0002"
);
var result = await domain.GetSubscribeAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Subscribe(
rankingName: "ranking-0001"
).SubscribeUser(
targetUserId: "user-0002"
);
var future = domain.GetSubscribeFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Subscribe(
"ranking-0001" // rankingName
)->SubscribeUser(
"user-0002" // targetUserId
);
const auto Future = Domain->GetSubscribe(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// 변경된 값 / 결과 값을 취득
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).me(game_session).subscribe(
"ranking-0001"
).subscribe_user(
"user-0002"
)
var async_result = await domain.get_subscribe(
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---
### listSubscribes
구독 랭킹용으로 팔로우하고 있는 사용자 목록 조회
구독 랭킹을 위해 플레이어가 구독(팔로우)하고 있는 모든 사용자를 조회합니다.
구독 랭킹은 팔로우한 사용자의 스코어만 표시되므로, 이 목록이 플레이어의 친구 리더보드에 누가 표시될지를 결정합니다.
랭킹용 "팔로우 중" 목록을 표시할 때 사용합니다. 예를 들어, 친구 랭킹 관리 화면에서 "팔로우 중: Alice, Bob, Charlie"와 같이 표시하거나, 플레이어가 몇 명의 친구를 추적하고 있는지 확인하는 경우에 편리합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzSubscribeUser>](#ezsubscribeuser) | 구독 대상 사용자 정보 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.SubscribesAsync(
rankingName: "ranking-0001"
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Subscribes(
rankingName: "ranking-0001"
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Subscribes(
"ranking-0001" // rankingName
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeSubscribes(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeSubscribes(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeSubscribes(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeSubscribes(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeSubscribes(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeSubscribes(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### getSubscribeRankingRank
구독(친구) 랭킹에서 플레이어 자신의 순위 조회
친구 간에서 플레이어 자신의 랭킹 항목을 조회합니다. 순위와 점수가 포함됩니다.
친구 리더보드에서 플레이어의 위치를 표시할 때 사용합니다. 예를 들어 친구 랭킹 화면 상단에서 "친구 내 순위: 2위(10,500점)"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzSubscribeRankingData](#ezsubscriberankingdata) | 구독 랭킹|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
).SubscribeRankingData(
scorerUserId: null
);
var result = await domain.GetSubscribeRankingRankAsync(
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
).SubscribeRankingData(
scorerUserId: null
);
var future = domain.GetSubscribeRankingRankFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
nullptr, // season
"user-0001" // userId
)->SubscribeRankingData(
nullptr // scorerUserId
);
const auto Future = Domain->GetSubscribeRankingRank(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// 변경된 값 / 결과 값을 취득
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).subscribe_ranking_model(
"ranking-0001"
).subscribe_ranking_season(
null,
null
).subscribe_ranking_data(
null
)
var async_result = await domain.get_subscribe_ranking_rank(
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---
### listSubscribeRankings
구독(친구) 랭킹의 리더보드 조회
친구 리더보드를 조회합니다. 플레이어가 구독(팔로우)한 사용자의 점수만 표시됩니다.
각 항목에는 사용자 ID, 점수, 순위, 첨부된 메타데이터가 포함됩니다.
친구 리더보드를 표시할 때 사용합니다. 예를 들어 친구 랭킹 화면에서 "1위: Alice(12,000점), 2위: 나(10,500점), 3위: Bob(9,800점)"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzSubscribeRankingData>](#ezsubscriberankingdata) | 구독 랭킹 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
);
var items = await domain.SubscribeRankingsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: null,
userId: "user-0001"
);
var it = domain.SubscribeRankings(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
nullptr, // season
"user-0001" // userId
);
const auto It = Domain->SubscribeRankings(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
---
### getSubscribeRankingModel
이름을 지정하여 구독 랭킹 정의를 조회
이름을 지정하여 구독 랭킹 모델을 1건 조회합니다.
조회할 수 있는 정보에는 점수 범위, 정렬 순서, 시즌/참가 기간 설정이 포함됩니다.
특정 구독 랭킹의 규칙을 표시할 때 사용합니다. 예를 들어 랭킹 상세 화면에서 "친구 하이스코어 — 주간 리셋, 점수가 높을수록 상위"와 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzSubscribeRankingModel](#ezsubscriberankingmodel) | 구독 랭킹 모델|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).subscribe_ranking_model(
"ranking-0001"
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).subscribe_ranking_model(
"ranking-0001"
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### listSubscribeRankingModels
구독 랭킹 정의 목록 조회
이 네임스페이스에 등록된 모든 구독 랭킹 모델을 조회합니다.
구독 랭킹은 친구 전용 리더보드입니다. 플레이어는 자신이 구독(팔로우)한 사용자의 점수만 표시됩니다.
친구 간의 경쟁에 최적입니다. 예를 들어 "친구 하이스코어", "친구 위클리 챌린지"처럼 게임 전체가 아닌 친구 간에만 경쟁하는 랭킹입니다.
어떤 구독 랭킹이 있는지 확인할 때 사용합니다. 예를 들어 친구 랭킹 화면에서 "친구 하이스코어", "친구 스피드클리어"와 같은 선택지를 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzSubscribeRankingModel>](#ezsubscriberankingmodel) | 구독 랭킹 모델 목록|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var items = await domain.SubscribeRankingModelsAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
var it = domain.SubscribeRankingModels(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
const auto It = Domain->SubscribeRankingModels(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeSubscribeRankingModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeSubscribeRankingModels(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: null
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeSubscribeRankingModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeSubscribeRankingModels(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
nullptr // namespaceName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeSubscribeRankingModels(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeSubscribeRankingModels(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### getSubscribeRankingScore
특정 구독 랭킹에 등록한 플레이어의 점수 조회
특정 구독(친구) 랭킹과 시즌의 플레이어 점수를 조회합니다.
특정 친구 랭킹에서 플레이어의 현재 점수를 표시할 때 사용합니다. 예를 들어 친구 랭킹 상세 화면에서 "당신의 점수: 12,000점(이번 주)"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| season | long | | | | 0 ~ 9223372036854775805 | 시즌 |
| gameSession | GameSession | | ✓| | | GameSession |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzSubscribeRankingScore](#ezsubscriberankingscore) | 구독 랭킹 스코어|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
var item = await domain.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
)->SubscribeRankingScore(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).subscribe_ranking_model(
"ranking-0001"
).subscribe_ranking_season(
0,
null
).subscribe_ranking_score(
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
).SubscribeRankingScore(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
)->SubscribeRankingScore(
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).subscribe_ranking_model(
"ranking-0001"
).subscribe_ranking_season(
0,
null
).subscribe_ranking_score(
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### listSubscribeRankingScores
구독 랭킹에 등록한 플레이어의 점수 목록 조회
플레이어가 구독(친구) 랭킹에 등록한 모든 점수를 조회합니다.
친구 랭킹에서 플레이어 자신의 점수를 표시할 때 사용합니다. 예를 들어 친구 랭킹 개요 화면에서 "당신의 친구 하이스코어: 12,000점"과 같이 표시하는 경우에 유용합니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | | | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓| | | GameSession |
| pageToken | string | | | | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 |
| limit | int | | | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| items | [List<EzSubscribeRankingScore>](#ezsubscriberankingscore) | 구독 랭킹 스코어 목록|
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var items = await domain.SubscribeRankingScoresAsync(
).ToListAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var it = domain.SubscribeRankingScores(
);
List items = new List();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
}
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
const auto It = Domain->SubscribeRankingScores(
);
TArray Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}
```
##### 값 변경 이벤트 핸들링
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeSubscribeRankingScores(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeSubscribeRankingScores(callbackId);
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeSubscribeRankingScores(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeSubscribeRankingScores(callbackId);
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeSubscribeRankingScores(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeSubscribeRankingScores(CallbackId);
```
**⚠️ Warning**
이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
---
### putSubscribeRanking
구독 랭킹에 점수 등록
지정한 구독(친구) 랭킹에 플레이어의 점수를 등록합니다. 메타데이터를 첨부할 수도 있습니다.
이 점수는 이 플레이어를 구독(팔로우)하고 있는 모든 사용자의 친구 리더보드에 표시됩니다.
플레이어가 점수 대상 활동을 완료한 후에 사용합니다. 예를 들어 스테이지를 클리어한 후 점수를 "친구 하이스코어" 랭킹에 등록하여 플레이어의 친구가 확인할 수 있도록 하는 경우입니다.
#### Request
| | 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 |
| --- | --- | --- | --- | --- | --- | --- |
| namespaceName | string | | ✓| | ~ 128자 | 네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| rankingName | string | | ✓| | ~ 128자 | 구독 랭킹 모델 이름
구독 랭킹 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
| gameSession | GameSession | | ✓| | | GameSession |
| score | long | | ✓| | 0 ~ 9223372036854775805 | 스코어 |
| metadata | string | | | | ~ 512자 | 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. |
#### Result
| | 타입 | 설명 |
| --- | --- | --- |
| item | [EzSubscribeRankingScore](#ezsubscriberankingscore) | 등록한 구독 랭킹 스코어|
#### 구현 예제
**Unity (UniTask)**
```csharp
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var result = await domain.PutSubscribeRankingAsync(
score: 100L,
metadata: null
);
var item = await result.ModelAsync();
```
**Unity (Vanilla)**
```cs
var domain = gs2.Ranking2.Namespace(
namespaceName: "namespace-0001"
).SubscribeRankingModel(
rankingName: "ranking-0001"
).SubscribeRankingSeason(
season: 0,
userId: "user-0001"
);
var future = domain.PutSubscribeRankingFuture(
score: 100L,
metadata: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result;
```
**Unreal Engine 5**
```cpp
const auto Domain = Gs2->Ranking2->Namespace(
"namespace-0001" // namespaceName
)->SubscribeRankingModel(
"ranking-0001" // rankingName
)->SubscribeRankingSeason(
0, // season
"user-0001" // userId
);
const auto Future = Domain->PutSubscribeRanking(
100L // score
// metadata
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// 변경된 값 / 결과 값을 취득
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();
```
**Godot**
```gdscript
var domain = ez.ranking2.namespace_(
"namespace-0001"
).subscribe_ranking_model(
"ranking-0001"
).subscribe_ranking_season(
0,
null
)
var async_result = await domain.put_subscribe_ranking(
100, # score
null # metadata
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result
```
---