EOS 음성 채팅 플러그인

EOS 음성 채팅(EOS Voice Chat) 플러그인을 사용하면 개발자는 에픽 온라인 서비스(Epic Online Services, EOS) 음성 인터페이스를 활용하여 제품에 음성 커뮤니케이션을 추가할 수 있습니다. EOS 음성 인터페이스 활용에는 엔진의 온라인 서브 시스템(Online Subsystem, OSS) 로부터 유사한 IVoiceChat 및 IVoiceChatUser 인터페이스를 사용하는 것이 포함됩니다. 또한, VivoxVoiceChat을 사용했던 개발자는 EOS 백엔드로 간단히 이주할 수 있습니다.

구성

EOS 음성 채팅 플러그인(EOS Voice Chat plugin)은 IVoiceChat 및 IVoiceChatUser 인터페이스를 실행합니다. 시작하려면 에디터의 편집(Edit) 메뉴에서 플러그인 브라우저(Plugin Browser) 를 연 다음 플러그인을 찾아 활성화합니다.

프로젝트에서 플러그인을 활성화했다면 로비(Lobbies) 또는 신뢰할 수 있는 서버(Trusted Server) 방식을 통해 통합할 수 있습니다. 이러한 방식들은 서로 배타적이지 않으므로 같이 사용하여 각 방식의 이점과 기능을 취할 수 있습니다.

두 방식 모두 EOS 작동 방식에 기반하지만, EOS SDK로 직접 프로그래밍할 필요는 없습니다. 하지만 작동 방식을 더 잘 이해하고 싶다면 EOS 음성 인터페이스 문서를 읽어보세요. 문서를 읽을 때 IVoiceChat의 채널(Channels) 이 EOS에서 룸(Rooms) 과 동일한 의미를 가지며, 두 용어가 서로 바뀌어 사용될 수 있다는 것을 명심하세요.

EOS 음성 인터페이스와 통합하기

두 가지 주요 통합 방식인 로비(Lobbies)와 신뢰할 수 있는 서버(Trusted Server)는 서로 다른 기능을 제공합니다. 특정 방식이 프로젝트에 더 잘 맞는다고 간주되는 경우가 아니라면 혼합해서 사용하는 것을 권장합니다. 로비 방식을 사용하면 시스템이 IVoiceChatUser::JoinChannel 함수 없이 자동으로 EOS를 통해 음성 채팅에 참가하며, EOS에서 IVoiceChatUser 인스턴스를 받게 됩니다. 신뢰할 수 있는 서버 방식을 사용하는 경우 신뢰할 수 있는 서버에서 크리덴셜을 받아 IVoiceChatUser::JoinChannel 함수를 호출해야 하지만, 참가하거나 퇴장할 채널을 직접 선택할 수 있습니다. 또한 이 방식을 사용하면 EOS가 제공하는 인스턴스를 사용하기보다는 IVoiceChat 및 IVoiceChatUser 인스턴스를 제어할 수 있습니다. IVoiceChat 및 IVoiceChatUser 인터페이스로 신뢰할 수 있는 서버 채널을 수동 관리하면서 OnlineSubsystemEOS 플러그인으로 로비 음성 채널을 자동 관리하고 싶다면 두 가지 통합 방식을 혼합해서 사용하면 됩니다. 또한 혼합 통합 방식을 사용하는 개발자들은 사용자가 신뢰할 수 있는 서버 방식으로 가입한 채널을 통해 로비 방식의 IVoiceChatUser 인스턴스를 재사용할 수도 있습니다.

시작하려면 EOS 개발자 포털에서 애플리케이션을 환경설정해야 합니다. 또한 로비 통합 방식을 사용 중인 경우 프로젝트에서 OnlineSubsystemEOS 플러그인을 활성화해야 합니다.

로비 방식 사용하기

로비 방식은 채널 참가와 관련된 작업 대부분에 EOS를 사용합니다. 로비 방식을 사용할 경우 EOS가 작업을 대신하므로 초기화하고, 연결하고, 로그인하고, 채널에 참가하는 일반적인 IVoiceChat 흐름을 구현할 필요가 없다는 뜻입니다.

