Stats Interface

통계 관리를 위한 인터페이스입니다.

15 분 소요

통계 인터페이스(Stats Interface) 는 개발자가 애플리케이션의 사용자 통계 를 관리할 수 있는 기능을 제공하며, 획득한 아이템 수, 플레이어의 최단 레벨 완료 시간, 총 승리 및 패배 수, 플레이어가 특정 동작을 수행한 횟수 등 개발자가 트래킹하고자 하는 통계 데이터를 포함할 수 있습니다. 통계를 활용하여 업적을 언제 잠금해제할지, 그리고 리더보드에서 사용자의 순위를 어떻게 매길지 결정할 수 있습니다.

통계 인터페이스 액세스

통계 인터페이스 함수에 액세스하려면 플랫폼 인터페이스에서 EOS_Platform_GetStatsInterface 함수를 호출하여 EOS_HStats 핸들을 확보해야 합니다. 다른 모든 인터페이스와 마찬가지로 EOS_HPlatform 핸들의 틱이 실행되고 있어야 요청 완료 시 적절한 콜백이 트리거될 수 있습니다.

통계 수집

통계 인터페이스가 사용자 통계와 상호작용하도록 하려면 개발자 포털 에서 게임 통계를 정의해야 합니다. 그리고 EOS_Stats_IngestStat 을 호출하여 애플리케이션 내에 통계를 수집하면, 애플리케이션이 통계를 EOS 백엔드 로 제출합니다.

통계를 수집했다고 해도 제출과 처리에 시간이 걸리므로 백엔드 업데이트가 즉시 완료되지는 않습니다. 마찬가지로, 통계를 사용하는 업적도 잠금해제하는 데 시간이 걸릴 수 있습니다.

EOS_Stats_IngestStat 함수가 수용하는 파라미터는 다음과 같습니다.

파라미터설명
Handle유효한 EOS_HStats 핸들입니다.
Options수집하는 통계에 대한 정보가 포함된 EOS_Stats_IngestStatOptions 구조체입니다.
ClientDataCompletionDelegate 에서 다시 전달되는 임의의 데이터입니다.
CompletionDelegate시그니처가 EOS_Stats_OnIngestStatCompleteCallback 과 일치하는 함수입니다. 통계 수집 연산 완료 시 호출됩니다.

성공적으로 완료 시 해당 함수는 EOS_Success 값으로 EOS_EResult 를 반환하고, 옵션이 하나라도 부정확하면 EOS_InvalidParameters 를 반환합니다.

통계 수집 옵션

EOS_Stats_IngestStatOptions 구조체의 파라미터는 다음과 같습니다.

파라미터설명
ApiVersionEOS_STATS_INGESTSTAT_API_LATEST로 설정합니다.
LocalUserId수집되는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다.
Stats수집하려는 통계의 정보를 가진 EOS_Stats_IngestData 구조체의 목록입니다.
StatsCount수집할 통계 개수입니다.
TargetUserId수집할 특정 타깃 사용자 ID입니다.

데이터 수집

EOS_Stats_IngestData 구조체는 특정 통계에 대한 정보를 포함합니다. 파라미터는 다음과 같습니다.

파라미터설명
ApiVersionEOS_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 구조체입니다.
ClientDataCompletionDelegate 에서 다시 전달되는 임의의 데이터입니다.
CompletionDelegate시그니처가 EOS_Stats_OnQueryStatsCompleteCallback 과 일치하는 함수입니다. 통계 수집 연산 완료 시 호출됩니다.

쿼리 통계 옵션

EOS_Stats_QueryStatsOptions 구조체에는 쿼리 대상인 사용자에 대한 정보 및 얻을 통계의 범위를 좁힐 수 있는 추가 파라미터가 포함됩니다. 파라미터는 다음과 같습니다.

