언리얼 엔진의 현재상태 인터페이스 | 언리얼 엔진 5.6 문서

온라인 서비스에 로그인할 때, 온라인에서 만난 친구와 다른 사용자에 대한 정보를 확인하고 싶을 수도 있습니다. 예를 들어, 많은 온라인 서비스에서는 다른 사용자가 온라인인지, 그들이 현재 어떤 게임을 플레이하고 있는지, 매치에 참가할 수 있는지와 같은 정보를 확인할 수 있습니다. 온라인 서비스 현재상태 인터페이스(Online Services Presence Interface) 는 사용자의 현재상태를 쿼리하고 업데이트하고 변경사항을 리스닝하는 등, 온라인 서비스 전반에 걸친 플랫폼별 사용자 상태와 관련된 모든 함수 기능을 포함합니다.

이 문서에서는 API 개요와 코드 예시, 그리고 온라인 서브시스템 현재상태 인터페이스에서 코드를 변환하는 팁을 살펴봅니다.

API 개요

함수

다음 테이블에서는 현재상태 인터페이스에 포함된 함수에 대한 개괄적 설명을 확인할 수 있습니다.

함수	설명
쿼리
`QueryPresence`	제공된 `TargetAccountId` 를 지닌 사용자의 현재상태를 가져옵니다.
`BatchQueryPresence`	제공된 `TargetAccountIds` 목록에 있는 모든 사용자의 현재상태를 가져옵니다.
얻기
`GetCachedPresence`	인터페이스에 캐시된 제공된 `TargetAccountId` 를 지닌 사용자의 현재상태를 얻습니다.
업데이트
`UpdatePresence`	사용자 현재상태를 업데이트합니다.
`PartialUpdatePresence`	지정된 현재상태 세팅으로만 사용자의 현재상태를 업데이트합니다.
이벤트 리스닝
`OnPresenceUpdated`	사용자의 현재상태가 업데이트되면 이벤트가 트리거됩니다.

열거형 클래스

현재상태 인터페이스는 사용자 상태와 참가 가능 여부, 게임 상태를 나타내는 세 개의 열거형 클래스를 정의합니다. 이러한 열거형 클래스는 FUserPresence 구조체의 세 가지 프라이머리 멤버를 나타냅니다. 자세한 내용은 이 페이지의 프라이머리 구조체 섹션을 참조하세요.

EUserPresenceStatus

열거자	설명
`Offline`	사용자가 오프라인입니다.
`Online`	사용자가 온라인입니다.
`Away`	사용자가 자리를 비웠습니다.
`ExtendedAway`	사용자가 2시간(플랫폼에 따라 다를 수 있음) 이상 자리를 비웠습니다.
`DoNotDisturb`	사용자가 방해받기를 원하지 않습니다.
`Unknown`	기본 사용자 현재상태 스테이트입니다.

EUserPresenceJoinability

열거자	설명
`Public`	누구나 이 세션을 찾고 참가할 수 있습니다.
`FriendsOnly`	참가하려면 로비 멤버의 친구여야 합니다.
`InviteOnly`	참가하려면 먼저 초대받아야 합니다.
`Private`	사용자가 현재 초대를 수락하지 않고 있습니다.
`Unknown`	기본 사용자 현재상태 참가 가능 여부 스테이트입니다.

EUserPresenceGameStatus

열거자	설명
`PlayingThisGame`	사용자가 나와 같은 게임을 플레이하고 있습니다.
`PlayingOtherGame`	사용자가 나와 다른 게임을 플레이하고 있습니다.
`Unknown`	기본 사용자 현재상태 게임 스테이트입니다.

프라이머리 구조체

FUserPresence

FUserPresence 구조체는 현재상태 인터페이스의 프라이머리 오브젝트이며 사용자 현재상태와 관련된 모든 필수 정보로 구성됩니다.

