리더보드의 집계 기간 및 정산 시간 확인 방법 문의

고객님의 문의에 답변하는 직원은 고객 여러분의 가족 중 한 사람일 수 있습니다.
고객의 언어폭력(비하, 조롱, 욕설, 협박, 성희롱 등)으로부터 직원을 보호하기 위해
관련 법에 따라 수사기관에 필요한 조치를 요구할 수 있으며, 형법에 의해 처벌 대상이 될 수 있습니다.

커뮤니티 이용 정책에 위배되는 게시물을 작성할 경우, 별도 안내 없이 게시물 삭제 또는 커뮤니티 이용이 제한될 수 있습니다.

문의 응대 : 평일 오전 10시 ~ 오후 6시
문의를 남기실 경우 다음 항목을 작성해 주세요.
정보가 부족하거나 응대시간 외 문의하는 경우 확인 및 답변이 지연될 수 있습니다.

  • 베이스/채팅/데이터베이스/월드 SDK 버전 : 5.18.12
  • 프로젝트명 : MSR_GLOBAL
  • 스테이터스 코드 :
  • 에러 코드 :
  • 에러 메시지 :
    뒤끝 개발팀을 통한 별도의 기술지원이 작업이 필요한 요청은 help@backnd.com 으로 문의해주시기 바랍니다.

안녕하세요.
리더보드의 집계 기간 및 정산 시간, 정산 진행 여부를 인게임 내에서 확인하는 방법​ 에 대해 문의드립니다.

현재 인게임에서 플레이어에게 리더보드의 현재 집계 기간(시작일 ~ 종료일)​ 을 표시하려고 합니다.

뒤끝에서 제공하는 리더보드 정보 중 rankStartDateAndTime , rankEndDateAndTime 필드를 통해 집계 기간을 확인할 수 있는 것으로 보이나, 해당 필드는 특정 기간 동안만 운영되는 일회성 리더보드의 집계 기간 을 나타내는 것으로 알고 있습니다.

반면 콘솔에서 리더보드의 집계 주기를 매일 / 매주 / 매월(N개월) 등으로 설정한 경우에는, 해당 설정값을 기준으로 ​현재 집계 기간의 시작일과 종료일을 계산하거나 가져올 수 있는 방법이 확인되지 않습니다.

GetLeaderboards

{
    "rows": [
        {
            "rankType": "user", // 리더보드 타입(user / guild)
            "isDivision": true, // 그룹 구분 여부
            "rewardInDate": "2024-07-30T04:52:13.448Z",
            "order": "desc", // 정렬 순서
            "initializationTime": "04:00:00 UTC+9:00", // 리더보드 초기화 시간
            "rankStartDateAndTime": "2024-08-19T15:40:00.000Z", // (일회성, 기한없음 리더보드에서만) 리더보드 시작 시간
            "rankEndDateAndTime": "2024-08-20T15:00:00.000Z", // (일회성 리더보드에서만) 리더보드 종료 시간
            // 랭킹 기간
            // day : 일간
            // week : 주간
            // month : 월간
            // infinity : 누적 랭킹
            // custom : 일회성 랭킹
            "date": "custom", // 
            "inDate": "2024-08-20T07:08:09.478Z", // 리더보드 생성 일시
            "uuid": "01916e9d-5186-7594-b8ab-e286cefb6226",
            "extraDataColumn": "추가 항목 컬럼 이름", // (추가항목 선택시에만) 추가항목 컬럼이름
            "extraDataType": "S", // (추가항목 선택시에만) 추가항목 컬럼 데이터 타입
            "isReset": true, // 초기화 시 데이터 리셋 여부
            // 언어별 보상 이름
            "rewardPostTitle": {
                "ko": "한국보상",
                "en": "EnglishReward",
                "fallback": "en"
            },
            "rewardName": "보상 차트 이름",
            "title": "랭킹 제목",
            "table": "랭킹에 사용된 테이블 이름",
            "column": "랭킹에 사용된 컬럼 이름"
        },
    ]
}

