Stats Interface

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

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

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

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

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

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

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

연산이 완료되면 EOS_Stats_IngestStat 에 제공된 모든 CompletionDelegate 가 호출됩니다. 이는 EOS_Stats_IngestStatCompleteCallbackInfo 구조체를 반환하는데, 그 구조체의 파라미터는 다음과 같습니다.

EOS_Stats_QueryStats 함수로 EOS 백엔드로부터 사용자 통계 목록을 요청할 수 있습니다. 연산이 완료되면 통계는 함수 자체를 통해 반환되지 않고 로컬에서 캐싱됩니다. 자세한 내용은 통계 복사 섹션을 참조하세요.

EOS_Stats_QueryStats 함수는 다음과 같은 파라미터를 수용합니다.

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

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

연산이 완료되면 EOS_Stats_QueryStats 에 제공된 모든 CompletionDelegate 가 호출됩니다. 이는 파라미터가 다음과 같은 EOS_Stats_OnQueryStatsCompleteCallbackInfo 구조체를 반환합니다.

EOS_Stats_QueryStats 가 연산에 성공하면 요청된 통계는 로컬 캐싱됩니다. 이후 EOS_Stats_CopyStatByIndex 또는 EOS_Stats_CopyStatByName 으로 로컬 캐시에서 주어진 통계의 사본을 얻을 수 있습니다.

통계 정보를 복사하여 EOS_Stats_Stat 구조체를 반환하게 하기 위한 함수입니다. 이 구조체는 하나의 특정 플레이어 통계에 대한 정보입니다. 프로퍼티는 다음과 같습니다.

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

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

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

연산 완료 시 아웃 파라미터 OutStat 을 사용하여 원하는 EOS_Stats_Stat 을 출력합니다. 해당 함수의 반환값은 EOS_EResult 입니다. 정보를 이용할 수 있고 OutStat 을 통해 성공적으로 전달되면 EOS_Success 값을 가지게 됩니다. 파라미터가 하나라도 유효하지 않거나 아웃 파라미터로 null 포인터가 제공되면 EOS_InvalidParameters 값을 가지게 됩니다. 요청한 통계를 찾을 수 없으면 EOS_NotFound 값을 가지게 됩니다.

EOS_Stats_CopyStatByIndexOptions 구조체는 EOS_Stats_CopyStatByIndex 의 요청된 통계 인덱스를 가집니다. 파라미터는 다음과 같습니다.

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

연산 완료 시 아웃 파라미터 OutStat 을 사용하여 원하는 EOS_Stats_Stat 을 출력합니다. 해당 함수의 반환값은 EOS_EResult 입니다. 정보를 이용할 수 있고 OutStat 을 통해 성공적으로 전달되면 EOS_Success 값을 가지게 됩니다. 파라미터가 하나라도 유효하지 않거나 아웃 파라미터로 null 포인터가 제공되면 EOS_InvalidParameters 값을 가지게 됩니다. 요청한 통계를 찾을 수 없으면 EOS_NotFound 값을 가지게 됩니다.

EOS_Stats_CopyStatByNameOptions 구조체는 EOS_Stats_CopyStatByName 의 요청된 통계 인덱스를 가집니다. 파라미터는 다음과 같습니다.

EOS_Stats_CopyStatByIndex 로 통계 데이터를 회수하고 나면 EOS_Stats_Stat_Release 를 호출하여 해당 통계 관련 메모리를 해제해야 합니다. 이 함수는 EOS_Stats_CopyStatByName 또는 EOS_Stats_CopyStatByIndex 의 OutStat 파라미터로 EOS_Stats_Stat 구조체 출력을 수용합니다.

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

전체 통계 시스템에 다음 제한이 적용됩니다.

통계 수집은 통계 변경을 서비스로 제출할 때의 엔드포인트이며, 사용자별 사용률 제한이 있습니다. 전용 서버가 사용자 대신 통계를 제출할 때는 사용자별 제한이 적용되지 않습니다. 이 경우 제한은 당시의 디플로이별 동시 사용자(CCU) 수를 베이스로 합니다.

업적을 테스트 샌드박스에서 테스트하려면 해당 샌드박스에 대한 디플로이에도 통계가 포함되어야 합니다. 업적을 라이브 환경에 디플로이하기 전에 테스트를 진행하여 통계 구조에서 발생할 수 있는 오류를 점검하고, 플레이어가 업적을 성공적으로 잠금해제하도록 지원해야 합니다.

제품 의 테스트 샌드박스 생성에 관한 정보는 제품, 샌드박스, 디플로이 ID의 문서를 참고하세요.