Unreal Engine 멤버십

Unreal Engine에서 Hybe Game Platform Service(이하, 플랫폼, Platform)의 멤버십(로그인·계정) 기능을 연동하는 방법을 설명합니다.

이 문서의 코드 예시는 UnrealStarter 샘플 프로젝트를 기준으로 작성되었습니다. 샘플의 핵심 구현 파일은 다음과 같습니다.

구분	샘플 파일	역할
Auth Agent	`Source/UnrealStarter/Agent/USPlatformAuthAgent.*`	인증 이벤트 처리
Webview Agent	`Source/UnrealStarter/Agent/USPlatformWebviewAgent.*`	웹뷰 Show/Close 처리
커스텀 웹뷰	`Source/UnrealStarter/Public/LoginWebBrowser.*`	WebBrowser 플러그인 연동
초기화	`Source/UnrealStarter/UI/Page/InitPage.cpp`	SDK Mount 및 설정
로그인 UI	`Source/UnrealStarter/UI/Page/LoginPage.cpp`	로그인 수단별 호출
계정 관리	`Source/UnrealStarter/UI/Page/AccountPage.cpp`	로그아웃·탈퇴·토큰 갱신

결제 연동은 Unreal Engine 빌링 문서를 참고하세요.

요구사항

플랫폼 SDK를 사용하기 위한 요구 사항은 다음과 같습니다.

OS: Windows, macOS, Android, iOS
Unreal Engine: 5.4 이상
Visual Studio 2022 권장 (Windows)

정보

플랫폼 SDK는 언리얼 플러그인(HybePlatform)으로 제공됩니다.

Unreal Engine 5.4.4, 5.5.4 환경에서 테스트되었습니다.

정보

iOS 개발을 위해 macOS를 지원합니다.

macOS Standard 실행 모드에서 일부 기능은 동작하지 않을 수 있습니다.

연동 준비

SDK 설치

언리얼 엔진에서 Platform SDK를 사용하려면 배포된 플러그인 [HybePlatform] 폴더를 프로젝트의 Plugins 폴더 하위에 복사합니다.

UnrealStarter 샘플 프로젝트

플랫폼 SDK 플러그인을 이용한 언리얼 샘플 프로젝트를 제공합니다.

UnrealStarter_x.x.x.zip 파일을 압축 해제합니다.
샘플앱 프로젝트는 5.2.1 환경으로 제공됩니다.
UnrealStarter.uproject 파일에서 오른쪽 버튼을 이용해 Visual Studio 솔루션 파일을 생성합니다.
Visual Studio 솔루션 파일을 엽니다.
게임 접속 환경 설정 후 빌드합니다.

정보

언리얼 5.4에서 샘플 프로젝트 열기

UnrealStarter.uproject 파일에서 오른쪽 버튼을 클릭한 후

[Switch Unreal Engine version...]을 선택하고, [Select Unreal Engine Version]에서 5.4를 선택한 후 업데이트된 UnrealStarter.uproject 파일을 엽니다.

샘플 실행 환경 설정

DefaultEngine.ini에 Custom URI Scheme을 등록합니다.

DefaultEngine.ini
[HybeGamePlatform]
CustomScheme=drimageplatform

플랫폼 초기화 시 전달하는 Configuration JSON 예시입니다. 샘플에서는 Content/UnrealStarter/Data/DrimagePlatform/drimage_config.json에서 환경을 선택합니다.

{
    "BuildEnv": "qa",
    "ProjectId": "XXXXX",
    "WebClientId": "xxx-xxxx-xxx",
    "SteamAppID": 0,
    "SteamIdentity": "sample-qa-00000000"
}

샘플 디렉토리 구조

경로	설명
`Config/`	샘플앱 설정 파일 (`DefaultEngine.ini` 등)
`Content/`	샘플앱 리소스
`Plugins/HybePlatform/`	게임 플랫폼 플러그인
`Source/UnrealStarter/`	샘플 앱 소스 코드

DefaultEngine.ini 설정

SDK에서 참조하는 DefaultEngine.ini 설정 목록입니다.

DefaultEngine.ini
[HybeGamePlatform]
SteamAppId=0
CustomScheme=drimageplatform
iOSGoogleServicePList=Config/Firebase/GoogleService-Info.plist
AndroidGoogleServiceJson=Config/Firebase/google-services.json
EOSCredentialsJson="<<Base64 Encoded EOS Credentials JSON>>"
EOSSupportMode=launcher
EOSCredentialsPath=Config/EOS/eos_credentials.json

Key	Description
`SteamAppId`	스팀 플랫폼을 이용하는 경우 할당된 AppId
`CustomScheme`	앱 외부에서 URI 프로토콜로 데이터를 전달할 때 사용할 앱 고유 스킴
`iOSGoogleServicePList`	iOS Firebase 앱 환경 데이터 plist 파일 위치
`AndroidGoogleServiceJson`	Android Firebase 앱 환경 데이터 json 파일 위치
`EOSCredentialsJson`	Epic(EOS) 인증 JSON (Base64 인코딩)
`EOSSupportMode`	Epic 로그인 연동 모드 (`launcher`, `signin`, `none`)
`EOSCredentialsPath`	개발 전용 EOS 인증 파일 경로

연동 개요

게임 클라이언트는 플랫폼 SDK가 전달하는 이벤트를 수신할 Agent를 구현해야 합니다.

Agent	역할
HybePlatformAuthAgent	인증(로그인·로그아웃·탈퇴·초기화) 이벤트 수신
HybePlatformWebviewAgent	회원가입·약관동의·본인인증 등 웹뷰 이벤트 수신

SDK의 진입점은 HybePlatformAgent 싱글톤입니다. 멤버십 관련 모든 API는 이 클래스를 통해 호출합니다.

로그인 Flow

① - ④ 플랫폼 이벤트 리스너(Auth/Webview Agent)를 등록합니다.
⑤ - ⑧ 저장 경로·언어 설정 후 플랫폼 초기화(Mount)를 수행합니다.
⑨ - ⑫ 초기화 완료 후 자동 로그인을 시도할 수 있습니다.
⑬ - ⑳ 로그인 수단을 선택해 플랫폼 로그인을 요청하고, 신규 회원은 웹뷰를 통해 가입 절차를 진행합니다.
㉑ - ㉓ 게임 서버 접속 전 로그인 토큰을 갱신해 게임 서버에 전달합니다.

멤버십 연동

UnrealStarter 샘플의 InitPage::MountSDK() 흐름을 기준으로 단계별 연동 방법을 설명합니다.

1. Auth Agent 구현

플랫폼 로그인 과정에서 발생하는 이벤트를 수신하기 위해 HybePlatformAuthAgent를 상속합니다.

USPlatformAuthAgent.h
class UNREALSTARTER_API USPlatformAuthAgent : public HybePlatformAuthAgent
{
public:
    virtual void OnMount(bool mounted) override;
    virtual void OnLoginSuccess(const FString& resultJson) override;
    virtual void OnLoginFailure(const FString& resultJson) override;
    virtual void OnLogoutSuccess() override;
    virtual void OnLogoutFailure(const FString& message) override;
    virtual void OnWithDraw() override;
    virtual void OnRefreshVerifyToken(const FString& token) override;
    virtual void OnInspection() override;
    virtual void OnFunnelEvent(const FString& eventName, const FString& paramJson) override;
};