프로젝트에서 OnlineSubsystemEOS를 구성했다면 EOS 로비 세션에 참가하고, EOS 로비 세션을 호스트할 수 있습니다. 아래 단계를 따르면 해당 음성 채널에 대한 자동 가입이 활성화됩니다.

1. EOS 개발자 포털(EOS Developer Portal)에서 음성 지원을 활성화해 애플리케이션을 환경설정합니다.

2. 로비 세션 생성 시 FOnlineSessionSettings::bUseLobbiesVoiceChatIfAvailable 을 true 로 설정합니다.

3. FOnlineSubsystemEOS::GetVoiceChatUserInterface 를 호출하여 주어진 로컬 사용자와 연결된 IVoiceChatUser 인터페이스 인스턴스를 얻습니다.

사용자가 EOS에 로그인하면 GetVoiceChatUserInterface 함수로 IVoiceChatUser 인터페이스의 인스턴스를 얻을 수 있습니다. 채널을 관리할 필요는 없지만, 이 인터페이스 인스턴스를 사용해 사용자의 선택된 입출력 디바이스 또는 차단된 플레이어 목록 등 시스템의 다른 측면과 상호작용할 수 있습니다. 이 인터페이스 인스턴스를 사용해 이벤트 알림 콜백을 등록합니다. 사용자가 로그인 상태를 유지하는 한, OnlineSubsystemEOS 플러그인이 사용자가 참가하거나 퇴장하는 모든 로비에 연결된 음성 채널에 자동으로 참가 및 퇴장합니다. 이때 EOSVoiceChat은 이에 대응하여 OnVoiceChatChannelJoined 및 OnVoiceChatChannelExited 델리게이트를 브로드캐스트합니다.

OnlineSubsystemEOS 플러그인이 로비 세션 생성, 삭제, 참가, 퇴장에 대한 알림을 포함한 로비 세션에 대한 정보로 EOS 음성 채팅 플러그인을 자동 업데이트합니다. EOS 음성 채팅 플러그인은 이러한 이벤트에 대응하여 OnVoiceChatChannelJoined 및 OnVoiceChatChannelExited 델리게이트를 브로드캐스트합니다.

신뢰할 수 있는 서버 방식 사용하기

수동 채널 관리가 더 적합한 상황이라면 신뢰할 수 있는 서버(Trusted Server) 통합 방식을 사용해야 합니다. 예를 들어 EOS 로비 기반으로 구축되지 않은 파티 시스템을 사용하는 경우, 신뢰할 수 있는 서버 방식을 사용해야 이러한 파티용 채널을 생성할 수 있습니다. 신뢰할 수 있는 서버 방식을 사용하면 사용자의 채널 연결을 더 잘 제어할 수 있지만, 사용자가 채널에 가입하려면 신뢰할 수 있는 서버에서 로그인 크리덴셜을 얻어야 합니다.

신뢰성 있는 서버 엔진 환경설정

로비 통합 방식의 IVoiceChatUser 인터페이스 인스턴스를 재사용하는 경우 이 섹션을 건너뛰어도 됩니다.

로비 통합 방식을 사용하지 않거나 별도의 IVoiceChatUser 인터페이스 인스턴스를 사용하고자 하는 경우, 다음 섹션을 Engine.ini 파일에 추가하고 사용 중인 제품 관련 정보로 채워야 합니다.

	[EOSVoiceChat]
	ProductId=
	SandboxId=
	DeploymentId=
	ClientId=
	ClientSecret=

Copy full snippet

[EOSVoiceChat] ProductId= SandboxId= DeploymentId= ClientId= ClientSecret=

각 줄을 사용 중인 제품에 적합한 값으로 채웁니다. 값은 EOS 개발자 포털(EOS Developer Portal)에서 제품을 열어 확인할 수 있습니다. EOSVoiceChat은 이러한 값을 사용해 EOS 플랫폼 인터페이스 인스턴스를 생성합니다.

코드 플로

