통계 인터페이스(Stats Interface) 는 개발자가 애플리케이션의 사용자 통계 를 관리할 수 있는 기능을 제공하며, 획득한 아이템 수, 플레이어의 최단 레벨 완료 시간, 총 승리 및 패배 수, 플레이어가 특정 동작을 수행한 횟수 등 개발자가 트래킹하고자 하는 통계 데이터를 포함할 수 있습니다. 통계를 활용하여 업적을 언제 잠금해제할지, 그리고 리더보드에서 사용자의 순위를 어떻게 매길지 결정할 수 있습니다.
통계 인터페이스 액세스
통계 인터페이스 함수에 액세스하려면 플랫폼 인터페이스에서 EOS_Platform_GetStatsInterface
함수를 호출하여 EOS_HStats 핸들을 확보해야 합니다. 다른 모든 인터페이스와 마찬가지로 EOS_HPlatform
핸들의 틱이 실행되고 있어야 요청 완료 시 적절한 콜백이 트리거될 수 있습니다.
통계 수집
통계 인터페이스가 사용자 통계와 상호작용하도록 하려면 개발자 포털 에서 게임 통계를 정의해야 합니다. 그리고 EOS_Stats_IngestStat
을 호출하여 애플리케이션 내에 통계를 수집하면, 애플리케이션이 통계를 EOS 백엔드 로 제출합니다.
통계를 수집했다고 해도 제출과 처리에 시간이 걸리므로 백엔드 업데이트가 즉시 완료되지는 않습니다. 마찬가지로, 통계를 사용하는 업적도 잠금해제하는 데 시간이 걸릴 수 있습니다.
EOS_Stats_IngestStat
함수가 수용하는 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
Handle | 유효한 EOS_HStats 핸들입니다. |
Options | 수집하는 통계에 대한 정보가 포함된 EOS_Stats_IngestStatOptions 구조체입니다. |
ClientData | CompletionDelegate 에서 다시 전달되는 임의의 데이터입니다. |
CompletionDelegate | 시그니처가 EOS_Stats_OnIngestStatCompleteCallback 과 일치하는 함수입니다. 통계 수집 연산 완료 시 호출됩니다. |
성공적으로 완료 시 해당 함수는 EOS_Success
값으로 EOS_EResult
를 반환하고, 옵션이 하나라도 부정확하면 EOS_InvalidParameters
를 반환합니다.
통계 수집 옵션
EOS_Stats_IngestStatOptions
구조체의 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
ApiVersion | EOS_STATS_INGESTSTAT_API_LATEST로 설정합니다. |
LocalUserId | 수집되는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다. |
Stats | 수집하려는 통계의 정보를 가진 EOS_Stats_IngestData 구조체의 목록입니다. |
StatsCount | 수집할 통계 개수입니다. |
TargetUserId | 수집할 특정 타깃 사용자 ID입니다. |
데이터 수집
EOS_Stats_IngestData
구조체는 특정 통계에 대한 정보를 포함합니다. 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
ApiVersion | EOS_STATS_INGESTDATA_API_LATEST 로 설정합니다. |
StatName | 수집할 통계의 이름입니다. |
IngestAmount | 통계로 제출할 integer값입니다. |
통계 완료 콜백 정보 수집
연산이 완료되면 EOS_Stats_IngestStat
에 제공된 모든 CompletionDelegate
가 호출됩니다. 이는 EOS_Stats_IngestStatCompleteCallbackInfo
구조체를 반환하는데, 그 구조체의 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
ResultCode | 성공적으로 요청됐으면 EOS_Success 값의 EOS_EResult 입니다. 다른 코드는 전부 오류를 의미합니다. |
ClientData | 자체 ClientData 파라미터를 사용하여 EOS_Stats_IngestStat 에 전달되는 컨텍스트입니다. |
UserId | 수집하는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다. |
통계 쿼리
EOS_Stats_QueryStats
함수로 EOS 백엔드로부터 사용자 통계 목록을 요청할 수 있습니다. 연산이 완료되면 통계는 함수 자체를 통해 반환되지 않고 로컬에서 캐싱됩니다. 자세한 내용은 통계 복사 섹션을 참조하세요.
EOS_Stats_QueryStats
함수는 다음과 같은 파라미터를 수용합니다.
파라미터 | 설명 |
---|---|
Handle | 유효한 EOS_HStats 핸들입니다. |
Options | 회수하는 통계를 소유한 플레이어에 대한 정보가 포함된 EOS_Stats_QueryStatsOptions 구조체입니다. |
ClientData | CompletionDelegate 에서 다시 전달되는 임의의 데이터입니다. |
CompletionDelegate | 시그니처가 EOS_Stats_OnQueryStatsCompleteCallback 과 일치하는 함수입니다. 통계 수집 연산 완료 시 호출됩니다. |
쿼리 통계 옵션
EOS_Stats_QueryStatsOptions
구조체에는 쿼리 대상인 사용자에 대한 정보 및 얻을 통계의 범위를 좁힐 수 있는 추가 파라미터가 포함됩니다. 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
ApiVersion | EOS_STATS_QUERYSTATS_API_LATEST 로 설정합니다. |
UserId | 얻어 오는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다. |
StartTime (선택 사항) | EOS_STATS_TIME_UNDEFINED 가 아니면 시작 시간의 POSIX 타임 스탬프입니다. |
EndTime (선택 사항) | EOS_STATS_TIME_UNDEFINED 가 아니면 종료 시간의 POSIX 타임 스탬프입니다. |
StatNames (선택 사항) | 쿼리할 특정 통계 이름 목록입니다. |
StatNamesCount (선택 사항) | StatNames 에 나열된 이름의 개수입니다. |
StartTime
과 EndTime
파라미터가 설정되면 쿼리는 주어진 시작 및 종료 시간으로 제한됩니다.
통계 쿼리 완료 시 콜백 정보
연산이 완료되면 EOS_Stats_QueryStats
에 제공된 모든 CompletionDelegate
가 호출됩니다. 이는 파라미터가 다음과 같은 EOS_Stats_OnQueryStatsCompleteCallbackInfo
구조체를 반환합니다.
파라미터 | 설명 |
---|---|
ResultCode | 성공적으로 요청됐으면 EOS_Success 값의 EOS_EResult 입니다. 다른 코드는 전부 오류를 의미합니다. |
ClientData | 자체 ClientData 파라미터를 사용하여 EOS_Stats_QueryStats 에 전달되는 컨텍스트입니다. |
UserId | 수집하는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다. |
통계 복사
EOS_Stats_QueryStats
가 연산에 성공하면 요청된 통계는 로컬 캐싱됩니다. 이후 EOS_Stats_CopyStatByIndex
또는 EOS_Stats_CopyStatByName
으로 로컬 캐시에서 주어진 통계의 사본을 얻을 수 있습니다.
EOS 통계 구조체
통계 정보를 복사하여 EOS_Stats_Stat
구조체를 반환하게 하기 위한 함수입니다. 이 구조체는 하나의 특정 플레이어 통계에 대한 정보입니다. 프로퍼티는 다음과 같습니다.
프로퍼티 | 설명 |
---|---|
ApiVersion | EOS_STATS_STAT_API_LATEST 로 설정합니다. |
Name | 개발자 포털에 표시되는 통계 이름입니다. |
StartTime | EOS_STATS_TIME_UNDEFINED 가 아니면 이 통계를 반환한 쿼리의 시작 시간 POSIX 타임 스탬프입니다. |
EndTime | EOS_STATS_TIME_UNDEFINED 가 아니면 이 통계를 반환한 쿼리의 종료 시간 POSIX 타임 스탬프입니다. |
Value | 통계의 현재 값으로, integer 형식입니다. |
통계 개수 획득
성공적으로 플레이어 통계를 쿼리하고 나면 EOS_Stats_GetStatsCount
를 사용하여 로컬 캐싱된 통계의 개수를 확인할 수 있습니다. 이 함수는 다음과 같은 파라미터를 받습니다.
파라미터 | 설명 |
---|---|
Handle | 유효한 EOS_HStats 핸들입니다. |
Options | EOS_STATS_GETSTATCOUNT_API_LATEST 값으로 설정된 ApiVersion 과 회수하는 통계 개수를 소유한 사용자의 유효한 EOS_ProductUserId 로 설정된 UserId 로 이루어진 EOS_Stats_GetStatCountOptions 구조체입니다. |
이 함수가 반환하는 integer는 현재 캐싱된 통계 개수를 나타냅니다.
인덱스로 통계 복사
EOS_Stats_CopyStatByIndex
함수는 캐싱된 통계 목록에서 주어진 인덱스를 기반으로 통계 사본을 가져옵니다. 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
Handle | 유효한 EOS_HStats 핸들입니다. |
Options | EOS_Stats_CopyStatByIndexOptions 구조체는 통계를 가져오기 위한 캐시 내 목표 인덱스를 가지고 있습니다. |
OutStat | 원하는 통계 정보를 가진 타입 EOS_Stats_Stat 의 아웃 파라미터입니다. 종료 시 EOS_Stats_Stat_Release 를 사용합니다. |
연산 완료 시 아웃 파라미터 OutStat
을 사용하여 원하는 EOS_Stats_Stat
을 출력합니다. 해당 함수의 반환값은 EOS_EResult
입니다. 정보를 이용할 수 있고 OutStat
을 통해 성공적으로 전달되면 EOS_Success
값을 가지게 됩니다. 파라미터가 하나라도 유효하지 않거나 아웃 파라미터로 null 포인터가 제공되면 EOS_InvalidParameters
값을 가지게 됩니다. 요청한 통계를 찾을 수 없으면 EOS_NotFound
값을 가지게 됩니다.
인덱스로 통계 복사 옵션
EOS_Stats_CopyStatByIndexOptions
구조체는 EOS_Stats_CopyStatByIndex
의 요청된 통계 인덱스를 가집니다. 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
ApiVersion | EOS_STATS_COPYSTATBYINDEX_API_LATEST 로 설정합니다. |
UserId | 사본을 얻는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다. |
StatIndex | 캐싱된 통계 목록 내 인덱스를 나타내는 integer입니다. |
이름으로 통계 복사
EOS_Stats_CopyStatByName
함수는 개발자 포털에서 주어진 통계 이름을 기반으로 통계의 사본을 가져옵니다. 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
Handle | 유효한 EOS_HStats 핸들입니다. |
Options | EOS_Stats_CopyStatByNameOptions 구조체는 캐시에서 가져올 통계의 이름을 가지고 있습니다. |
OutStat | 원하는 통계 정보를 가진 타입 EOS_Stats_Stat 의 아웃 파라미터입니다. 종료 시 EOS_Stats_Stat_Release 를 사용합니다. |
연산 완료 시 아웃 파라미터 OutStat
을 사용하여 원하는 EOS_Stats_Stat
을 출력합니다. 해당 함수의 반환값은 EOS_EResult
입니다. 정보를 이용할 수 있고 OutStat
을 통해 성공적으로 전달되면 EOS_Success
값을 가지게 됩니다. 파라미터가 하나라도 유효하지 않거나 아웃 파라미터로 null 포인터가 제공되면 EOS_InvalidParameters
값을 가지게 됩니다. 요청한 통계를 찾을 수 없으면 EOS_NotFound
값을 가지게 됩니다.
이름으로 통계 복사 옵션
EOS_Stats_CopyStatByNameOptions
구조체는 EOS_Stats_CopyStatByName
의 요청된 통계 인덱스를 가집니다. 파라미터는 다음과 같습니다.
파라미터 | 설명 |
---|---|
ApiVersion | EOS_STATS_COPYSTATBYNAME_API_LATEST 로 설정합니다. |
UserId | 사본을 얻는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다. |
StatName | 사본을 가져올 통계의 이름입니다. |
캐싱된 통계에서 메모리 해제
EOS_Stats_CopyStatByIndex
로 통계 데이터를 회수하고 나면 EOS_Stats_Stat_Release
를 호출하여 해당 통계 관련 메모리를 해제해야 합니다. 이 함수는 EOS_Stats_CopyStatByName
또는 EOS_Stats_CopyStatByIndex
의 OutStat
파라미터로 EOS_Stats_Stat
구조체 출력을 수용합니다.
사용 제한
통계 인터페이스는 애플리케이션의 사용자 통계를 관리하며 획득한 아이템 수, 플레이어의 최단 레벨 완료 시간, 총 승리 및 패배 수, 플레이어가 특정 동작을 수행한 횟수 등 개발자가 트래킹하고자 하는 통계 데이터를 포함할 수 있습니다. 통계를 활용하여 업적을 언제 잠금해제할지, 그리고 리더보드에서 사용자의 순위를 어떻게 매길지 결정할 수 있습니다. 스로틀링, 사용 할당량, 모범 사례에 대한 일반적인 정보는 서비스 사용 제한을 참고하세요.
전체 통계 시스템에 다음 제한이 적용됩니다.
기능 | 제한 |
---|---|
통계 개수 | 디플로이(Deployment)당 500개 |
통계 이름 길이 | 256자 |
호출당 수집되는 최대 통계 | 3,000개 |
최대 마일스톤(디폴트) | 100개 |
통계 수집은 통계 변경을 서비스로 제출할 때의 엔드포인트이며, 사용자별 사용률 제한이 있습니다. 전용 서버가 사용자 대신 통계를 제출할 때는 사용자별 제한이 적용되지 않습니다. 이 경우 제한은 당시의 디플로이별 동시 사용자(CCU) 수를 베이스로 합니다.
사용 타입 | 사용자별 제한 | 디플로이(Deployment)별 제한 |
---|---|---|
통계 수집 | 분당 요청 60회, 요청별 통계 500건 | 분당 5개의 CCU당 요청 1회 |
플레이어 ID로 통계 구하기 | 분당 요청 100회 | - |
플레이어 ID로 통계 구하기 | 분당 요청 100회, 요청당 플레이어 64명, 플레이어별 통계 25건 | - |
통계 생성 | - | 분당 요청 100회 |
통계 삭제 | - | 분당 요청 100회 |
업적 및 통계 테스트
업적을 테스트 샌드박스에서 테스트하려면 해당 샌드박스에 대한 디플로이에도 통계가 포함되어야 합니다. 업적을 라이브 환경에 디플로이하기 전에 테스트를 진행하여 통계 구조에서 발생할 수 있는 오류를 점검하고, 플레이어가 업적을 성공적으로 잠금해제하도록 지원해야 합니다.
제품 의 테스트 샌드박스 생성에 관한 정보는 제품, 샌드박스, 디플로이 ID의 문서를 참고하세요.