초기화 완료 시 자동 로그인을 시도하는 샘플 구현입니다.

USPlatformAuthAgent.cpp - OnMount
void USPlatformAuthAgent::OnMount(bool mounted)
{
    if (mounted)
    {
        HybePlatformAgent::Instance().DoAutoLogin([this](bool bAutoLogin)
        {
            if (bAutoLogin)
            {
                // 자동 로그인 시도 — 결과는 OnLoginSuccess / OnLoginFailure로 전달
            }
            else
            {
                // 저장된 자동 로그인 정보 없음 — 로그인 UI 표시
            }
        });
    }
}

로그인 성공 시 imid와 loginToken을 파싱해 게임 컨텍스트에 저장합니다.

USPlatformAuthAgent.cpp - OnLoginSuccess
void USPlatformAuthAgent::OnLoginSuccess(const FString& resultJson)
{
    TSharedPtr<FJsonObject> JsonObject;
    TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(resultJson);
    if (FJsonSerializer::Deserialize(Reader, JsonObject) && JsonObject.IsValid())
    {
        auto imid = JsonObject->GetStringField(TEXT("imid"));
        // imid, loginToken을 게임 서버 연동에 사용
    }
}

런처 SSO 자동 로그인 실패(code: 8) 시 게임 종료를 권장합니다.

USPlatformAuthAgent.cpp - OnLoginFailure
void USPlatformAuthAgent::OnLoginFailure(const FString& resultJson)
{
    TSharedPtr<FJsonObject> JsonObject;
    TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(resultJson);
    if (FJsonSerializer::Deserialize(Reader, JsonObject) && JsonObject.IsValid())
    {
        auto code = JsonObject->GetIntegerField(TEXT("code"));
        if (code == 8) // LAUNCHER_SSO_FAIL
        {
            // 런처 연동 로그인 실패 — 게임 종료 처리
            FPlatformMisc::RequestExit(false);
        }
    }
}

2. Webview Agent 구현

회원 가입, 서비스 이용 동의, 본인 확인 등은 웹뷰를 통해 진행됩니다. SDK는 웹뷰를 직접 제공하지 않으며, 게임 클라이언트가 HybePlatformWebviewAgent를 구현해 Show/Close 이벤트를 처리해야 합니다.

경고

플랫폼 SDK는 웹뷰를 직접 제공하지 않습니다.

인게임에서 사용하는 웹뷰를 이용해 로그인 프로세스를 연동해야 합니다. 언리얼 WebBrowser 플러그인 기반 가이드를 제공합니다.

USPlatformWebviewAgent.h
class UNREALSTARTER_API USPlatformWebviewAgent : public HybePlatformWebviewAgent
{
public:
    virtual void OnCloseWebview() override;
    virtual void OnShowWebview(const FString& url) override;
};

USPlatformWebviewAgent.cpp
void USPlatformWebviewAgent::OnShowWebview(const FString& url)
{
    // 게임 UI 스레드에서 웹뷰 팝업
    // 샘플: UGlobalWidgetManager::ShowWebview(url)
}

void USPlatformWebviewAgent::OnCloseWebview()
{
    // 게임 UI 스레드에서 웹뷰 닫기
    // 샘플: UGlobalWidgetManager::CloseWebview()
}

3. 커스텀 웹뷰 구현

정보

Settings > Plugins에서 WebBrowser를 사용하도록 체크합니다.

언리얼 WebBrowser 플러그인을 상속한 커스텀 웹뷰를 추가합니다.

LoginWebBrowser.h
UCLASS()
class UNREALSTARTER_API ULoginWebBrowser : public UWebBrowser
{
    GENERATED_BODY()

public:
    UFUNCTION(BlueprintCallable)
    void PostMessage(FString jsonResponse);

    void PrepareJsBridge();
    void OnConsoleLog(const FString& Message, const FString& Source,
                      int32 Line, EWebBrowserConsoleLogSeverity Severity);
    void OnHandleOnUrlChanged(const FText& InText);
    void ShowWebview(const FString& url);
    void CloseWebview();

protected:
    virtual TSharedRef<SWidget> RebuildWidget() override;
};

URL 변경 시 SDK에 알리고, JavaScript Bridge를 준비합니다.

LoginWebBrowser.cpp
void ULoginWebBrowser::OnHandleOnUrlChanged(const FText& InText)
{
#if PLATFORM_WINDOWS || PLATFORM_MAC
    PrepareJsBridge(); // PC: URL 변경 시마다 바인딩 갱신
#endif
    FString url = InText.ToString();
    HybePlatformAgent::Instance().GetWebviewAgent()->OnUrlChanged(url);
}

void ULoginWebBrowser::PrepareJsBridge()
{
    FString linkName = TEXT("webbridge");
#if PLATFORM_WINDOWS || PLATFORM_MAC
    WebBrowserWidget->BindUObject(linkName, this, false);
#else
    WebBrowserWidget->BindUObject(linkName, this, true);
#endif
}

void ULoginWebBrowser::PostMessage(FString jsonMethod)
{
    HybePlatformAgent::Instance().GetWebviewAgent()->EvalMethod(
        jsonMethod, [this](const FString& resultJson)
        {
            if (!resultJson.IsEmpty())
            {
                FString js = FString::Printf(TEXT("window.unityEventHandler(%s);"), *resultJson);
                ExecuteJavascript(js);
            }
        });
}

void ULoginWebBrowser::ShowWebview(const FString& url)
{
    WebBrowserWidget->LoadURL(url);
    SetVisibility(ESlateVisibility::Visible);
}

void ULoginWebBrowser::CloseWebview()
{
    WebBrowserWidget->LoadURL(TEXT("about:blank"));
    SetVisibility(ESlateVisibility::Hidden);
    HybePlatformAgent::Instance().GetWebviewAgent()->OnNotifyWebviewClose();
}

정보

플랫폼별 BindUObject 설정

플랫폼	세 번째 인자	동작
Windows / macOS	`false`	URL 변경 시 바인딩 해제 → `OnUrlChanged`에서 재바인딩
Android / iOS	`true`	URL 변경 후에도 바인딩 유지

웹뷰 위젯 생성 후 JavaScript Bridge를 초기화합니다.

WebviewWidget.cpp
void UWebviewWidget::InitWithUrl(const FString& url)
{
    if (WebBrowser != nullptr)
    {
        WebBrowser->PrepareJsBridge();
        WebBrowser->ShowWebview(url);
    }
}

4. 플랫폼 초기화

Mount() 호출 전에 Agent 등록, 저장 경로, 언어 설정을 완료합니다. 샘플의 InitPage::MountSDK() 구현을 참고하세요.

InitPage.cpp - MountSDK
void UInitPage::MountSDK()
{
    // 1. Agent 등록
    HybePlatformAgent::Instance().SetPlatformAuthAgent(new USPlatformAuthAgent());
    HybePlatformAgent::Instance().SetPlatformWebviewAgent(new USPlatformWebviewAgent());

    // 2. 로컬 저장 경로 지정 (자동 로그인 등)
    HybePlatformAgent::Instance().SetWritableStorageDirectory(FPaths::ProjectSavedDir());

    // 3. 클라이언트 언어 설정
    HybePlatformAgent::Instance().SetClientLanguage(CachedLanguage);

    // 4. Configuration JSON 준비 후 초기화
    FString JsonString = /* BuildEnv, ProjectId, WebClientId, SteamAppID, SteamIdentity 등 */;
    HybePlatformAgent::Instance().Mount(JsonString);
}