따라서 아래 사항에 대해 문의드립니다.

  1. 매일 / 매주 / 매월(N개월)로 설정된 리더보드의 현재 집계 기간(시작일 ~ 종료일)을 출력하기 위한 방법
  2. 현재 리더보드가 정산 진행 중인지 여부를 확인할 수 있는 방법이 있는지
  3. 정산이 시작되는 정확한 시점과 정산이 완료되는 시점 이 입력해둔 값의 +1시간으로 고정인지

이에 해당 정보를 확인할 수 있는 API나 권장 구현 방법이 있다면 안내 부탁드립니다.

감사합니다.

안녕하세요 개발자님,
리더보드의 개선에 따라 GetReturnValuetoJSON 및 LeaderboardTableItem도 일부 변경이 이루어졌으나 개발자문서 내 반영이 이루어지지 않아 혼동 드린 점 죄송합니다.

개선 변경된 값은 다음과 같습니다.

GetReturnValuetoJSON

{
    "rows": [
        {
            "rankType": "user", // 리더보드 타입(user / guild)
            "isDivision": true, // 그룹 구분 여부
            "isDatabase": false, // 집계 대상이 게임 정보 테이블이 아닌 데이터베이스 테이블인지 여부
            "order": "desc", // 정렬 순서

            // 리더보드 주기
            // day      : 일간
            // week     : 주간
            // month    : 1개월
            // 2months ~ 6months : 2~6개월
            // infinity : 누적 리더보드
            // custom   : 일회성 리더보드
            "date": "3months",

            "initializationTime": "02:00:00 UTC+09:00", // 초기화 시각

            // 주간 리더보드의 초기화 요일 (0: 일요일 ~ 6: 토요일)
            // 주간 외 주기에서는 기본값(1)이 반환되며 의미 없음
            "initializationDay": 1,

            // 1~6개월 리더보드의 초기화 일자
            // 숫자(해당 일자) 또는 "end"(말일) — 타입이 달라지므로 파싱 시 주의
            // 일간 / 주간 주기에서는 기본값(1)이 반환되며 의미 없음
            "initializationDate": 15,

            // 일회성 리더보드  : 실제 집계 시작 / 종료 시간
            // 2~6개월 리더보드   : 현재 회차의 기준 월 (해당 월 1일 00:00 UTC 고정)
            //               초기화 일자가 해당 월에 아직 도래하지 않은 경우 직전 월이 반환됨
            //               초기화 일자·시각이 반영되지 않으므로 집계 기간 표시에 그대로 사용 불가
            // 일간/주간/1개월 : 반환되지 않음
            "rankStartDateAndTime": "2026-09-01T00:00:00.000Z",
            "rankEndDateAndTime": "2026-12-01T00:00:00.000Z",

            "inDate": "2024-08-20T07:08:09.478Z", // 리더보드 생성 일시
            "uuid": "01916e9d-5186-7594-b8ab-e286cefb6226",

            "extraDataColumn": "추가 항목 컬럼 이름", // (추가항목 선택시에만)
            "extraDataType": "S", // (추가항목 선택시에만) 데이터 타입
            "isReset": true, // 초기화 시 데이터 리셋 여부

            "rewardName": "보상 차트 이름",
            "rewardInDate": "2024-07-30T04:52:13.448Z", // 보상 차트의 inDate
            "rewardPostTitle": { // 언어별 보상 우편 제목
                "ko": "한국보상",
                "en": "EnglishReward",
                "fallback": "en"
            },

            "title": "리더보드 제목",
            "table": "리더보드에 사용된 테이블 이름",
            "column": "리더보드에 사용된 컬럼 이름"
        },
        ...
    ]
}

// 아래 필드는 JSON 응답에는 포함되지만 LeaderboardTableItem에는 포함되어 있지 않습니다.
// 해당 값이 필요한 경우 GetReturnValuetoJSON()으로 직접 파싱해 주세요.
// initializationDay, initializationDate, inDate, rewardName, rewardInDate, isDatabase

LeaderboardTableItem

public class LeaderboardTableItem
{
    public string rankType;
    public string date;
    public bool isDivision;
    public string uuid;
    public string order;
    public string initializationTime;
    public bool isReset;
    public string title;
    public string table;
    public string column;