멤버	타입	설명
`AccountId`	`FAccountId`	이 현재상태의 사용자입니다.
`Status`	`EUserPresenceStatus`	사용자 현재상태 스테이트입니다. 기본값은 `EUserPresenceStatus::Unknown` 입니다.
`Joinability`	`EUserPresenceJoinability`	사용자 세션 스테이트입니다. 기본값은 `EUserPresenceJoinability::Unknown` 입니다.
`GameStatus`	`EUserPresenceGameStatus`	사용자 게임 스테이트입니다. 기본값은 `EUserPresenceGameStatus::Unknown` 입니다.
`StatusString`	`FString`	사용자 현재상태 스테이트의 스트링 표현입니다.
`RichPresenceString`	`FString`	현재 게임 스테이트의 게임 정의 표현입니다.
`Properties`	`FPresenceProperties`	세션 키입니다.

FPresenceProperties 타입은 FPresenceVariant 가 FString 인 TMap<FString, FPresenceVariant> 에 대한 typedef입니다.

예시

이제 UpdatePresence, QueryPresence 및 GetPresence 를 보여주는 예시를 살펴보겠습니다. UserA 가 기본 플랫폼 서비스로 현재상태를 업데이트한 후, UserB 는 업데이트된 UserA 의 현재상태를 쿼리합니다. 쿼리가 성공적으로 반환되면, UserB 는 UserA 의 현재상태를 얻습니다.

코드

UserAPresence.cpp

    UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
	UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();

	TSharedRef<UE::Online::FUserPresence> Presence = MakeShared<UE::Online::FUserPresence>();
	Presence->AccountId = UserA;
	Presence->Status = UE::Online::EUserPresenceStatus::Online;
	Presence->Joinability = UE::Online::EUserPresenceJoinability::Public;
	Presence->RichPresenceString = TEXT("Exploring the Great Citadel");
	Presence->Properties.Add(TEXT("advanced_class"), TEXT("advanced_class_assassin"));
	
	UE::Online::FUpdatePresence::Params Params;
	Params.LocalAccountId = AccountId;
	Params.Presence = Presence;

	PresenceInterface->UpdatePresence(MoveTemp(Params))
	.OnComplete([](const UE::Online::TOnlineResult<UE::Online::FUpdatePresence> Result)
	{
		if(Result.IsOk())
		{
			// 성공 - 이제 UserB가 현재상태를 쿼리할 수 있습니다.
		}
		else
		{
			// 실패 - Result.GetErrorValue();에서 오류 스테이트를 확인하십시오.
		}
	});

UserBPresence.cpp

    UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
	UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();
	
    PresenceInterface->QueryPresence({UserA})
    .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result)
    {
        if(Result.IsOk())
        {
            // 성공 - 이제 GetPresence를 사용하여 실제로 현재상태 오브젝트를 확인합니다.
            
            UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB});
            if(GetPresenceResult.IsOk())
            {
                TSharedRef<const UE::Online::FUserPresence> Presence = GetPresenceResult.GetOkValue().Presence;

                // 이제 Presence->RichPresenceString은 "그레이트 시타델 탐험"이 됩니다.
                // 이제 Presence->Properties에는 {advanced_class: advanced_class_assassin}이 포함됩니다.
                // 기타 등등...
            }
            else
            {
                // 실패 - GetPresenceResult.GetErrorValue();로 오류 스테이트를 확인하십시오.
            }
            
        }
        else
        {
            // 실패 - Result.GetErrorValue();에서 오류 스테이트를 확인하십시오.
        }
    });

UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
	UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();
	
    PresenceInterface->QueryPresence({UserA})
    .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result)
    {
        if(Result.IsOk())
        {
            // 성공 - 이제 GetPresence를 사용하여 실제로 현재상태 오브젝트를 확인합니다.
            
            UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB});
            if(GetPresenceResult.IsOk())
            {
                TSharedRef<const UE::Online::FUserPresence> Presence = GetPresenceResult.GetOkValue().Presence;

// 이제 Presence->RichPresenceString은 "그레이트 시타델 탐험"이 됩니다.
                // 이제 Presence->Properties에는 {advanced_class: advanced_class_assassin}이 포함됩니다.
                // 기타 등등...
            }
            else
            {
                // 실패 - GetPresenceResult.GetErrorValue();로 오류 스테이트를 확인하십시오.
            }
            
        }
        else
        {
            // 실패 - Result.GetErrorValue();에서 오류 스테이트를 확인하십시오.
        }
    });

연습

두 사용자 모두 지정된 파라미터 없이 GetServices 를 호출하여 기본 온라인 서비스를 가져온 다음, 현재상태 인터페이스에 액세스합니다.

UserAPresence.cpp 및 UserBPresence.cpp
```
     UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
     UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();
```
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::IPresencePtr PresenceInterface = OnlineServices->GetPresenceInterface();
UserA 가 Presence 라는 FUserPresence 구조체를 초기화합니다. 앞서 언급한 현재상태 인터페이스에서 제공하는 열거형 중 EUserPresenceStatus 와 EUserPresenceJoinability 두 개를 사용한다는 점에 주목하세요.

UserAPresence.cpp
```
     TSharedRef<UE::Online::FUserPresence> Presence = MakeShared<UE::Online::FUserPresence>();
     Presence->AccountId = UserA;
     Presence->Status = UE::Online::EUserPresenceStatus::Online;
     Presence->Joinability = UE::Online::EUserPresenceJoinability::Public;
     Presence->RichPresenceString = TEXT("Exploring the Great Citadel");
     Presence->Properties.Add(TEXT("advanced_class"), TEXT("advanced_class_assassin"));
```
TSharedRef<UE::Online::FUserPresence> Presence = MakeShared<UE::Online::FUserPresence>(); Presence->AccountId = UserA; Presence->Status = UE::Online::EUserPresenceStatus::Online; Presence->Joinability = UE::Online::EUserPresenceJoinability::Public; Presence->RichPresenceString = TEXT("Exploring the Great Citadel"); Presence->Properties.Add(TEXT("advanced_class"), TEXT("advanced_class_assassin"));
UserA 가 UpdatePresence 에 전달될 파라미터로 Params 라는 FUpdatePresence::Params 구조체를 초기화합니다.

UserAPresence.cpp
```
     UE::Online::FUpdatePresence::Params Params;
     Params.LocalAccountId = AccountId;
     Params.Presence = Presence;
```
UE::Online::FUpdatePresence::Params Params; Params.LocalAccountId = AccountId; Params.Presence = Presence;
UserA 가 UpdatePresence 를 호출하고 OnComplete 콜백으로 그 결과를 처리합니다.