경고

HybePlatformAgent는 게임 플랫폼의 메인 클래스입니다. 멤버십·결제 등 플랫폼 기능은 이 클래스를 통해 제공됩니다.

초기화 결과는 등록한 Auth Agent의 OnMount 이벤트로 전달됩니다.

void USPlatformAuthAgent::OnMount(bool mounted)
{
    if (mounted)
    {
        // 초기화 성공 — 자동 로그인 시도 또는 로그인 UI 표시
    }
    else
    {
        // 초기화 실패 — 설정 정보(BuildEnv, 저장 경로, SteamAppId 등) 확인
    }
}

Platform Configuration에서 JSON 항목을 확인하세요.

5. Custom URI Scheme 등록

Third Party Login(Google, Apple 등) 결과는 Custom URI Scheme으로 앱에 전달됩니다.

DefaultEngine.ini
[HybeGamePlatform]
CustomScheme=drimageplatform

자세한 내용은 Custom URI Scheme을 참고하세요.

6. 플랫폼 로그인

로그인 수단을 선택해 Login()을 호출합니다. 결과는 Auth Agent로 전달됩니다.

LoginPage.cpp
void ULoginPage::HandleLogin(const FString& LoginType)
{
    FString signinMethod = LoginType;
    bool bEnableAutoLogin = AutoLoginCheckBox->IsChecked();

    HybePlatformAgent::Instance().Login(signinMethod, bEnableAutoLogin);
    // 성공: OnLoginSuccess / 실패: OnLoginFailure
}

경고

지원하는 로그인 수단:

GOOGLE, APPLE, LINE, STEAM, IM(이메일), GUEST, EPIC_GAMES

게임별로 로그인 가능한 수단은 달라질 수 있습니다.

7. 게임 서버 로그인 (토큰 갱신)

로그인 성공 후 발급된 loginToken은 약 1시간 동안 유효합니다. 게임 서버 접속 전에 RefreshVerifyToken으로 토큰을 갱신하세요.

AccountPage.cpp
void UAccountPage::OnRefreshTokenButtonClicked()
{
    HybePlatformAgent::Instance().RefreshVerifyToken();
    // 갱신된 토큰: OnRefreshVerifyToken 이벤트로 전달
}

다음 경우에 토큰 갱신이 필요합니다.

로그인 후 즉시 게임 서버에 접속하지 않는 경우 (로비 대기 등)
게임 서버와의 연결이 끊긴 후 재접속하는 경우
비정상 종료 후 로비로 복귀해 재접속하는 경우

정보

OnLoginSuccess에서 바로 RefreshVerifyToken()을 호출하면 FAIL_LOCK_REQUEST 오류가 발생할 수 있습니다. OnLoginSuccess에서 수신한 loginToken은 일정 시간 유효하므로 즉시 갱신할 필요가 없습니다.

웹뷰 사이즈 가이드

경고

PC 웹뷰와 전체화면이 아닌 모바일 웹뷰는 내부 컨텐츠를 정상 표시하기 위해 아래 사이즈 가이드를 준수해야 합니다.

Horizontal 및 PC 기준

가로 (68%): WebView의 Size.X를 0.68 (Percent 또는 Fill 기준)
세로: 디바이스 전체 높이 - 홈 인디케이터 영역 - (16px * 2) (상하 Gutter)

Vertical 기준

가로 (90%): WebView의 Size.X를 0.9
세로: 디바이스 전체 높이 - 상태 바 - 홈 인디케이터 영역 - (16px * 2) - 60px (추가 마진)

float HomeIndicatorHeight = 34.0f; // iPhone 기준 예시
float StatusBarHeight = 44.0f;     // OS에 따라 다름

플랫폼 로그인 (스팀)

멤버십 연동과 기본 흐름은 동일하며, 아래 설정을 추가합니다.

1. Configuration 설정

{
    "SteamAppID": 1234567,
    "SteamIdentity": "sample-qa-00000000"
}

DefaultEngine.ini에 스팀 AppId를 등록합니다.

DefaultEngine.ini
[HybeGamePlatform]
SteamAppId=1234

2. Build.cs DLL 런타임 설정

Windows 빌드 시 스팀 연동에 필요한 DLL이 배포되도록 RuntimeDependencies를 설정합니다.

UnrealStarter.Build.cs
if (Target.Platform == UnrealTargetPlatform.Win64)
{
    RuntimeDependencies.Add("$(BinaryOutputDir)/steam_api64.dll",
        "$(ProjectDir)/Plugins/HybePlatform/Source/ThirdParty/Steam/lib/x64/steam_api64.dll");
    RuntimeDependencies.Add("$(BinaryOutputDir)/steam_agent.dll",
        "$(ProjectDir)/Plugins/HybePlatform/Source/ThirdParty/PlatformSDK/lib/x64/steam_agent.dll");
}

정보

스팀 게임 연동 시 게임 실행과 언리얼 에디터 실행 모두에서 steam_api64.dll, steam_agent.dll이 필요합니다.

스팀을 지원하는 게임의 경우에만 해당 파일이 배포되도록 설정하세요.

3. 스팀 로그인

HybePlatformAgent::Instance().Login(TEXT("STEAM"), false);

플랫폼 로그인 (Epic)

멤버십 연동과 기본 흐름은 동일하며, 아래 설정을 추가합니다.

1. Configuration 설정

DefaultEngine.ini
[HybeGamePlatform]
EOSCredentialsJson="<<Base64 Encoded EOS Credentials JSON>>"
EOSSupportMode=launcher
# 개발 전용
EOSCredentialsPath=Config/EOS/eos_credentials.json

EOSSupportMode	설명
`launcher`	에픽 런처에서 실행한 경우에 한해 로그인 연동(SSO). PROD 빌드 시 반드시 사용
`signin`	에픽 런처 SSO + 게임에서 직접 에픽 로그인 (개발 환경 추천)
`none`	에픽 로그인 미지원 (기본값)

경고

EOSCredentialsJson은 게임별로 제공됩니다. 기술 PM에게 문의하세요.

2. Build.cs DLL 런타임 설정

UnrealStarter.Build.cs
if (Target.Platform == UnrealTargetPlatform.Win64)
{
    RuntimeDependencies.Add("$(BinaryOutputDir)/eos_agent.dll",
        "$(ProjectDir)/Plugins/HybePlatform/Source/ThirdParty/PlatformSDK/lib/x64/eos_agent.dll");
    RuntimeDependencies.Add("$(BinaryOutputDir)/EOSSDK-Win64-Shipping.dll",
        "$(ProjectDir)/Plugins/HybePlatform/Source/ThirdParty/PlatformSDK/lib/x64/EOSSDK-Win64-Shipping.dll");
}

3. 에픽 로그인

HybePlatformAgent::Instance().Login(TEXT("EPIC_GAMES"), false);

경고

스팀·에픽 단일 빌드 지원

단일 빌드로 스팀과 에픽 스토어를 모두 지원하는 경우, 초기화 순서는 에픽 초기화 → 에픽 미지원 시 → 스팀 초기화입니다.

스팀 환경 실행: -ini:Engine:[HybeGamePlatform]:EOSSupportMode=none
에픽 환경 실행: 별도 설정 불필요. 스팀 연동을 비활성화하려면 -ini:Engine:[HybeGamePlatform]:SteamAppId=0