파라미터설명
ApiVersionEOS_STATS_QUERYSTATS_API_LATEST 로 설정합니다.
UserId얻어 오는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다.
StartTime (선택 사항)EOS_STATS_TIME_UNDEFINED 가 아니면 시작 시간의 POSIX 타임 스탬프입니다.
EndTime (선택 사항)EOS_STATS_TIME_UNDEFINED 가 아니면 종료 시간의 POSIX 타임 스탬프입니다.
StatNames (선택 사항)쿼리할 특정 통계 이름 목록입니다.
StatNamesCount (선택 사항)StatNames 에 나열된 이름의 개수입니다.

StartTimeEndTime 파라미터가 설정되면 쿼리는 주어진 시작 및 종료 시간으로 제한됩니다.

통계 쿼리 완료 시 콜백 정보

연산이 완료되면 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 구조체를 반환하게 하기 위한 함수입니다. 이 구조체는 하나의 특정 플레이어 통계에 대한 정보입니다. 프로퍼티는 다음과 같습니다.

프로퍼티설명
ApiVersionEOS_STATS_STAT_API_LATEST 로 설정합니다.
Name개발자 포털에 표시되는 통계 이름입니다.
StartTimeEOS_STATS_TIME_UNDEFINED 가 아니면 이 통계를 반환한 쿼리의 시작 시간 POSIX 타임 스탬프입니다.
EndTimeEOS_STATS_TIME_UNDEFINED 가 아니면 이 통계를 반환한 쿼리의 종료 시간 POSIX 타임 스탬프입니다.
Value통계의 현재 값으로, integer 형식입니다.

통계 개수 획득

성공적으로 플레이어 통계를 쿼리하고 나면 EOS_Stats_GetStatsCount 를 사용하여 로컬 캐싱된 통계의 개수를 확인할 수 있습니다. 이 함수는 다음과 같은 파라미터를 받습니다.

파라미터설명
Handle유효한 EOS_HStats 핸들입니다.
OptionsEOS_STATS_GETSTATCOUNT_API_LATEST 값으로 설정된 ApiVersion 과 회수하는 통계 개수를 소유한 사용자의 유효한 EOS_ProductUserId 로 설정된 UserId 로 이루어진 EOS_Stats_GetStatCountOptions 구조체입니다.

이 함수가 반환하는 integer는 현재 캐싱된 통계 개수를 나타냅니다.

인덱스로 통계 복사

EOS_Stats_CopyStatByIndex 함수는 캐싱된 통계 목록에서 주어진 인덱스를 기반으로 통계 사본을 가져옵니다. 파라미터는 다음과 같습니다.

파라미터설명
Handle유효한 EOS_HStats 핸들입니다.
OptionsEOS_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 의 요청된 통계 인덱스를 가집니다. 파라미터는 다음과 같습니다.

파라미터설명
ApiVersionEOS_STATS_COPYSTATBYINDEX_API_LATEST 로 설정합니다.
UserId사본을 얻는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다.
StatIndex캐싱된 통계 목록 내 인덱스를 나타내는 integer입니다.

이름으로 통계 복사

EOS_Stats_CopyStatByName 함수는 개발자 포털에서 주어진 통계 이름을 기반으로 통계의 사본을 가져옵니다. 파라미터는 다음과 같습니다.

파라미터설명
Handle유효한 EOS_HStats 핸들입니다.
OptionsEOS_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 의 요청된 통계 인덱스를 가집니다. 파라미터는 다음과 같습니다.

파라미터설명
ApiVersionEOS_STATS_COPYSTATBYNAME_API_LATEST 로 설정합니다.
UserId사본을 얻는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 EOS_ProductUserId 입니다.
StatName사본을 가져올 통계의 이름입니다.

캐싱된 통계에서 메모리 해제

EOS_Stats_CopyStatByIndex 로 통계 데이터를 회수하고 나면 EOS_Stats_Stat_Release 를 호출하여 해당 통계 관련 메모리를 해제해야 합니다. 이 함수는 EOS_Stats_CopyStatByName 또는 EOS_Stats_CopyStatByIndexOutStat 파라미터로 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의 문서를 참고하세요.