통계 인터페이스

통계 관리용 인터페이스입니다.

개발자는 통계 인터페이스 로 애플리케이션의 사용자 통계 를 관리할 수 있으며, 획득 아이템 수, 승리/패배 수 또는 사용자가 특정 액션을 수행한 횟수 등 개발자가 확인하고자 하는 모든 통계 데이터가 포함됩니다. 통계를 활용해 정보를 수집하고 업적순위표 를 처리할 수 있습니다. 인터페이스는 `eos_stats.h`에서 철저히 설명되어 있습니다.

통계 인터페이스 액세스

통계 인터페이스 함수에 액세스하려면

[Platform Interface](인터페이스/플랫폼)
에서 EOS_Platform_GetStatsInterface 함수를 호출하여 EOS_HStats 핸들을 확보해야 합니다. 모든 인터페이스가 그렇듯이 EOS_HPlatform 핸들이 요청 완료 시 적절한 콜백이 발동되도록 티킹하는 게 중요합니다.

통계 흡수

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

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

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

Parameter

Description

Handle

유효한 EOS_HStats 핸들입니다.

Options

흡수하는 통계에 대한 정보가 포함된 EOS_Stats_IngestStatsOptions 구조체입니다.

ClientData

`CompletionDelegate`에서 다시 전달되는 임의의 데이터입니다.

CompletionDelegate

시그니처가 `EOS_Stats_OnIngestStatCompleteCallback`과 일치하는 함수입니다. 통계 흡수 연산 완료 시 호출됩니다.

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

통계 옵션 흡수

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

Parameter

Description

ApiVersion

EOS_STATS_INGESTSTAT_API_LATEST로 설정합니다.

UserId

흡수되는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 `EOS_ProductUserId`입니다.

Stats

흡수하려는 통계의 정보를 가진 EOS_Stats_IngestData 구조체의 목록입니다.

StatsCount

흡수할 통계 개수입니다.

데이터 흡수

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

Parameter

Description

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 백엔드로부터 사용자 통계 목록을 요청할 수 있습니다. 연산이 완료되면 통계는 함수 자체를 통해 반환되지 않고 로컬에서 캐싱됩니다. 자세한 정보는 Copying Stats를 참조하세요.

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

Parameter

Description

Handle

유효한 EOS_HStats 핸들입니다.

Options

회수하는 통계를 소유한 플레이어에 대한 정보가 포함된 EOS_Stats_QueryStatOptions 구조체입니다.

ClientData

`CompletionDelegate`에서 다시 전달되는 임의의 데이터입니다.

CompletionDelegate

시그니처가 `EOS_Stats_OnQueryStatsCompleteCallback`과 일치하는 함수입니다. 통계 흡수 연산 완료 시 호출됩니다.

쿼리 통계 옵션

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

Parameter

Description

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` 구조체를 반환합니다.

Parameter

Description

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

Property

Description

ApiVersion

`EOS_STATS_STAT_API_LATEST`로 설정합니다.

Name

개발자 포털에 표시되는 통계 이름입니다.

StartTime

`EOS_STATS_TIME_UNDEFINED`가 아니면 이 통계를 반환한 쿼리의 시작 시간 POSIX 타임 스탬프입니다.

EndTime

`EOS_STATS_TIME_UNDEFINED`가 아니면 이 통계를 반환한 쿼리의 종료 시간 POSIX 타임 스탬프입니다.

Value

통계의 현재 값으로, integer 형식입니다.

통계 개수 획득

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

Parameter

Description

Handle

유효한 EOS_HStats 핸들입니다.

Options

EOS_STATS_GETSTATCOUNT_API_LATEST 값으로 설정된 ApiVersion`과 회수하는 통계 개수를 소유한 사용자의 유효한 EOS_ProductUserId`로 설정된 UserId`로 이루어진 EOS_Stats_GetStatCountOptions` 구조체입니다.

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

인덱스로 통계 복사

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

Parameter

Description

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`의 요청된 통계 인덱스를 가집니다. 파라미터는 다음과 같습니다.

Parameter

Description

ApiVersion

`EOS_STATS_COPYSTATBYINDEX_API_LATEST`로 설정합니다.

UserId

사본을 얻는 통계를 소유한 사용자의 계정 ID를 나타내는 유효한 `EOS_ProductUserId`입니다.

StatIndex

캐싱된 통계 목록 내 인덱스를 나타내는 integer입니다.

이름으로 통계 복사

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

Parameter

Description

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`의 요청된 통계 인덱스를 가집니다. 파라미터는 다음과 같습니다.

Parameter

Description

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` 구조체 출력을 수용합니다.

사용 제한

성능 및 속도의 유지를 위해 준수해야 하는 사용 제한에 대한 자세한 정보는 서비스 사용 제한 페이지를 참고해 주세요.