플랫폼 로그인 (Android)

멤버십 연동에 아래 과정을 추가합니다.

1. Configuration 설정

{
    "WebClientId": "xxx-xxxx-xxx"
}

정보

WebClientId는 퍼블리셔 개발 환경 구성 후 설정 정보와 함께 개발사로 전달됩니다. 설정하지 않으면 Google 로그인이 실패합니다.

2. 앱 사이닝

Project Settings > Platforms > Android > Distribution Signing에 사이닝 키스토어를 설정합니다.

정보

사이닝을 적용하지 않으면 Google 로그인 인증이 실패합니다.

3. 로그인

HybePlatformAgent::Instance().Login(TEXT("GOOGLE"), false);

플랫폼 로그인 (iOS)

멤버십 연동과 동일합니다. Apple 로그인·푸시·결제를 위해 iOS Capability 설정을 추가하세요.

게스트 로그인

Guest 계정은 임시 회원으로, 특정 서비스만 이용할 수 있는 계정입니다.

HybePlatformAgent::Instance().Login(TEXT("GUEST"), false);

정보

Guest 계정은 개인정보를 수집·저장하지 않으며, 연령 확인 등 개인정보 수집이 필요한 서비스 환경에서는 지원할 수 없습니다.

Guest 계정으로는 플랫폼 결제를 이용할 수 없습니다.

일반 회원 전환

Guest 계정에 일반 인증 수단을 연결하면 일반 계정으로 전환됩니다. 샘플에서는 로그인 페이지에서 ConvertMember 모드로 전환합니다.

LoginPage.cpp
HybePlatformAgent::Instance().ConvertMember(signinMethod, TEXT(""),
    [](FString result)
    {
        if (result == HybePlatform::ResultCode::SUCCESS)
        {
            // 일반 계정 전환 완료
        }
    });

자동 로그인

Login() 호출 시 두 번째 인자로 자동 로그인 지원 여부를 설정합니다.

bool bSupportAutoLogin = true;
HybePlatformAgent::Instance().Login(TEXT("GOOGLE"), bSupportAutoLogin);

true로 설정하면 로그인 정보가 로컬에 저장되며, 초기화 이후 DoAutoLogin()으로 자동 로그인을 시도할 수 있습니다.

HybePlatformAgent::Instance().DoAutoLogin([](bool bAutoLogin)
{
    if (bAutoLogin)
    {
        // 자동 로그인 시도 — 결과는 OnLoginSuccess / OnLoginFailure
    }
    else
    {
        // 저장된 로그인 정보 없음
    }
});

런처 자동 로그인

런처를 통해 게임이 실행되는 경우, DoAutoLogin()에서 런처 인증 정보로 자동 로그인을 시도합니다.

위험

런처 인증 토큰으로 자동 로그인이 실패하면 OnLoginFailure에 에러 코드 LAUNCHER_SSO_FAIL(8)이 전달됩니다. 이 경우 게임을 종료하도록 처리해야 합니다.

플랫폼 로그아웃

HybePlatformAgent::Instance().Signout();

로그아웃 결과는 Auth Agent로 전달됩니다.

성공: OnLogoutSuccess
실패: OnLogoutFailure

정보

Signout()을 호출하면 저장된 자동 로그인 정보가 삭제됩니다.

경고

로그아웃이 필요한 경우

타이틀로 이동 후 다른 계정으로 다시 로그인하는 경우
자동 로그인 정보를 삭제하고자 하는 경우

강제 초기화가 필요한 경우 ForceSignout()을 사용합니다. 백엔드 로그아웃 없이 로컬 로그인 정보를 즉시 초기화합니다.

AccountPage.cpp
HybePlatformAgent::Instance().ForceSignout();

탈퇴

HybePlatformAgent::Instance().Withdraw();

탈퇴 프로세스용 웹뷰가 팝업되고, 완료 시 OnWithDraw가 호출됩니다.

void USPlatformAuthAgent::OnWithDraw()
{
    // 탈퇴된 계정은 Signout()으로 로그아웃할 수 없음
    HybePlatformAgent::Instance().ForceSignout();
}

정보

탈퇴 완료 후 다른 계정으로 로그인하려면 ForceSignout()으로 로그인 정보를 초기화해야 합니다.

푸시 연동

모바일 환경에서 Firebase Cloud Messaging(FCM) 연동 기능을 제공합니다.

정보

Firebase 설정용 Android/iOS 설정 파일은 담당 기술 PM에게 문의하세요.

Android

google-services.json을 프로젝트에 복사합니다. 기본 경로: Config/Firebase/google-services.json
DefaultEngine.ini의 AndroidGoogleServiceJson으로 경로를 변경할 수 있습니다.
UPL.xml에 google-services 패키지를 지정합니다.

<buildscriptGradleAdditions>
  <insert>
    dependencies {
      classpath 'com.google.gms:google-services:4.3.15'
    }
  </insert>
</buildscriptGradleAdditions>

정보

Android 13 이상에서는 게임 시작 시 푸시 허용 팝업이 자동으로 노출되도록 설정되어 있습니다.

iOS

GoogleService-Info.plist를 프로젝트에 복사합니다. 기본 경로: Config/Firebase/GoogleService-Info.plist
푸시 수신을 위해 iOS Capability 설정을 반드시 적용하세요.

점검

게임이 점검 상태인 경우 초기화(Mount) 과정에서 두 가지 이벤트가 전달됩니다.

OnShowWebview: 점검 페이지 URL
OnInspection: 점검 상태 알림

void USPlatformAuthAgent::OnInspection()
{
    mIsInspection = true;
}

void USPlatformAuthAgent::OnMount(bool mounted)
{
    if (mounted && mIsInspection)
    {
        mIsInspection = false;
        // 점검 중 UI 처리
    }
}

경고

OnShowWebview → OnInspection → OnMount 순서로 호출됩니다.

OnMount는 점검 상태를 전달하지 않으므로, OnInspection에서 점검 플래그를 별도로 관리하세요.

Remote Play 연동

언리얼 Pixel Streaming을 이용한 원격 플레이를 지원합니다.

1. PixelStreaming 플러그인 활성화

Settings > Plugins > PixelStreaming을 체크한 후 에디터를 재시작합니다.

2. RemotePlayConnector 플러그인 추가

SDK에 포함된 RemotePlayConnector를 Plugins 폴더에 복사합니다.
.uproject의 Modules에 RemotePlayConnector를 추가합니다.

"AdditionalDependencies": [
    "UMG",
    "WebBrowserWidget",
    "HybePlatform",
    "RemotePlayConnector"
]

3. 이벤트 핸들러 등록

#include "RemotePlaySubsystem.h"

URemotePlaySubsystem* RemotePlaySubsystem =
    GetGameInstance()->GetSubsystem<URemotePlaySubsystem>();
if (RemotePlaySubsystem)
{
    RemotePlaySubsystem->OnClientConnected().AddLambda([]()
    {
        // 원격 플레이어 접속 — 모바일 환경에 맞게 UI 조정
    });

    RemotePlaySubsystem->OnClientDisconnected().AddLambda([]()
    {
        // 원격 플레이어 접속 해제
    });
}

정보