    // 일회성 리더보드에만 값이 존재
    // 2~6개월 주기 리더보드는 JSON 응답에는 포함되나 현재 해당 필드에 담기지 않음 (1개월 주기 리더보드는 JSON에서도 미제공)
    public string rankStartDateAndTime;
    public string rankEndDateAndTime;

    //추가 항목이 있을 경우에만 존재
    public string extraDataColumn;
    public string extraDataType;

    public Dictionary<string, string> rewardPostTitle = null;
}

위 변경 정보는 빠른 시일 내 개발자 문서에 반영토록 하겠습니다.



문의해주신 내용 순차적으로 답변드립니다.

1. 매일 / 매주 / 매월(N개월) 리더보드의 현재 집계 기간 확인 방법

현재 집계 기간을 그대로 반환하는 값은 제공되지 않으며, 위 응답값을 조합해 산출해 주셔야 합니다.

주기 사용할 값
day initializationTime
week initializationDay + initializationTime
month(1개월) initializationDate + initializationTime
2~6months(2~6개월) rankStartDateAndTime의 연·월을 회차 기준으로 삼고, initializationDate + initializationTime 적용

rankStartDateAndTime / rankEndDateAndTime은 일회성 리더보드 외에 2~6개월 리더보드에도 반환되나, 이 경우 현재 회차의 기준 월만을 나타내며 초기화 일자·시각이 반영되지 않습니다.

또한 이 값은 리더보드 생성 시점이 아닌 직전 초기화 경계를 기준으로 하므로, 설정하신 초기화 일자가 해당 월에 아직 도래하지 않은 경우 직전 월이 반환됩니다.

예) 9월 22일에 생성한 2개월 주기 / 말일 / 02:00 KST
→ 9월 말일이 아직 도래하지 않아 rankStartDateAndTime은 2026-08-01로 반환
→ 실제 현재 집계 기간은 2026-08-31 02:00 ~ 2026-10-31 02:00 (KST)

예) 3개월 주기 / 매월 15일 / 02:00 KST 리더보드, rankStartDateAndTime이 2026-09-01인 경우
→ 현재 집계 기간은 2026-09-15 02:00 ~ 2026-12-15 02:00 (KST)

2~6개월 주기의 경우 산출에 필요한 initializationDay, initializationDate가 현재 LeaderboardTableItem에 포함되어 있지 않으므로, GetReturnValuetoJSON()으로 직접 파싱해 주셔야 합니다.(매일/매주/1개월은 JSON에도 미제공)
initializationDate는 숫자 또는 "end"(말일)로 타입이 달라지는 점도 함께 참고 부탁드립니다.


2. 정산 진행 중 여부 확인

정산 상태를 직접 조회하는 별도 API는 제공하지 않습니다.
다만 정산 구간은 3번 답변과 같이 1시간으로 고정되어 있으므로, 1번에서 산출한 집계 종료 시각을 기준으로 해당 구간을 미리 판단하실 수 있습니다.

이 구간에는 리더보드 관련 UI 전체를 비활성화하고 "리더보드 정산 중입니다"와 같은 안내를 노출하는 방식을 권장드립니다. 불필요한 호출을 줄일 수 있고, 유저에게도 상태가 명확하게 전달됩니다.

다만 클라이언트 시간 오차 등으로 정산 구간에 호출이 발생할 수 있으므로, 예외 처리로 아래 응답에 대한 처리를 함께 구현해 주시기 바랍니다.

statusCode : 428
errorCode  : Precondition Required
message    : Precondition Required ranking is being counted

해당 응답은 리더보드 갱신(점수 등록) 호출에 한해 반환되며, 순위 조회 호출에서는 반환되지 않습니다.
정산 중 여부를 순위 조회 결과로 판별하실 수는 없으며, 조회 UI 통제 역시 위의 시간 기준으로 처리해 주셔야 합니다.


3. 정산 시작·완료 시점

설정하신 초기화 시각부터 1시간이 정산 구간으로 고정됩니다.
데이터 규모에 따라 실제 처리는 1시간 이전에 완료되나, 서버는 해당 1시간 동안 정산 상태를 유지하며 이 구간 중 갱신 시도 시 위 428 응답이 반환됩니다.
정산 구간 전체를 정산 중으로 간주하여 구현해 주시면 됩니다.