온라인 서비스 통계 인터페이스(Online Services Stats Interface) 는 온라인 서비스에 통계와 데이터를 업로드하고 통계 쿼리를 완료하는 데 사용됩니다. 통계 인터페이스 함수 기능은 온라인 서비스의 업적 및 순위표 인터페이스처럼 사용자의 게임플레이 통계에 의존하는 다른 인터페이스에도 사용됩니다.
API 개요
다음 테이블에서는 통계 인터페이스에 포함된 함수에 대한 포괄적인 설명을 확인할 수 있습니다.
| 함수 | 설명 |
|---|---|
| 업데이트 | |
UpdateStats |
플랫폼에 통계를 업로드합니다. |
| 쿼리 | |
QueryStats |
사용자의 통계를 쿼리하고 그 결과를 인터페이스에 캐시합니다. |
BatchQueryStats |
사용자 그룹의 통계를 쿼리하고 그 결과를 인터페이스에 캐시합니다. |
| 얻기 | |
GetCachedStats |
QueryStats 또는 BatchQueryStats를 호출한 뒤에 저장된 캐시된 사용자 통계를 얻습니다. |
| 이벤트 리스닝 | |
OnStatsUpdated |
사용자 통계가 변경되면 이벤트가 발동됩니다. |
구성
해당하는 플랫폼 백엔드 또는 StatsNull 구현을 통해 통계 인터페이스를 사용할 수 있습니다. 통계 인터페이스를 사용하려면, 먼저 DefaultEngine.ini 파일에서 통계 인터페이스를 환경설정해야 합니다.
DefaultEngine.ini
[OnlineServices.Stats]
StatDefinitions=(Name=Stat_Use_Largest, Id=0, ModifyMethod=Largest)
StatDefinitions=(Name=Stat_Use_Smallest, Id=1, ModifyMethod=Smallest)
StatDefinitions=(Name=Stat_Use_Set, Id=2, ModifyMethod=Set)
StatDefinitions=(Name=Stat_Use_Sum, Id=3, ModifyMethod=Sum)
통계 정의(Stat Definitions) 는 다음 필드로 구성됩니다:
Name: 통계의 이름입니다.- 각각
UpdateStats및QueryStats로 통계를 업데이트하고 쿼리하는 데 사용되는 이름입니다.
- 각각
Id: 통계의 ID입니다.- 플랫폼 포탈에서 구성된 해당 통계 ID입니다.
ModifyMethod: 통계 업데이트 방법을 규정하는 메서드입니다.- 비
StatsNull구현의 경우, 수정 메서드(Modify Method)는 플랫폼 포털에 구성됩니다. - 수정 메서드는 타이틀 관리 업적 사용 시 모든 구현에서 업적 인터페이스가 업적이 규정된 잠금해제 규칙을 충족하는지 여부를 결정하는 데 사용합니다.
- 비
통계로 업적을 잠금해제하고 순위표를 업데이트하려면, DefaultEngine.ini 파일의 업적 및 순위표 구성 섹션에 해당 통계를 지정해야 합니다.
예시
이 섹션에는 다음에 대한 방법을 안내하는 다양한 코드 예시가 포함되어 있습니다.
통계 쿼리하기
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::IStatsPtr Stats = OnlineServices->GetStatsInterface();
UE::Online::FQueryStats::Params Params;
Params.LocalAccountId = LocalAccountId;
Params.TargetAccountId = TargetAccountId;
Params.StatNames = {"StatA", "StatB"};
// 이 OnComplete 호출에 대한 자세한 내용은 연습 아래의 참고를 확인하세요.
Stats->QueryStats(MoveTemp(Params)).OnComplete([](const UE::Online::TOnlineResult<FQueryStats>& Result)
{
if (Result.IsError())
{
const UE::Online::FOnlineError OnlineError = Result.GetErrorValue();
// OnlineError 처리
return;
}
const UE::Online::FQueryStats::Result QueriedStats = Result.GetOkValue();
// QueriedStats 처리
});
연습
-
지정된 파라미터 없이
GetServices를 호출하여 기본 온라인 서비스를 사용합니다.UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
-
기본 온라인 서비스를 위한 통계 인터페이스에 액세스합니다.
UE::Online::IStatsPtr Stats = OnlineServices->GetStatsInterface();
-
TargetAccountId의StatNames를 쿼리하는 데 필요한 파라미터를 인스턴스화합니다.UE::Online::FQueryStats::Params Params; Params.LocalAccountId = LocalAccountId; Params.TargetAccountId = TargetAccountId; Params.StatNames = {"StatA", "StatB"}; -
오류 또는 쿼리된 통계를 처리하여
QueryStats.OnComplete콜백을 처리합니다.Stats->QueryStats(MoveTemp(Params)).OnComplete([](const UE::Online::TOnlineResult<FQueryStats>& Result) { if (Result.IsError()) { const UE::Online::FOnlineError OnlineError = Result.GetErrorValue(); // OnlineError 처리 return; } const UE::Online::FQueryStats::Result QueriedStats = Result.GetOkValue(); // QueriedStats 처리 });
멤버 함수를 바인딩하려면 언제나 UObject 파생 클래스 또는 TSharedFromThis에서 상속된 클래스를 사용하고 다음 함수를 사용하는 것이 좋습니다.
.OnComplete(this, &MyClass::OnQueryStatsComplete)
이렇게 하면 자동으로 CreateUObject, CreateThreadSafeSP 또는 CreateSP 가 선택됩니다. 가장 안전한 델리게이트 생성 호출이 사용됩니다. 자세한 내용은 온라인 서비스 개요 페이지의 콜백 포맷 섹션을 참조하세요.
캐시된 통계 얻기
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::IStatsPtr Stats = OnlineServices->GetStatsInterface();
UE::Online::TOnlineResult<FGetCachedStats> CachedStats = Stats->GetCachedStats({});
if (CachedStats.IsError())
{
UE::Online::FOnlineError OnlineError = CachedStats.GetErrorValue();
// OnlineError 처리
return;
}
UE::Online::FGetCachedStats::Result& CachedStatsData = CachedStats.GetOkValue();
// CachedStatsData 처리
연습
-
지정된 파라미터 없이
GetServices를 호출하여 기본 온라인 서비스를 사용하고 통계 인터페이스에 액세스합니다.UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::IStatsPtr Stats = OnlineServices->GetStatsInterface();
-
Stats->GetCachedStats로 통계 인터페이스를 통해 캐시된 통계를 얻습니다.UE::Online::TOnlineResult
-
오류 또는 캐시된 통계 데이터를 처리하여
CachedStats를 처리합니다.if (CachedStats.IsError()) { UE::Online::FOnlineError OnlineError = CachedStats.GetErrorValue(); // OnlineError 처리 return; } UE::Online::FGetCachedStats::Result& CachedStatsData = CachedStats.GetOkValue(); // CachedStatsData 처리
이벤트 수신하기
이벤트 리스닝은 동기 및 비동기 함수와는 다르게 처리됩니다. OnStatsUpdated 이벤트 결과 처리를 위해 FOnlineEventDelegateHandle 을 생성한 다음, 적절한 디스트럭션을 보장하기 위해 셧다운 코드에서 Unbind 를 호출해야 합니다.
연습
-
통계 인터페이스에 대한 클래스에서 이벤트 핸들을 선언합니다.
UE::Online::FOnlineEventDelegateHandle StatEventHandle; -
init 코드에서 기본 온라인 서비스를 초기화하고 통계 인터페이스에 액세스하고 이벤트 발생 시 통계를 처리합니다.
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::IStatsPtr Stats = OnlineServices->GetStatsInterface(); StatEventHandle = Stats->OnStatsUpdated().Add([](const UE::Online::FStatsUpdated& StatsUpdated) { // 이 람다 내 커스텀 로직 }); -
셧다운 코드에서 이벤트 핸들러의 바인딩 해제를 확인합니다.
StatEventHandle.Unbind();
콘솔 명령 실행하기
콘솔 명령으로 비동기 인터페이스를 실행하기 위한 일반 명령줄 구문의 경우, 온라인 서비스 개요 문서를 참조하세요.
예시
QueryStats 함수를 실행하려면 다음 콘솔 명령을 실행합니다.
OnlineServices Index=0 Stats QueryStats 0 0 ["StatA", "StatB"]
이 명령은 0번째 로컬 사용자에 대해 기본 온라인 서비스로 통계 인터페이스에서 QueryStats 를 호출합니다. 특히, 위의 명령은 기본 온라인 서비스에 이 사용자의 StatA 및 StatB 를 쿼리합니다.
통계 데이터 리셋하기
개발 및 테스트 중에 ResetStats 함수는 현재 타이틀에 대해 제공된 모든 플레이어 통계를 리셋합니다. 온라인 서비스마다 정책은 다르지만, 이 함수가 테스트 환경 외부에서 작동할 것이라고 기대해서는 안 됩니다. 출시 빌드에서는 ResetStats 함수를 사용한 모든 코드를 제거하거나, 컴파일 시간 로직을 사용하여 이 코드를 다음과 같이 마스킹하세요.
#if !UE_BUILD_SHIPPING
// ResetStats 호출이 포함된 코드 블록
#endif
추가 정보
헤더 파일
필요에 따라 Stats.h 헤더 파일에서 직접 추가 정보를 참조하세요. Stats.h 통계 인터페이스 헤더 파일은 다음 디렉터리에 있습니다.
UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE 소스 코드를 획득하는 방법에 대한 지침은 언리얼 엔진 소스 코드 내려받기 문서를 참조하세요.
함수 파라미터 및 반환 타입
파라미터 전달 방법 및 / 함수 반환 시 결과 처리 방법을 포함한 함수 파라미터 및 반환 타입에 대한 설명은 온라인 서비스 개요 페이지의 함수 섹션을 참조하세요.