Pixel Streaming 서버 연결은 게임 초기 단계에서 시도되므로, 이벤트 핸들러는 게임 시작 시점에 등록해야 합니다.

퍼널 이벤트 연동

플랫폼 SDK 연동 과정에서 발생하는 퍼널 이벤트는 Auth Agent의 OnFunnelEvent로 전달됩니다.

void USPlatformAuthAgent::OnFunnelEvent(const FString& eventName, const FString& paramJson)
{
    // 게임별 퍼널 로그 스펙에 맞게 기록
}

eventName	설명
`PLATFORM_CERT_REQ`	서비스 이용 동의 화면 노출
`PLATFORM_CERT_COMP`	서비스 이용 동의 완료
`PHONE_CERT_REQ`	본인 인증 시작
`PHONE_CERT_COMP`	본인 인증 완료
`PHONE_CERT_FAIL`	본인 인증 실패

로그 연동

게임 클라이언트는 플레이 과정에서 발생하는 유저의 행동 로그를 수집하여 전달해야 합니다. 전달하는 로그의 명세는 별도로 전달되는 로그 명세서를 참고하세요.

로그 전송 과정은 다음 2단계로 구분할 수 있습니다.

로그 데이터 수집 — 로그 JSON 생성
로그 전송 — 생성된 JSON을 로그 서버로 전송

로그 데이터(JSON) 수집

로그 JSON은 로그 명세서를 참고하여 직접 생성하거나, 플러그인에서 제공하는 기능을 사용할 수 있습니다.

클래스	역할
LogneticAgent	공통 로그 등록 및 로그 전송
LogneticEvent	로그 JSON 생성

정보

LogneticEvent는 로그 JSON을 생성하는 편의 기능을 제공합니다.

각 프로젝트별로 로그 JSON을 생성하는 별도의 기능이 있는 경우 해당 기능을 사용하면 됩니다.

로그 속성 종류

로그 속성	설명	예
공통 속성	모든 로그에 추가되는 공통 속성	`os_type`, `service_id`
자동 생성 속성	로그 JSON 생성 시 현재 시간(UTC)으로 자동 추가(ISO8601)	`cre_time`
클라이언트 생성 속성	로그 명세서에 따른 클라이언트 로그	`log_type`

아래 포맷의 JSON 로그를 생성하는 경우를 예로 들 수 있습니다.

{
    "log_type": "LOGIN_COMP",
    "os_type": 1,
    "service_id": "10060000",
    "external_device_type": 0,
    "external_device_id": "b845158f4d599d791ca22790151cd473",
    "cre_time": "2024-06-13T08:02:27.014000Z"
}

공통 속성 등록

공통 속성은 1회 등록하면 LogneticEvent를 사용하는 경우 JSON 생성 시 자동으로 추가됩니다. 게임 초기화 시점에 한 번 등록하는 것을 권장합니다.

StarterLognetic.cpp
void StarterLognetic::Prepare()
{
    Lognetic().SetCommon(TEXT("os_type"), 1);
    Lognetic().SetCommon(TEXT("service_id"), TEXT("12010000"));
    Lognetic().SetCommon(TEXT("external_device_type"), 0);
    Lognetic().SetCommon(TEXT("external_device_id"), FPlatformMisc::GetLoginId());
}

정보

Lognetic()은 LogneticAgent 싱글톤 인스턴스에 접근하는 매크로입니다.

개별 속성 등록

로그 명세서에 정의된 클라이언트 속성은 Set()으로 개별 등록합니다.

LogneticEvent()
    .Set(TEXT("log_type"), TEXT("LOGIN_COMP"));

로그 JSON 생성

ToJson()은 등록된 속성을 JSON 문자열로 변환합니다. 공통 속성과 생성 시간(cre_time)이 자동으로 추가됩니다.

FString logJson = LogneticEvent()
    .Set(TEXT("log_type"), TEXT("LOGIN_COMP"))
    .ToJson();

전송 없이 JSON만 확인하거나, 별도의 전송 로직과 연동할 때 사용합니다.

로그 JSON 생성 및 전송

Send()는 JSON을 생성한 뒤 로그 서버로 전송합니다. 1개의 로그를 즉시 전송할 때 사용합니다.

LogneticEvent()
    .Set(TEXT("log_type"), TEXT("LOGIN_COMP"))
    .Send();

중첩 구조 로그

객체(AddObject)와 배열(AddArray)을 조합하여 중첩 구조의 로그를 생성할 수 있습니다.

{
  "log_type": "LOGOUT",
  "os_type": 1,
  "service_id": "10060000",
  "external_device_type": 0,
  "external_device_id": "b845158f4d599d791ca22790151cd473",
  "cre_time": "2024-06-13T08:02:27.015000Z",
  "online_play": {
    "play_cnts": 5,
    "play_details": [
      {
        "dungeon_type": "10",
        "dungeon_id": "1",
        "scale": 2
      },
      {
        "dungeon_type": "20",
        "dungeon_id": "2",
        "scale": 5
      }
    ]
  }
}

AddObject()로 하위 속성 객체를, AddArray()로 배열 속성을 추가합니다.

LogneticEvent logoutLog;
logoutLog.Set(TEXT("log_type"), TEXT("LOGOUT"));

auto& onlinePlay = logoutLog.AddObject(TEXT("online_play"));
onlinePlay.Set(TEXT("play_cnts"), 5);
onlinePlay.AddArray(TEXT("play_details")) // online_play/play_details[0]
    .Set(TEXT("dungeon_type"), TEXT("10"))
    .Set(TEXT("dungeon_id"), TEXT("1"))
    .Set(TEXT("scale"), 2);
onlinePlay.AddArray(TEXT("play_details")) // online_play/play_details[1]
    .Set(TEXT("dungeon_type"), TEXT("20"))
    .Set(TEXT("dungeon_id"), TEXT("2"))
    .Set(TEXT("scale"), 5);
logoutLog.Send();

JSON 로그 전송

1개 이상의 수집한 로그를 전송하는 방법입니다.

단일 로그를 생성하면서 전송

LogneticEvent 사용

LogneticEvent()
    .Set(TEXT("log_type"), TEXT("LOGIN_COMP"))
    .Send();

LogneticAgent 사용 — JSON을 먼저 생성한 뒤 전송합니다.

FString logJson = LogneticEvent()
    .Set(TEXT("log_type"), TEXT("LOGIN_COMP"))
    .ToJson();
Lognetic().SendEvent(logJson);

1개 이상 로그를 전송

여러 로그를 한 번에 전송하면 네트워크 요청 횟수를 줄일 수 있습니다.

FString logJson = LogneticEvent()
    .Set(TEXT("log_type"), TEXT("LOGIN_COMP"))
    .ToJson();
FString logJson2 = LogneticEvent()
    .Set(TEXT("log_type"), TEXT("LOGOUT"))
    .ToJson();
TArray<FString> logs = {logJson, logJson2};
Lognetic().SendEvent(logs);

API 상세는 LogneticEvent, LogneticAgent를 참고하세요.

API Reference

Platform Configuration

Mount()에 전달하는 실행 환경 JSON 정보입니다.

{
    "BuildEnv": "qa",
    "ProjectId": "0000",
    "WebClientId": "xxx",
    "SteamAppID": 0,
    "SteamIdentity": "sample-qa-00000000"
}

