Skip to main content
XBOX 서비스 리더보드는 사용자 통계에서 파생되며 쿼리로 구축됩니다. 이는 API로 업로드되는 “점수”가 주도하는 Steam의 리더보드와 다릅니다. 업적과 마찬가지로 XBOX Game Development Kit(GDK)에는 통계에 대한 두 개의 API가 있습니다: 이벤트 기반과 타이틀 관리. 업적과는 달리 이벤트 기반 통계 및 리더보드를 타이틀 관리보다 우선 사용하는 것을 권장합니다. 이 항목에서는 그 API에 초점을 맞춥니다. 이 두 API가 어떻게 다른지에 대한 자세한 내용은 이벤트 기반 vs. 타이틀 관리 통계를 참조하세요. 두 플랫폼 모두 자체 포털에서 리더보드를 정의합니다. 차이점은 XBOX 서비스는 먼저 Partner Center에서 통계 규칙을 정의한 다음, 그 규칙이 주도하는 통계를 기반으로 리더보드를 구축하게 한다는 점입니다. 반면 Steam은 둘을 구분하지 않습니다. 포털이나 프로그래밍 방식으로 리더보드를 생성한 다음 해당 리더보드에 직접 사용자 점수를 업로드합니다. Steam Leaderboard API와 비교해 이러한 API가 어떻게 사용될 수 있는지 보여주기 위해, Steam SDK와 이벤트 기반 XBOX Game Development Kit(GDK) 통계 플랫폼에서 가장 멀리 이동한 거리에 대한 리더보드(예시는 Steamworks API 문서에서 가져옴)를 만드는 방법에 대한 코드 예시를 제공합니다. 다음 섹션에서 로직을 설명합니다.

포털에서 통계/리더보드 생성

Steamworks

Steamworks 관리자 포털에서 Stats & Achievements > Leaderboards로 이동합니다. 다음 스크린샷(Steamworks 문서에서)과 같이 양식을 완성합니다.

XBOX Game Development Kit(GDK)(이벤트 기반)

Partner Center에서 게임으로 이동한 뒤 XBOX services > Gameplay settings를 선택합니다. 오른쪽 창의 탐색 표시줄에서 Player Stats > Stat Rules를 선택하고, 통계의 요구 사항을 충족하도록 구성해 Show로 통계 규칙을 추가합니다. 통계 업데이트에는 마지막 업데이트 이후 플레이어(사용자)가 이동한 거리의 계산된 값이 포함되므로, 서비스가 이 값을 얻을 측정 필드를 지정합니다.
이벤트를 업데이트할 데이터를 이벤트의 Measurements 또는 Dimensions 필드에 저장하는 것 사이에 기능적 차이는 없습니다. 두 필드는 Application Insights와 함께 사용하기 위해 존재합니다. 자세한 내용은 [Application Insights API for custom events and
metrics](https://learn.microsoft.com/en-us/azure/azure-monitor/app/api-custom-events-metrics)를 참조하세요. 다음 스크린샷은 Partner Center에서 통계 규칙을 생성하는 데 사용되는 양식을 보여줍니다. 저장한 후 오른쪽 창 상단의 Leaderboard를 선택하고 다음 스크린샷과 같이 방금 생성한 통계로 주도되는 새 리더보드를 생성합니다.

점수 업로드

Steamworks

Steamworks에서는 이동한 새 총 피트 값을 계산하고 ISteamUserStats::UploaderLeaderboardScore 메서드로 API에 전송해야 합니다.

XBOX Game Development Kit(GDK)(이벤트 기반)

XBOX Game Development Kit(GDK)의 이벤트 기반 통계에서는 이벤트 수신 시 이 통계를 증가시키기를 원한다고 지정했고 이 diff 값을 어디서 찾을지 measurements JSON 문자열에서 지정했으므로, 다음과 같이 이동한 피트의 차이를 XblEventsWriteInGameEvent에 전달하기만 하면 됩니다.
자세한 내용은 이벤트 기반 통계를 구동하는 이벤트 작성을 참조하세요.

글로벌 리더보드 가져오기

글로벌 리더보드는 Steamworks SDK로 ISteamUserStats::GetLeaderboardEntries를 호출한 뒤, 각 항목 또는 리더보드의 “행”을 얻기 위해 callback 함수에서 ISteamUserStats::GetDownloadedLeaderboardEntry를 호출해 가져올 수 있습니다.

Steamworks

XBOX Game Development Kit(GDK)(이벤트 기반)

XBOX Game Development Kit(GDK) API는 유사한 패턴을 따릅니다. 원하는 리더보드, 범위, 정렬 방법, 포함할 추가 필드(있는 경우) 등을 지정하는 쿼리를 만듭니다. 쿼리로 XblLeaderboardGetLeaderboardAsync를 호출한 후, 다음 코드 예시와 같이 XblLeaderboardGetLeaderboardResultSizeXblLeaderboardGetLeaderboardResult를 사용해 결과를 지정된 버퍼에 넣고 반복할 수 있습니다.
자세한 내용은 다음을 참조하세요.

소셜 리더보드 가져오기

Steamworks에서는 ELeaderboardDataRequest::k_ELeaderboardDataRequestFriends 열거형을 사용해 리더보드를 현재 사용자의 친구로 범위화할 수 있습니다. XBOX Game Development Kit(GDK)에서는 이를 _소셜 리더보드_라고 합니다. XBOX 서비스에서 소셜 리더보드를 가져오려면 XblLeaderboardQuery 구조체에서 xboxIUserId를 XBOX 서비스에 로그인된 현재 사용자의 XBOX User ID(XUID)와 같게 설정하고, leaderboardNamenullptr로, socialGroupXblSocialGroupType::People 또는 XblSocialGroupType::Favorites로 설정하세요. 앞서 표시한 대로 XblLeaderboardGetLeaderboardAsync를 호출합니다. 자세한 내용은 XblSocialGroupType을 참조하세요. Steam과 유사한 리더보드를 생성하는 데 사용되는 일반 사용자 통계 외에도, XBOX 서비스에는 Featured Stats 라는 추가 개념이 있습니다. Featured Stats는 여러분의 게임에 대해 XBOX 생태계의 다양한 표면에 나타나며, 이미 생성된 사용자의 통계나 리더보드 값을 보여줄 수 있습니다. 게임당 최대 20개의 Featured Stats를 생성할 수 있습니다. Featured Stats와 이를 추가하는 방법에 대한 자세한 내용은 Featured Stats 개요이벤트 기반 Featured Stats의 포털 구성을 참조하세요.

속도 제한

이벤트를 작성할 때 XBOX Services API(XSAPI)를 너무 자주 호출하지 않도록 주의하세요. 그렇지 않으면 게임이 속도 제한에 걸릴 수 있습니다. 이는 예기치 못한 동작과 사용자에게 좋지 않은 경험을 초래할 수 있습니다. 이는 Steam에서는 문제가 아닌 XBOX 서비스의 우려 사항입니다. Steam에서 통계 값을 작성하는 것은 게임이 명시적으로 동기화하기 전까지 서버로의 API 호출을 발생시키지 않습니다. 자주 발생하는 이벤트의 경우, API 호출을 특정 개수의 이벤트가 발생한 후 발행하거나 특정 시간 간격으로 서버에서 업데이트하도록 배치화해 보세요. XBOX Live Trace Analyzer(XblTraceAnalyzer.exe)를 사용해 API 호출을 디버깅할 수 있습니다. XBOX 서비스에서의 속도 제한에 대한 자세한 내용은 세밀한 속도 제한을 참조하세요.
마지막 수정일 2026년 8월 24일