UserAPresence.cpp
```
     PresenceInterface->UpdatePresence(MoveTemp(Params))
     .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FUpdatePresence> Result)
     {
         if(Result.IsOk())
         {
             // 성공 - 이제 UserB가 현재상태를 쿼리할 수 있습니다.
         }
         else
         {
             // 실패 - Result.GetErrorValue();에서 오류 스테이트를 확인하십시오.
         }
     });
```
PresenceInterface->UpdatePresence(MoveTemp(Params)) .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FUpdatePresence> Result) { if(Result.IsOk()) { // 성공 - 이제 UserB가 현재상태를 쿼리할 수 있습니다. } else { // 실패 - Result.GetErrorValue();에서 오류 스테이트를 확인하십시오. } });
UserB 가 UserA 의 현재상태를 쿼리합니다. 쿼리의 OnComplete 콜백 내에서 UserB 는 먼저 QueryPresence 가 'OK' 상태를 반환했는지 확인합니다. OK 상태가 반환되었다면, UserB 는 안전하게 UserA 의 현재상태를 가져오고 그에 따라 GetPresence 의 결과나 오류를 처리할 수 있습니다.

UserBPresence.cpp
```
     PresenceInterface->QueryPresence({UserA})
     .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result)
     {
         if(Result.IsOk())
         {
             // 성공 - 이제 GetPresence를 사용하여 실제로 현재상태 오브젝트를 확인합니다.
                
             UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB});
             if(GetPresenceResult.IsOk())
             {
                 // 성공했습니다!
             }
             else
             {
     // 실패 - GetPresenceResult.GetErrorValue();로 오류 스테이트를 확인하십시오.
             }
                
         }
         else
         {
             // 실패 - Result.GetErrorValue();에서 오류 스테이트를 확인하십시오.
         }
     });
```
PresenceInterface->QueryPresence({UserA}) .OnComplete([](const UE::Online::TOnlineResult<UE::Online::FQueryPresence> Result) { if(Result.IsOk()) { // 성공 - 이제 GetPresence를 사용하여 실제로 현재상태 오브젝트를 확인합니다. UE::Online::TOnlineResult<UE::Online::FGetPresence> GetPresenceResult = PresenceInterface->GetPresence({UserB}); if(GetPresenceResult.IsOk()) { // 성공했습니다! } else { // 실패 - GetPresenceResult.GetErrorValue();로 오류 스테이트를 확인하십시오. } } else { // 실패 - Result.GetErrorValue();에서 오류 스테이트를 확인하십시오. } });

모든 함수 호출이 오류 없이 반환되면, 이제 UserB 는 UserA 의 업데이트된 상태를 확인하고 UserB 는 이 상태에 따라 결정을 선택할 수 있습니다. 예를 들어 UserB 는 GetPresenceResult 에 액세스하여 UserA 가 온라인이고 참가 가능 여부 상태가 공개인지 확인할 수 있습니다. 이 상태 설정 시 UserB 는 UserA 와 '그레이트 시타델 탐험'에 함께 참가하기로 결정할 수 있습니다.

온라인 서브시스템에서 코드 변환하기

온라인 서비스 플러그인은 온라인 서브시스템 플러그인의 업데이트된 버전이며 가까운 미래에는 서로 나란히 존재할 것입니다. 온라인 서비스 현재상태 인터페이스의 API 함수 기능은 온라인 서브시스템 현재상태 인터페이스의 API 함수 기능과 거의 일대일로 매핑됩니다. 다음과 같은 몇 가지 사항에 주의해야 합니다.

함수의 비동기성을 더 잘 나타내기 위해 SetPresence 의 이름을 UpdatePresence 로 변경했습니다.
UpdatePresence 및 QueryPresence 는 이제 오버로드되지 않습니다.
대신 변경된 이름의 PartialUpdatePresence 및 BatchQueryPresence 함수를 사용하는 것이 좋습니다.
- UpdatePresence 및 QueryPresence 에 대한 오버로드는 각각 PartialUpdatePresence 및 BatchQueryPresence 로 이름이 변경되었습니다.
QueryPresence 에 bListenToChanges 파라미터가 주어졌습니다.
- 이 파라미터는 OnPresenceUpdated 이벤트에 특정 사용자를 추가합니다.
- 파라미터의 기본값은 True로 설정됩니다.

추가 정보

헤더 파일

필요에 따라 Presence.h 헤더 파일에서 직접 추가 정보를 참조하세요. Presence.h 현재상태 인터페이스 헤더 파일은 다음 디렉터리에 있습니다.

	UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

UE 소스 코드를 획득하는 방법에 대한 지침은 언리얼 엔진 소스 코드 내려받기 문서를 참조하세요.

함수 파라미터 및 반환 타입

파라미터 전달 방법 및 / 함수 반환 시 결과 처리 방법을 포함한 함수 파라미터 및 반환 타입에 대한 설명은 온라인 서비스 개요 페이지의 함수 섹션을 참조하세요.