Key	설명	예시
`BuildEnv`	개발 환경	`qa`, `prod`
`ProjectId`	기술 PM에게 전달받은 ProjectID	`1000`
`WebClientId`	기술 PM에게 전달받은 Google WebClientID
`SteamAppID`	기술 PM에게 전달받은 SteamAppID
`SteamIdentity`	기술 PM에게 전달받은 스팀 인증 토큰

Custom URI Scheme

Google, Apple 등 Third Party Login 결과는 Custom URI Scheme으로 앱에 전달됩니다.

DefaultEngine.ini
[HybeGamePlatform]
CustomScheme=drimageplatform

경고

URI Scheme 이름은 알파벳으로 시작해야 하며, 소문자/숫자/+, -, .만 허용됩니다.

예: myapp+v1://은 유효하지만, 1app://은 허용되지 않습니다.

HybePlatformAgent

게임 플랫폼의 메인 클래스입니다. 결제를 제외한 대부분의 플랫폼 기능을 제공합니다.

Mount

플랫폼 SDK 플러그인 초기화를 수행합니다.

void Mount(const FString& configJson) const

configJson: 설정 정보 JSON 문자열
초기화 결과: Auth Agent의 OnMount로 전달

플랫폼 로그인을 수행합니다.

void Login(const FString& signinMethod, bool bEnableAutologin) const

signinMethod: STEAM, GOOGLE, APPLE, LINE, EPIC_GAMES, IM, GUEST
bEnableAutologin: 자동 로그인 정보 저장 여부
결과: OnLoginSuccess / OnLoginFailure

DoAutoLogin

저장된 로그인 정보로 자동 로그인을 시도합니다.

void DoAutoLogin(std::function<void(bool)> callback) const

callback: 자동 로그인 시도 여부 (true: 시도함, false: 저장 정보 없음)
로그인 결과: OnLoginSuccess / OnLoginFailure

경고

에픽 런처를 통해 게임을 실행한 경우, 자동 로그인 실패 시 게임을 종료하도록 처리해야 합니다.

Signout

플랫폼 로그아웃을 수행합니다. 저장된 자동 로그인 정보도 삭제됩니다.

void Signout() const

결과: OnLogoutSuccess / OnLogoutFailure

ForceSignout

백엔드 연동 없이 로컬 로그인 정보를 즉시 초기화합니다.

void ForceSignout() const

결과: OnLogoutSuccess
자동 로그인 정보는 초기화하지 않습니다.

ConvertMember

게스트 회원을 일반 회원으로 전환합니다.

void ConvertMember(const FString& signinMethod, const FString& yyyyMMdd,
                   std::function<void(FString)> callback) const

signinMethod: STEAM, GOOGLE, APPLE, LINE, IM
yyyyMMdd: (선택) 생년월일, 예) 20021010

ShowRequireGuestBirthDay

생년월일 입력 웹뷰를 팝업합니다.

void ShowRequireGuestBirthDay(std::function<void(FString)> callback) const

callback: 입력 결과 (yyyyMMdd). 취소 시 빈 문자열

RefreshVerifyToken

로그인 토큰을 갱신합니다. 갱신된 토큰은 OnRefreshVerifyToken으로 전달됩니다.

void RefreshVerifyToken() const

Withdraw

계정 탈퇴를 요청합니다. 탈퇴 웹뷰가 팝업되고 결과는 OnWithDraw로 전달됩니다.

void Withdraw() const

GetLocationCode

현재 사용자의 접속 국가 코드를 반환합니다 (ISO 3166-1 alpha-2).

FString GetLocationCode() const

SetClientLanguage

SDK에 클라이언트 언어를 설정합니다. 웹뷰 다국어에 반영됩니다.

void SetClientLanguage(const FString& language) const

language: ISO 639-1 (ko, en, ja, zh-tw)

SetWritableStorageDirectory

SDK 로컬 데이터 저장 경로를 설정합니다.

void SetWritableStorageDirectory(const FString& dir) const

GetSteamInfo

스팀 사용자 정보를 반환합니다 (Windows).

HybePlatform::SteamInfo GetSteamInfo() const

class SteamInfo
{
public:
    UINT64 Id;            // User ID
    FString Language;     // 스팀 API 언어코드 (ISO 639-1)
    FString Currency;     // 통화코드 (KRW, USD 등)
    INT AppBuildId;       // 앱 빌드 ID
};

GetAgreementStatus / UpdateAgreement

약관 동의 정보를 조회·업데이트합니다.

static void GetAgreementStatus(std::function<void(HybePlatform::AgreementPayload)> callback)
static void UpdateAgreement(const HybePlatform::AgreementPayload& payload,
                            std::function<void(bool, HybePlatform::AgreementPayload)> callback)

class AgreementPayload
{
public:
    bool advertising;    // 마케팅 수신 동의
    bool adPush;         // 앱 푸시 수신 동의
    bool adNightPush;    // 야간 푸시 수신 동의
};

GetUrl

인게임에서 사용하는 URL을 조회합니다.

static FString GetUrl(const FString& urlType, const FString& language = TEXT(""))

용도	url 타입
개인정보 처리방침	`URLKey::PRIVACY_POLICY`
계정 센터	`URLKey::MYPAGE`
약관 보기	`URLKey::TERMS_OF_SERVICE`
공지사항	`URLKey::NOTICE`
고객센터	`URLKey::CS`
홈페이지	`URLKey::HOMEPAGE`
한도 조회	`URLKey::PAYMENT_LIMIT`
일본 연령 확인	`URLKey::BIRTH_REQUIRED`
쿠폰 등록	`URLKey::COUPON`
거래 내역	`URLKey::TRANSACTION_HISTORY`

GetVersion / GetLastSigninTag

static FString GetVersion();
static FString GetLastSigninTag();

GetLastSigninTag() 반환 예시:

{
    "maskedEmail": "ma***@gmail.com",
    "method": "GOOGLE"
}

Agent 등록

void SetPlatformAuthAgent(HybePlatformAuthAgent* authAgent)
void SetPlatformWebviewAgent(HybePlatformWebviewAgent* webviewAgent)
void SetPlatformBillingAgent(HybePlatform::HybeBillingAgent* billingAgent)
HybePlatformAuthAgent* GetAuthAgent() const
HybePlatformWebviewAgent* GetWebviewAgent() const

HybePlatformAuthAgent

플랫폼 로그인 연동 이벤트 리스너. 게임 클라이언트에서 반드시 상속 구현해야 합니다.

OnLoginSuccess

로그인 성공 시 호출됩니다.

void OnLoginSuccess(const FString& resultJson)

{
    "imid": "4M87F6H5GFFZDPY8QM97",
    "loginToken": "xxx-xxx",
    "countryCode": "KR"
}

키	설명
`imid`	게임별 유저 ID
`loginToken`	게임 서버 인증용 토큰. RefreshVerifyToken으로 갱신 가능
`countryCode`	가입 국가 코드 (ISO 3166-1 alpha-2)

OnLoginFailure

로그인 실패 시 호출됩니다.

void OnLoginFailure(const FString& resultJson)

{
    "message": "Login Cancel",
    "code": 2
}