신뢰성 있는 서버 통합 방식으로 작업하는 경우, 음성 채팅 인터페이스 문서에 설명된 것과 동일한 코드 플로를 준수해야 합니다. 프로젝트가 두 가지 통합 방식을 모두 사용하고 신뢰성 있는 서버 채널에 OSS EOS의 IVoiceChatUser 인스턴스를 하나 이상 사용하는 경우, 로비 통합 방식이 인스턴스 수명 관리 등 대부분의 IVoiceChat 플로를 자동 처리하며 로그인한 IVoiceChatUser 인터페이스를 제공하므로 이러한 요구 사항이 적용되지 않습니다.

채널 참가하기

코드를 EOS SDK로 인터페이싱할 필요는 없지만, 채널 참가 프로세스는 궁극적으로 EOS 음성 인터페이스를 통해 이루어집니다. 해당 시스템을 더 잘 이해하고 싶다면 EOS 문서 사이트에서 이 문서를 읽는 것을 권장합니다.

채널에 참가하려면 클라이언트 기반 URL과 신뢰할 수 있는 서버에서 받은 참여자 토큰이 필요합니다. 아래 샘플과 유사하게 FEOSVoiceChatChannelCredentials 구조체를 채우고 JSON에 시리얼라이징해 EOS 음성 채팅에 이 정보를 제공합니다.

	// FEOSVoiceChatChannelCredentials 데이터 구조체를 생성합니다.
	FEOSVoiceChatChannelCredentials ChannelCredentials;
	// 세션마다 다른 신뢰할 수 있는 서버에서 클라이언트 기반 URL을 설정합니다.
	// URL은 "wss://example-of-url-us-east-1.rtcp.on.epicgames.com"과 같은 형식입니다.
	ChannelCredentials.ClientBaseUrl = ClientBaseUrlFromTrustedServer
	// 신뢰할 수 있는 서버에서 참여자 토큰을 설정합니다.
	ChannelCredentials.ParticipantToken = ParticipantTokenFromTrustedServer;

	// FEOSVoiceChatChannelCredentials 데이터 구조체로 JoinChannel을 호출합니다.
	VoiceChatUser->JoinChannel(ChannelName, ChannelCredentials.ToJson(), ...);

Copy full snippet

// FEOSVoiceChatChannelCredentials 데이터 구조체를 생성합니다. FEOSVoiceChatChannelCredentials ChannelCredentials; // 세션마다 다른 신뢰할 수 있는 서버에서 클라이언트 기반 URL을 설정합니다. // URL은 "wss://example-of-url-us-east-1.rtcp.on.epicgames.com"과 같은 형식입니다. ChannelCredentials.ClientBaseUrl = ClientBaseUrlFromTrustedServer // 신뢰할 수 있는 서버에서 참여자 토큰을 설정합니다. ChannelCredentials.ParticipantToken = ParticipantTokenFromTrustedServer; // FEOSVoiceChatChannelCredentials 데이터 구조체로 JoinChannel을 호출합니다. VoiceChatUser->JoinChannel(ChannelName, ChannelCredentials.ToJson(), ...);

로비 및 신뢰할 수 있는 서버 방식 혼합 사용하기

로비 통합 방식과 신뢰할 수 있는 서버 통합 방식은 서로 완전히 호환됩니다. 두 방식의 이점을 모두 취하고 싶다면 신뢰할 수 있는 서버 채널에 참가, 퇴장 및 상호작용할 때 로비 방식의 IVoiceChatUser 인터페이스를 재사용하거나, 별도의 인터페이스 인스턴스를 생성하면 됩니다.

테스팅 및 디버깅

콘솔 명령

로그 출력

LogEOSVoiceChat 로그 카테고리에는 EOSVoiceChat 플러그인 자체의 모든 로그 출력이 포함됩니다. 반면 LogEOSSDK 로그 카테고리에는 기저 EOS SDK의 로그 출력이 포함됩니다. LogEOSSDK 로그 카테고리의 상세 옵션 수준을 변경하면 EOS SDK Logging Interface의 로그 상세 옵션 세팅도 업데이트되므로 둘은 항상 동기화 상태를 유지합니다.