Code	상수	설명
0	`UNKNOWN_ERROR`	알 수 없는 오류
1	`NO_INITIALIZE`	초기화되지 않음
2	`SIGNIN_FAIL`	Google/Apple/Line 등 3rd Party Signin 실패
3	`PLATFORM_LOGIN_FAIL`	플랫폼 로그인 실패
4	`AUTO_LOGIN_FAIL`	자동 로그인 실패
5	`WITHDRAW_ACCOUNT`	탈퇴 회원
6	`CANCELED`	로그인 취소
7	`SIGNUP_FAIL`	회원가입 실패
8	`LAUNCHER_SSO_FAIL`	런처 SSO 실패

정보

에러 메시지는 개발 단계 로그 용도이며, 유저에게 직접 노출하지 않습니다.

OnLogoutSuccess

Signout / ForceSignout 성공 시 호출됩니다.

OnLogoutFailure

Signout 실패 시 호출됩니다.

OnMount

Mount 초기화 결과를 수신합니다.

void OnMount(bool mounted)

초기화 실패 시 확인 사항:

Platform Configuration의 BuildEnv 유효성
SetWritableStorageDirectory 경로 유효성
스팀 게임인 경우 SteamAppId 설정 여부

OnRefreshVerifyToken

RefreshVerifyToken 갱신 결과를 수신합니다.

void OnRefreshVerifyToken(const FString& token)

OnWithDraw

Withdraw 탈퇴 완료 시 호출됩니다.

OnInspection

초기화 시 점검 상태를 수신합니다. OnMount보다 먼저 호출됩니다.

OnMessageReceived

void OnMessageReceived(HybePlatform::PlatformMessage messageType)

messageType	설명
`NOT_ALLOWED_COUNTRY (1)`	접속 국가 제한

OnFunnelEvent

void OnFunnelEvent(const FString& eventName, const FString& paramJson)

HybePlatformWebviewAgent

인증 과정의 웹뷰 이벤트를 제공합니다.

OnShowWebview

웹뷰 팝업 요청. 지정된 URL로 웹뷰를 표시해야 합니다.

void OnShowWebview(const FString& url)

OnCloseWebview

웹뷰 닫기 요청. 화면의 웹뷰를 닫아야 합니다.

void OnCloseWebview()

EvalMethod / OnUrlChanged / OnNotifyWebviewClose

커스텀 웹뷰 구현 시 JavaScript Bridge 통신에 사용합니다.

void EvalMethod(const FString& actionJson, std::function<void(const FString&)> callback)
bool OnUrlChanged(const FString& url)
void OnNotifyWebviewClose()

LogneticEvent

로그 JSON을 생성하는 편의 클래스입니다.

Set

속성을 추가합니다.

template<typename T>
LogneticEvent& Set(const FString& key, T value)

파라미터	설명
`key`	속성명
`value`	속성 값 (`int`, `unsigned int`, `int64_t`, `uint64_t`, `float`, `double`, `FString` 지원)

반환: LogneticEvent 객체 (메서드 체이닝 가능)

AddObject

하위 로그 이벤트 객체를 생성합니다. 지정된 키(key)에 하위 객체를 등록합니다.

LogneticEvent& AddObject(const FString& key)

파라미터	설명
`key`	하위 이벤트 키 값

반환: 추가된 하위 이벤트 객체

LogneticEvent().Set(TEXT("log_type"), TEXT("LOGOUT"))
    .AddObject(TEXT("online_play"))
    .Set(TEXT("play_cnts"), 5)
    .ToJson();

JSON 생성 결과
{
  "log_type": "LOGOUT",
  "cre_time": "2024-06-13T08:02:27.015000Z",
  "online_play": {
    "play_cnts": 5
  }
}

경고

AddObject()는 새로 추가된 이벤트 객체를 반환합니다. 체이닝(chaining)으로 호출하면 반환된 이벤트에 속성이 추가됩니다.

AddObject()를 연속으로 호출하면 이전에 추가된 객체의 하위로 중첩되므로 주의가 필요합니다.

LogneticEvent().Set(TEXT("log_type"), TEXT("LOGOUT"))
    .AddObject(TEXT("online_play"))
    .Set(TEXT("play_cnts"), 5)
    .AddObject(TEXT("item_info"))   // online_play 하위에 item_info가 생성됨
    .Set(TEXT("type"), TEXT("bag"))
    .ToJson();

JSON 생성 결과
{
  "log_type": "LOGOUT",
  "cre_time": "2024-06-13T08:02:27.015000Z",
  "online_play": {
    "play_cnts": 5,
    "item_info": {
      "type": "bag"
    }
  }
}

동일 경로의 하위 이벤트를 루트에 추가하려면 참조를 분리합니다.

LogneticEvent logoutLog;
logoutLog.Set(TEXT("log_type"), TEXT("LOGOUT"));

auto& onlinePlay = logoutLog.AddObject(TEXT("online_play"));
onlinePlay.Set(TEXT("play_cnts"), 5);
auto& itemInfo = logoutLog.AddObject(TEXT("item_info")); // 루트에 생성됨
itemInfo.Set(TEXT("type"), TEXT("bag"));

logoutLog.ToJson();

JSON 생성 결과
{
  "log_type": "LOGOUT",
  "cre_time": "2024-06-13T08:02:27.015000Z",
  "online_play": {
    "play_cnts": 5
  },
  "item_info": {
    "type": "bag"
  }
}

AddArray

배열에 추가되는 로그 이벤트 객체를 생성합니다. 지정된 키(key)의 배열 마지막 아이템으로 등록됩니다. 동일한 키로 호출할 때마다 배열에 새 이벤트 객체가 추가됩니다.

LogneticEvent& AddArray(const FString& key)

파라미터	설명
`key`	하위 이벤트 키 값

반환: 추가된 하위 이벤트 객체

배열 1개 이벤트 추가
LogneticEvent log;
log.Set(TEXT("log_type"), TEXT("LOGOUT"))
   .AddArray(TEXT("play_details"))
   .Set(TEXT("dungeon_type"), TEXT("10"))
   .Set(TEXT("scale"), 2);
log.ToJson();

JSON 생성 결과
{
  "log_type": "LOGOUT",
  "play_details": [
    {
      "dungeon_type": "10",
      "scale": 2
    }
  ]
}

배열 2개 이벤트 추가
LogneticEvent log;
log.Set(TEXT("log_type"), TEXT("LOGOUT"))
   .AddArray(TEXT("play_details"))
   .Set(TEXT("dungeon_type"), TEXT("10"))
   .Set(TEXT("scale"), 2);
log.AddArray(TEXT("play_details"))
   .Set(TEXT("dungeon_type"), TEXT("20"))
   .Set(TEXT("scale"), 5);
log.ToJson();

JSON 생성 결과
{
  "log_type": "LOGOUT",
  "play_details": [
    {
      "dungeon_type": "10",
      "scale": 2
    },
    {
      "dungeon_type": "20",
      "scale": 5
    }
  ]
}

ToJson

등록된 속성을 JSON 문자열로 변환합니다. 공통 속성과 cre_time이 자동으로 추가됩니다.

FString ToJson()

Send

로그를 서버에 전송합니다. 아래 작업을 수행합니다.

공통 속성 추가
로그 생성 시간(cre_time) 추가
JSON 변환 후 로그 서버로 전송

void Send()

LogneticAgent

JSON 로그를 서버에 전송하는 기능을 제공합니다.

경고

LogneticEvent를 사용하지 않고, 로그 JSON을 직접 생성하는 경우에 SendEvent()를 사용할 수 있습니다.

SendEvent

JSON 로그를 서버에 전송합니다.

void SendEvent(const FString& json)
void SendEvent(TArray<FString> jsons)

파라미터	설명
`json`	전송할 JSON 로그
`jsons`	전송할 JSON 로그 배열

FString myLog = BuildCustomLog();
LogneticAgent::Instance().SendEvent(myLog); // 동일: Lognetic().SendEvent(myLog)

정보

1개 이상의 로그를 전송할 때는 TArray<FString> 오버로드를 사용하세요. 로그 전송은 요청마다 개별로 서버에 전달되므로, 여러 로그를 한꺼번에 요청하는 것이 효율적입니다.

1개 이상 로그 전송
FString myLog = BuildCustomLog();
FString myLog2 = BuildCustomLog2();
TArray<FString> logs = {myLog, myLog2};
LogneticAgent::Instance().SendEvent(logs); // 동일: Lognetic().SendEvent(logs)

SetCommon

모든 로그에 공통으로 포함될 속성을 설정합니다.

template<typename T>
void SetCommon(const FString& key, T value)

파라미터	설명
`key`	속성명
`value`	속성 값

공통 속성은 1회 등록하면 LogneticEvent 사용 시 JSON 생성에 자동으로 포함됩니다.

LogneticAgent::Instance().SetCommon(TEXT("os_type"), 1);
LogneticAgent::Instance().SetCommon(TEXT("service_id"), TEXT("10060000"));
LogneticAgent::Instance().SetCommon(TEXT("external_device_type"), 0);
LogneticAgent::Instance().SetCommon(TEXT("external_device_id"), FPlatformMisc::GetLoginId());

Lognetic

LogneticAgent 싱글톤 인스턴스에 접근하는 매크로입니다.

#define Lognetic() LogneticAgent::Instance()

URemotePlaySubsystem

메서드	설명
OnClientConnected()	원격 플레이어 접속
OnClientDisconnected()	원격 플레이어 접속 해제

DevUtil

개발 단계에서 테스트 용도로 제공되는 클래스.

메서드	설명
SetXsollaCountryCode(FString countryCode)	Xsolla 결제 시 결제 국가 설정
SetMyCardCountryCode(FString countryCode)	MyCard 결제 시 결제 국가 설정

Troubleshooting

플러그인 초기화 실패

steam_api64.dll 파일이 실행 폴더에 있는지 확인하세요.

Android Google 로그인 실패 (Login cancel)

앱 사이닝 적용 후 다시 빌드하세요.
Configuration의 WebClientId가 현재 환경에 등록된 값인지 확인하세요.

iOS Capability 설정

iOS에서 Apple 로그인, 푸시, 결제를 지원하려면 Xcode > Signing & Capabilities에서 아래 항목을 추가합니다.

Sign in with Apple
Push Notifications
In-App Purchase
Background Modes
- Remote notifications
- Background fetch
Extended Virtual Addressing

요구사항​

연동 준비​

SDK 설치​

UnrealStarter 샘플 프로젝트​

샘플 실행 환경 설정​

샘플 디렉토리 구조​

DefaultEngine.ini 설정​

연동 개요​

로그인 Flow​

멤버십 연동​

1. Auth Agent 구현​

2. Webview Agent 구현​

3. 커스텀 웹뷰 구현​

4. 플랫폼 초기화​

5. Custom URI Scheme 등록​

6. 플랫폼 로그인​

7. 게임 서버 로그인 (토큰 갱신)​

웹뷰 사이즈 가이드​

플랫폼 로그인 (스팀)​

1. Configuration 설정​

2. Build.cs DLL 런타임 설정​

3. 스팀 로그인​

플랫폼 로그인 (Epic)​

1. Configuration 설정​

2. Build.cs DLL 런타임 설정​

3. 에픽 로그인​

스팀·에픽 단일 빌드 지원​

플랫폼 로그인 (Android)​

1. Configuration 설정​

2. 앱 사이닝​

3. 로그인​

플랫폼 로그인 (iOS)​

게스트 로그인​

일반 회원 전환​

자동 로그인​

런처 자동 로그인​

플랫폼 로그아웃​

탈퇴​

푸시 연동​

Android​

iOS​

점검​

Remote Play 연동​

1. PixelStreaming 플러그인 활성화​

2. RemotePlayConnector 플러그인 추가​

3. 이벤트 핸들러 등록​

퍼널 이벤트 연동​

로그 연동​

로그 데이터(JSON) 수집​

로그 속성 종류​

공통 속성 등록​

개별 속성 등록​

로그 JSON 생성​

로그 JSON 생성 및 전송​

중첩 구조 로그​

JSON 로그 전송​

단일 로그를 생성하면서 전송​

1개 이상 로그를 전송​

API Reference​

Platform Configuration​

Custom URI Scheme​

HybePlatformAgent​

Mount​

Login​

DoAutoLogin​

Signout​

ForceSignout​

ConvertMember​

ShowRequireGuestBirthDay​

RefreshVerifyToken​

Withdraw​

GetLocationCode​

SetClientLanguage​

SetWritableStorageDirectory​

GetSteamInfo​

GetAgreementStatus / UpdateAgreement​

GetUrl​

GetVersion / GetLastSigninTag​

Agent 등록​

HybePlatformAuthAgent​

요구사항

연동 준비

SDK 설치

UnrealStarter 샘플 프로젝트

샘플 실행 환경 설정

샘플 디렉토리 구조

DefaultEngine.ini 설정

연동 개요

로그인 Flow

멤버십 연동

1. Auth Agent 구현

2. Webview Agent 구현

3. 커스텀 웹뷰 구현

4. 플랫폼 초기화

5. Custom URI Scheme 등록

6. 플랫폼 로그인

7. 게임 서버 로그인 (토큰 갱신)

웹뷰 사이즈 가이드

플랫폼 로그인 (스팀)

1. Configuration 설정

2. Build.cs DLL 런타임 설정

3. 스팀 로그인

플랫폼 로그인 (Epic)

1. Configuration 설정

2. Build.cs DLL 런타임 설정

3. 에픽 로그인

스팀·에픽 단일 빌드 지원

플랫폼 로그인 (Android)

1. Configuration 설정

2. 앱 사이닝

3. 로그인

플랫폼 로그인 (iOS)

게스트 로그인

일반 회원 전환

자동 로그인

런처 자동 로그인

플랫폼 로그아웃

탈퇴

푸시 연동

Android

iOS

점검

Remote Play 연동

1. PixelStreaming 플러그인 활성화

2. RemotePlayConnector 플러그인 추가

3. 이벤트 핸들러 등록

퍼널 이벤트 연동

로그 연동

로그 데이터(JSON) 수집

로그 속성 종류

공통 속성 등록

개별 속성 등록

로그 JSON 생성

로그 JSON 생성 및 전송

중첩 구조 로그

JSON 로그 전송

단일 로그를 생성하면서 전송

1개 이상 로그를 전송

API Reference

Platform Configuration

Custom URI Scheme

HybePlatformAgent

Mount

Login

DoAutoLogin

Signout

ForceSignout

ConvertMember

ShowRequireGuestBirthDay

RefreshVerifyToken

Withdraw

GetLocationCode

SetClientLanguage

SetWritableStorageDirectory

GetSteamInfo

GetAgreementStatus / UpdateAgreement

GetUrl

GetVersion / GetLastSigninTag

Agent 등록

HybePlatformAuthAgent