Unreal Engine 멤버십

Unreal Engine에서 Hybe Game Platform Service(이하, 플랫폼, Platform) 연동을 위한 SDK 사용법에 대해서 설명합니다.

환경 구성

개발 환경

Platform SDK를 사용하기 위한 요구 사항은 아래와 같습니다.

• OS : Windows, MacOS

• Enreal Engine : 5.2.x 이상

• Visual Studio 2022 권장

플랫폼 SDK는 언리얼 플러그인으로 제공되고 있습니다.

Unreal Engine 5.2.1, 5.4.4 에서 테스트 되었습니다.

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

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

SDK 설치

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

UnrealStarter 샘플 프로젝트

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

1. UnrealStarter_x.x.x.zip 파일을 압축 해제합니다. 샘플앱 프로젝트는 5.2.1 환경으로 제공됩니다.

2. UnrealStarter.uproject 파일에서 오른쪽을 버튼을 이용해서 Visual Studio 솔루션 파일을 생성합니다.

   
3. Visual Studio 솔루션 파일을 오픈 합니다.

4. 게임 접속 환경 설정 후 빌드 합니다.

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

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

[Switch Unreal Engine version...]을 선택한 후, [Select Unreal Engine Version] 에서 5.4를 선택한 후 5.4 환경으로 업데이트된 UnrealStarter.uproject 파일을 오픈 합니다.

UnrealStarter 샘플 실행하기

1

플랫폼 연동 환경 설정

DefaultEngine.ini

[HybeGamePlatform]
CustomScheme=PlatformStarter

// UnrealStarterGameModeBase.cpp
std::string configJson = R"({
    "BuildEnv": "qa",
    "ProjectId": "XXXXX",
    "ServiceId": "XXXXX"
})";

2

빌드 후 실행

샘플 디렉토리 구조

		설 명
Config		샘플앱 설정 파일
Content		샘플앱 리소스
Platforms
Plugins		플러그인 루트 폴더
	HybePlatform	게임 플랫폼 플러그인
Source
	UnrealStarter	샘플

로그인 FLOW

① - ④ 플랫폼 이벤트 리스너를 등록한다.

⑤ - ⑥ 플랫폼 초기화를 수행한다.

⑦ - ⑱ 플랫폼 로그인을 요청하고 이벤트를 처리한다.

⑪ - ⑱ 신규 회원 인 경우 웹뷰를 팝업하고 회원 가입 프로세스를 진행한다.

㉑ - ㉔ 게임 서버에 로그인 토큰을 전송하여 게임 서버에 접속한다.

㉕ 로그아웃을 요청한다.

플랫폼 이벤트 리스너 (Platform Agent)

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

• HybePlatformAuthAgent 인증 이벤트를 수신하는 Agent
• HybePlatformWebviewAgent 웹뷰 이벤트를 수신하는 Agent

플랫폼 초기화

1

연동 환경 Configuration 준비

Platform에 연동하기 위해서는 전달 받은 실행 환경 JSON을 준비합니다.

지원되는 세부 항목은 Platform Configuration을 참고하세요.

{
    "BuildEnv": "qa",
    "ProjectId": "0000",
    "ServiceId": "xxx-xxxx"
}

2

플랫폼 Auth Agent 등록

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

class UStarterPlatformAuthAgent : public HybePlatformAuthAgent
{
public:
    virtual void OnLoginSuccess(const FString& resultJson) override;
    virtual void OnLoginFailure(const FString& resultJson) override;
    virtual void OnLogoutSuccess() override;
    virtual void OnLogoutFailure(const FString& resultJson) override;
    virtual void OnWithDraw() override;
    virtual void OnMount(bool mounted) override;
    virtual void OnRefreshVerifyToken(const FString& token) override;
}

다음과 같이 이벤트 핸들러를 구현합니다.

// 로그인 성공시 전달되는 이벤트
void UStarterPlatformAuthAgent::OnLoginSuccess(const FString& resultJson)
{
}

// 로그인 실패시 전달되는 이벤트
void UStarterPlatformAuthAgent::OnLoginFailure(const FString& resultJson)
{
}

void UStarterPlatformAuthAgent::OnLogoutSuccess()
{
}

void UStarterPlatformAuthAgent::OnLogoutFailure(const FString& resultJson)
{
}

// 계정 탈퇴 완료시 전달되는 이벤트
void UStarterPlatformAuthAgent::OnWithDraw()
{

}

// SDK 초기화 수행시 전달되는 이벤트 핸들러
void UStarterPlatformAuthAgent::OnMount(bool mounted)
{
}

// 접속 토큰 갱신요청 시 전달되는 이벤트 핸들러 
void UStarterPlatformAuthAgent::OnRefreshVerifyToken(const FString& token)
{
}

// 점검 이벤트 핸들
void UStarterPlatformAuthAgent::OnInspection()
{
}

3

플랫폼 초기화

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

1. 게임 플랫폼 멤버 이벤트를 수신할 AuthAgent 등록

2. 게임 플랫폼 연동 과정에서 필요한 데이터를 저장할 경로 지정 (자동 로그인 등)

3. 클라이언트 언어 설정

4. 플랫폼 초기화 수행

//1. 게임플랫폼 플러그인에 Agent 및데이터 저장 경로를 등록한다. 
HybePlatformAgent::Instance().SetPlatformAuthAgent(new UStarterPlatformAuthAgent());
HybePlatformAgent::Instance().SetWritableStorageDirectory(FPaths::ProjectSavedDir());

//2. 설정 정보와 함께 플랫폼 초기화를 시도한다.
std::string configJson = R"({
    "BuildEnv": "qa",
    "ProjectId": "XXXXX",
    "ServiceId": "XXXXX"
})";

//3. 클라이언트 언어 설정
HybePlatformAgent::Instance().SetClientLanguage(TEXT("ko"));
GetClientContext().SetClientLanguage(TEXT("ko"));

//4. 플랫폼 SDK 초기화
HybePlatformAgent::Instance().Mount(FString(configJson.c_str()));

HybePlatformAgent은 게임 플랫폼의 서비스를 제공하는 메인 클래스로 게임 플랫폼이 제공하는 모든 기능은 HybePlatformAgent를 통해서 제공됩니다.

4

초기화 이벤트 핸들러

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

void UStarterPlatformAuthAgent::OnMount(bool mounted)
{
    if (mounted)
    {
        // 초기화 성공
        // 로그인 UI를 화면에 출력하거나 자동 로그인을 수행한다.
    }
}

플랫폼 로그인(공통)

플랫폼 로그인은 3가지 단계로 수행됩니다.

1. 구글/애플/이메일 등 인증 수단을 이용한 Signin

2. 회원 가입

3. 로그인

1

웹뷰 Agent 추가

로그인 프로세스에서 필요한 회원 가입, 서비스 이용 동의, 본인 확인 등의 과정에서 웹뷰를 통해 진행됩니다. SDK는 웹뷰가 필요한 경우에 등록된 웹뷰 Agent로 Show/Close 이벤트를 전달합니다.

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

인게임에서 사용하는 웹뷰를 이용해서 로그인 프로세스를 연동할 수 있습니다.

언리얼에서 제공하는 WebBrowser 플러그인을 이용한 가이드를 제공합니다.

HybePlatformWebviewAgent 를 상속받는 Agent를 추가합니다.

class UStarterPlatformWebviewAgent : public HybePlatformWebviewAgent
{
public:
    virtual void OnCloseWebview() override;
    virtual void OnShowWebview(const FString& url) override;
};

// 웹뷰 Close가 필요할 때 전달되는 이벤트
void UStarterPlatformWebviewAgent::OnCloseWebview()
{
}
// 웹뷰 팝업이 필요할 때 전달되는 이벤트
void UStarterPlatformWebviewAgent::OnShowWebview(const FString& url)
{
}

2

언리얼 커스텀 웹뷰 추가

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

언리얼에서 제공하는 Web Browser 플러그인을 상속 받는 커스텀 웹뷰를 추가합니다.

class ULoginWebBrowser : public UWebBrowser
{
    GENERATED_BODY()
	
public:
    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;
};

#define LOCTEXT_NAMESPACE "LoginWebBrowser"

/**
* @brief 웹뷰에서 호출한 console.log 호출시 수신되는 이벤트
*/
void ULoginWebBrowser::OnConsoleLog(const FString& Message, const FString& Source, int32 Line, EWebBrowserConsoleLogSeverity Severity)
{
    UE_LOG(LogTemp, Warning, TEXT("Console(%d, %s) : %s"), Line, *FPaths::GetCleanFilename(Source), *Message);
}

void ULoginWebBrowser::OnHandleOnUrlChanged(const FText& InText)
{
    // 웹뷰 url 변경 이벤트를 플랫폼 SDK에 전달합니다.
    FString url = InText.ToString();
    HybePlatformAgent::Instance().GetWebviewAgent()->OnUrlChanged(url);
}

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

void ULoginWebBrowser::CloseWebview()
{
    WebBrowserWidget->LoadURL("about:blank");
    SetVisibility(ESlateVisibility::Hidden);
    // 웹뷰가 닫힌 경우, 플랫폼에게 웹뷰 닫힘을 알립니다.
    HybePlatformAgent::Instance().GetWebviewAgent()->OnNotifyWebviewClose();
}

TSharedRef<SWidget> ULoginWebBrowser::RebuildWidget()
{
    if (IsDesignTime())
    {
        return SNew(SBox)
            .HAlign(HAlign_Center)
            .VAlign(VAlign_Center)
            [
                SNew(STextBlock)
                    .Text(LOCTEXT("Web Browser", "Web Browser"))
            ];
    }
    else
    {
        WebBrowserWidget = SNew(SWebBrowser)
            .InitialURL(InitialURL)
            .ShowControls(false)
            .SupportsTransparency(bSupportsTransparency)
            .OnUrlChanged(BIND_UOBJECT_DELEGATE(FOnTextChanged, OnHandleOnUrlChanged))
            .OnBeforePopup(BIND_UOBJECT_DELEGATE(FOnBeforePopupDelegate, HandleOnBeforePopup))
            .OnConsoleMessage(BIND_UOBJECT_DELEGATE(FOnConsoleMessageDelegate, OnConsoleLog));

        return WebBrowserWidget.ToSharedRef();
    }
}

3

웹뷰 언리얼 오브젝트 바인딩

웹뷰와 플랫폼 SDK 커뮤니케이션에 필요한 언리얼 오브젝트 바인딩을 적용합니다.

약관동의, 본인인증 등의 웹뷰를 이용한 로그인 과정에서 웹뷰에서 실행되는 JavaScript와 언리얼 엔진과 통신을 위해서 언리얼 오브젝트 바인딩이 필요합니다.

커스텀 웹뷰에 바이딩 기능을 추가합니다.

class ULoginWebBrowser : public UWebBrowser
{
    GENERATED_BODY()	
public:
    UFUNCTION(BlueprintCallable)
    void PostMessage(FString jsonResponse);
    void PrepareJsBridge();
             --- 중 략 ---
};

// 웹뷰에 webbridge 객체 바인딩
// 웹뷰 자바스크립트에서 webbridge를 이용해서 언리얼에 이벤트를 전달할 수 있다.
void ULoginWebBrowser::PrepareJsBridge()
{
    FString linkName = TEXT("webbridge");
    WebBrowserWidget->BindUObject(linkName, this, true); //true : URL이 변경되어도 계속 바이딩 유지
}


// JavaScript -> Unreal 함수 호출을 처리하는 핸들러
void ULoginWebBrowser::PostMessage(FString jsonMethod)
{
    HybePlatformAgent::Instance().GetWebviewAgent()->EvalMethod(jsonMethod, [this](const FString& resultJson) {
        if (resultJson.IsEmpty() == false)
        {
            FString js = FString::Printf(TEXT("window.unityEventHandler(%s);"), *resultJson);
            ExecuteJavascript(js);
        }
    });
}

void ULoginWebBrowser::OnHandleOnUrlChanged(const FText& InText)
{
    FString url = InText.ToString();
    HybePlatformAgent::Instance().GetWebviewAgent()->OnUrlChanged(url);
}

언리얼 Web Browser에서 제공하는 BindUObject 함수를 사용해서 언리얼 오브젝트로 브라우저에서 실행되는 JavaScript가 이벤트를 전달 할 수 있도록 연결하는 과정입니다.

웹뷰의 url이 변경될 때마다 바인딩을 새로 업데이트해야 합니다.

BindUObject(linkName, this, true) 로 설정해서 자동으로 url 변경 시 바인딩 유지되도록 구현할 수 있습니다.

4

웹뷰 오브젝트 바인딩 설정

WebBrowser 위젯 생성 후 웹뷰 언리얼 오브젝트 바이딩을 명시적으로 호출합니다.

class ULoginWidget : public UUserWidget
{
    UPROPERTY(meta = (BindWidget))
    class ULoginWebBrowser* loginWebview;
}

void ULoginWidget::NativeConstruct()
{
    Super::NativeConstruct();
 
    // 웹뷰 언리얼 오브젝트 바인딩
    if (loginWebview != nullptr)
    {
        loginWebview->PrepareJsBridge();
        CloseWebview();
    } 
}

5

웹뷰 Agent 등록

추가된 웹뷰 Agent를 플랫폼 초기화(Mount) 실행 전에 SDK에 등록합니다.

// Auth Agent 등록
HybePlatformAgent::Instance().SetPlatformAuthAgent(new UStarterPlatformAuthAgent());
// 웹뷰 Agent 등록
HybePlatformAgent::Instance().SetPlatformWebviewAgent(new UStarterPlatformWebviewAgent());

6

Custom URI Scheme 등록

DefaultEngine.ini에 Custom URI Scheme을 등록합니다. Custom Scheme은 게임 별로 원하는 이름으로 지정할 수 있습니다. 아래에서는 "PlatformStarter"으로 등록하는 예시입니다.

DefaultEngine.ini

[HybeGamePlatform]
CustomScheme=PlatformStarter

자세한 내용은 Custom URI Scheme 가이드를 참고하세요.

7

플랫폼 로그인

플랫폼 로그인을 프로세스를 실행합니다.

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

Login() 메소드를 호출하여 로그인을 요청합니다. 로그인 결과는 플랫폼 초기화 단계에서 등록한 Auth Agent로 전달됩니다.

지원하는 로그인 수단은 다음과 같습니다.

Google, Apple, LINE, Steam, Email, Guest, Facebook

8

로그인 이벤트 수신

void UStarterPlatformAuthAgent::OnLoginSuccess(const FString& resultJson)
{
    // 로그인 성공
}

void UStarterPlatformAuthAgent::OnLoginFailure(const FString& resultJson)
{
    // 로그인 실패
}

로그인 결과로 전달되는 정보를 이벤트를 참고하세요.

웹뷰 사이즈 가이드

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 설정

스팀 로그인은 아래 설정이 추가적으로 필요합니다.

std::string configJson = R"({
        --- 중략 ---
    "SteamIdentity": "XXXXX",
})";

INI에 연동할 스팀 AppID를 등록합니다.

DefaultEngine.ini

[HybeGamePlatform]
SteamAppId=1234 

2

Build.cs 스팀 dll 런타임 설정

게임 프로젝트의 xxxx.Build.cs 에 스팀 연동에 필요한 dll 이 배포되도록 RuntimeDependencies를설정합니다.

UnrealStarer.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");
}

스팀 게임으로 연동하는 경우, 게임 실행과 언리얼 에디터 실행 시 아래 dll 이 반드시 필요합니다. steam_api64.dll steam_agent.dll 스팀을 지원하는 게임의 경우에만 해당 파일이 배포되도록 설정하세요.

3

스팀 로그인

STEAM 로그인 수단으로 플랫폼 로그인을 요청합니다.

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

플랫폼 로그인(Android)

플랫폼 로그인(공통) 에 아래 과정을 추가합니다.

1

연동 Configuration 설정

안드로이드 로그인은 아래 설정이 추가적으로 필요합니다.

std::string configJson = R"({
        --- 중략 ---
    "WebClientId": "xxx-xxxx-xxx",
})";

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

2

로그인

플랫폼 로그인을 요청합니다.

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

3

앱 사이닝(Signing)

앱 빌드시 사이닝이 적용되도록 설정합니다.

Project Settings > Platforms > Android > Distribution Signing 에 사이닝에 필요한 키스토어 및 정보를 입력합니다.

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

플랫폼 로그인(iOS)

플랫폼 로그인(공통)과 동일합니다.

게스트 로그인

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

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

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

또한, Guest 계정으로 결제를 이용할 수 없습니다. 단, 유료 서비스 이용을 위한 연령 확인 등의 절차를 플랫폼이 아닌 인게임에서 자체적으로 진행, 저장한다면 플랫폼 개입 없이 결제를 활성화할 수 있습니다. 해당 내용은 별도 협의를 진행해야 합니다.

일반 회원 전환

Guest 계정에 일반 인증 수단을 연결 시 일반 계정으로 전환됩니다.

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

자동 로그인

플랫폼 로그인 단계에서 자동 로그인 지원 여부를 설정 할 수 있다.

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

Login 메소드 호출 시 두번째 인자로 true를 전달하면 로그인 정보가 저장되고, 플랫폼 초기화 이후에 저장된 로그인 정보를 이용해서 자동 로그인을 수행할 수 있다.

HybePlatformAgent::Instance().DoAutoLogin([this](bool bAutoLogin) {
});

DoAutoLogin() 을 호출하면 자동 로그인을 수행합니다. 저장된 로그인 정보가 있는 경우 콜백으로 true가 전달됩니다.

다음은 초기화 결과가 전달되는 OnMount() 핸들러에서 자동 로그인을 요청하는 경우입니다.

void UStarterPlatformAuthAgent::OnMount(bool mounted)
{
    if (mounted)
    {
        HybePlatformAgent::Instance().DoAutoLogin([this](bool bAutoLogin) {
            if (bAutoLogin)
            {
                // 자동 로그인 성공
            }
            else
            {
                // 자동 로그인 실패 : 로그인 정보 없는 경우
            }
        });
    }
}

플랫폼 로그아웃

플랫폼 로그아웃을 요청합니다.

HybePlatformAgent::Instance().Signout();

로그인 수단을 변경하기 위해서는 로그 아웃 성공 이후에 다시 로그인을 요청할 수 있습니다.

로그 아웃 결과는 HybePlatformAuthAgent를 상속받은 클래스로 전달된다.

• 로그아웃 성공 : OnLogoutSuccess
• 로그아웃 실패 : OnLogoutFailure

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

로그 아웃은 언제 호출하는가?

• 타이틀 이동 후 다른 계정으로 다시 로그인 하는 경우

• 자동 로그인 정보를 삭제하고자 하는 경우

탈퇴

계정 탈퇴를 요청합니다.

HybePlatformAgent::Instance().Withdraw();

Withdraw를 호출하면 탈퇴 프로세스를 수행하는 웹뷰가 팝업되고, 결과는 HybePlatformAuthAgent의 OnWithdraw() 로 전달됩니다.

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

탈퇴 완료 후 다른 계정으로 로그인을 다시 시도하기 위해서는 로그인 정보 초기화가 필요합니다. 탈퇴한 계정은 유효하지 않기 때문에 Signout()을 시도할 수 없습니다.

ForceSignout()으로 로그인 정보를 초기화할 수 있습니다.

푸시 연동

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

Android

1

google-services.json 파일을 Plugins 폴더에 복사합니다.

Plugins\HybePlatform\Source\HybePlatform\Build\Android\google-services.json

google-services.json 파일은 Firebase 프로젝트와 안드로이드 앱을 연결하는 데 필요한 구성 정보를 포함하는 파일로 다음 정보가 포함됩니다.

• Firebase 프로젝트 식별 정보

• Firebase Analytics, Cloud Messaging 등 설정 정보

이 파일을 프로젝트에 추가하면 Firebase SDK가 자동으로 필요한 설정을 구성합니다.

※ google-services.json 파일은 기술PM에게 문의하세요. ※

2

UPL.xml 에 google-services 패키지를 지정합니다.

게임 프로젝트의 UPL.xml에 gradle 설정을 아래와 같이 추가합니다.

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

google-services 버전은 JDK 또는 firebase 지원에 적합한 버전을 지정해야 합니다.

푸시 허용 요청 팝업

안드로이드 13 이상인 경우 게임 시작 시 자동으로 푸시 허용 팝업이 노출되도록설정되어있습니다.

점검

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

• 점검 페이지 팝업 이벤트

  • HybePlatformWebviewAgent를 상속받은 클래스의 OnShowWebview()에 점검 페이지 url이 전달됩니다.
• 점검 상태 이벤트

  • HybePlatformAuthAgent를 상속받은 클래스에서 OnInspection 이벤트 핸들러를 제공해야 합니다.

void UStarterPlatformAuthAgent::OnInspection()
{
}

OnShowWebview 가 먼저 호출되고 OnInspection() 이 순차적으로 호출됩니다.

OnInspection() 호출 이후에 OnMount() 이벤트가 전달됩니다.

OnMount 이벤트는 점검 상태를 전달하지 않습니다. 점검 상태에 따라서 별도 로직이 필요한 경우 OnInspection에서 점검 상태 플래그를 설정하면 Mount 후에 점검 상태 여부를 확인할 수 있습니다.

로그 연동

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

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

• 로그 데이터 수집 : 로그 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 생성 시 추가됩니다.

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

Lognetic()은 LogneticAgent 인스턴스 접근 매크로입니다.

개별 속성 등록

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

로그 JSON 생성

JSON 생성 시 등록된 공통 속성과 생성 시간(cre_time) 속성이 자동으로 추가 됩니다.

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

로그 JSON 생성 및 전송

Send() 메소드는 JSON을 생성 한 후 로그 서버로 전송을 수행합니다.

1개의 로그를 전송하는 경우에 사용합니다.

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

중첩 구조 로그를 생성하는 경우

{
  "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 사용

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 Reference

Platform Configuration

플랫폼 초기화 함수(Mount)에 전달하는 실행 환경 JSON 정보는 다음과 같습니다.

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

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

Custom URI Scheme

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

각 앱 별로 공유한 URI Scheme 을 지정해야 합니다.

DefaultEngine.ini에 HybeGamePlatform 항목에 설정하면 Windows/Android/iOS 앱 빌드 시 Custom URI Schem 이 자동 적용 됩니다.

DefaultEngine.ini 예시

[HybeGamePlatform]
CustomScheme=PlatformStarter

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

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

Custom URI Scheme 이란?

애플리케이션에서 고유한 프로토콜을 정의하여 특정 앱을 URL 형식으로 호출하거나 앱 간에 데이터 전달을 할 수 있도록 해주는 기능입니다. 보통 웹 브라우저나 다른 앱에서 myapp://와 같은 URL 형식을 통해 해당 앱을 열거나 명령을 실행할 때 사용됩니다.

HybePlatformAgent

게임 플랫폼의 서비스를 제공하는 메인 클래스로 결제 기능을 제외한 게임 플랫폼이 제공하는 대부분의 기능을 제공됩니다

Mount

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

void HybePlatformAgent::Mount(const FString& configJson) const

파라미터

• configJson 설정 정보 JSON 문자열

초기화 결과는 HybePlatformAuthAgent 상속받은 클래스의 OnMount 이벤트로 전달됩니다.

void UMyGamePlatformAuthAgent::OnMount(bool mounted)
{
    UE_LOG(LogTemp, Warning, TEXT("Platform Mounted : %d"), mounted);
}

Login

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

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

파라미터

• signinMethod 로그인 종류. STEAM, GOOGLE, APPLE, LINE, 이메일(IM), GUEST, FACEBOOK

• bEnableAutologin 자동 로그인 적용 여부

로그인 결과는 HybePlatformAuthAgent을 상속받은 클래스의 OnLoginSuccess와 OnLoginFailure이벤트로 전달됩니다.

bEnableAutologin 를 true로 설정하면 자동 로그인에 필요한 정보가 로컬에 저장됩니다.

저장된 정보는 자동 로그인(DoAutoLogin) 실행 시 사용됩니다.

스팀 계정 로그인 예

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

DoAutoLogin

자동 로그인을 실행합니다.

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

파라미터

• callback 자동 로그인 결과

Login() 호출 시 자동 로그인 여부 true로 설정한 경우 자동 로그인을 수행 합니다. 자동 로그인 된 정보가 없으면 콜백으로 false를 전달합니다. 호출 전에 자동 로그인 가능 여부를 판단하는 기능을 제공하지 않습니다. DoAutoLogin을 호출하면 콜백으로 결과가 전달됩니다.

로그인 결과는 OnLoginSuccess로 전달됩니다.

HybePlatformAgent::Instance().DoAutoLogin([this](bool bAutoLogin) {
    if (bAutoLogin)
    {
        // 자동 로그인 시도
    }
    else
    {
        // 자동 로그인 실패 : 로그인 정보 없는 경우
    }
});

자동 로그인 실패가 로그인 실패를 의미하지는 않습니다.

환경 변화에 따라 자동 로그인이 실패할 수 있습니다.

자동 로그인 실패하는 경우 로그인 수단 선택 화면을 출력해서 유저가 로그인을 시도하도록 해야 합니다.

Signout

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

void Signout() const

파라미터

• 없음

로그 아웃 결과는 HybePlatformAuthAgent를 상속받은 클래스로 전달된다.

• 로그아웃 성공 : OnLogoutSuccess
• 로그아웃 실패 : OnLogoutFailure

ForceSignout

플랫폼 SDK의 로그인 정보를 강제로 초기화 합니다.

void ForceSignout() const

파라미터

• 없음

백엔드로그 아웃 결과는 HybePlatformAuthAgent를 상속받은 클래스로 전달된다.

• 로그아웃 성공 : OnLogoutSuccess

Signout은 로그인 정보를 이용해서 플랫폼 백엔드에 로그아웃을 요청하는 우아한 로그아웃이며, ForceSignout은 백엔드 연동없이 로그인 정보를 즉시 초기화 합니다.

게임 실행 도중 강제로 로비로 돌아오는 등 비정상적인 상황에서 다시 로그인이 필요한 경우에 ForceSignout으로 로그인 정보를 초기화 하고 다시 로그인을 수행할 수 있습니다.

ForceSignout은 자동 로그인 정보를 초기화 하지 않습니다.

ConvertMember

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

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

파라미터

• signinMethod 로그인 종류. STEAM, GOOGLE, APPLE, LINE, 이메일(IM)

• yyyyMMdd (optional) 생년월일. 게스트에 대한 생년월일을 저장하고 있는 경우 제공합니다.

• callback 입력받은 생년월일 yyyyMMdd ex)20021010

ShowRequireGuestBirthDay

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

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

파라미터

• callback 입력 결과를 수신하는 콜백, 취소하는 경우 빈 문자열

  • yyyyMMdd 문자열이 전달됩니다. ex)20021010

RefreshVerifyToken

로그인 토큰을 갱신합니다.

void RefreshVerifyToken() const

파라미터

• 없음

플랫폼 로그인 성공 후에 전달 받은 LoginToken 을 갱신합니다.

로그인 성공 후 발급 받은 토큰은 1시간 동안 유효합니다. 로그인 토큰은 게임 서버로 전달되어 게임 서버가 플랫폼 백엔드 인증에 사용합니다.

다음 경우에 RefreshVerifyToken으로 로그인 토큰을 갱신 해야 합니다.

• 로그인 성공 이후 게임 서버에 로그인 토큰을 즉시 전달하지 않는 경우

  • 예를 들어, 로그인 후 [게임 시작] 클릭 후 게임 서버에 접속하는 경우 유저가 로그인 후 오랜 시간 자리를 비우고 [게임 시작]을 진행하면 만료된 로그인 토큰이 게임 서버에 전달되어 인증이 실패할 수 있습니다.

• 클라이언트가 게임 서버와 접속을 끊고 다시 게임 서버에 접속하는 경우

• 클라이언트가 비정상 상황에서 게임 서버와 접속이 강제로 끊긴 후 다시 게임 서버에 접속하는 경우

  • 예를 들어, 로비로 튕긴 후 다시 게임 서버에 접속하는 경우

Withdraw

계정 탈퇴를 요청합니다.

void Withdraw() const;

파라미터

• 없음

탈퇴 프로세스를 수행하는 웹뷰가 팝업되고, 결과는 HybePlatformAuthAgent를 상속받은 클래스의 OnWithdraw() 로 전달됩니다. 탈퇴 프로세스 도중 웹뷰를 강제로 닫는 경우 취소 이벤트가 별도로 전달되지는 않습니다. OnWithdraw()를 수신하지 않는 경우 탈퇴 진행이 되지 않았습니다.

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

탈퇴 완료 후 다른 계정으로 로그인을 다시 시도하기 위해서는 로그인 정보 초기화가 필요합니다. 탈퇴한 계정은 유효하지 않기 때문에 Signout()을 시도할 수 없습니다.

ForceSignout()으로 로그인 정보를 초기화할 수 있습니다.

GetLocationCode

현재 사용자의 접속 국가 코드를 반환합니다

FString GetLocationCode() const

파라미터

• 없음

리턴

• ISO 3166-1 alpha-2 국가 코드, ex) KR, US

SetClientLanguage

게임 클라이언트에서 사용하는 언어를 SDK에 전달합니다.

설정된 언어 정보를 이용해서 플랫폼 연동 과정에서 출력되는 웹뷰의 다국어가 적용됩니다.

void SetClientLanguage(const FString& language) const

파라미터

• language ISO 639-1 언어코드( ko, en, ja, zh-tw). 웹뷰에 보여지는 컨텐츠는 지원 국가 외에는 영문(en)으로 출력 됩니다.

SetWritableStorageDirectory

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

void SetWritableStorageDirectory(const FString& dir) const

파라미터

• dir 쓰기 가능한 경로

지정된 경로에 자동 로그인, 결제 정보 등이 저장됩니다.

적용 예)

//언리얼 제공 쓰기가능 폴더 지정
FString dir = FPaths::ProjectSavedDir();
HybePlatformAgent::Instance().SetWritableStorageDirectory(dir);

GetSteamInfo

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

HybePlatform::SteamInfo GetSteamInfo() const

리턴

• SteamInfo 쓰기 가능한 경로

class SteamInfo
{
public:
    UINT64 Id;            // User ID
    FString Language;     // (결제)스팀 API 호출시 사용되는 언어코드(ISO 639-1)
    FString Currency;     // (결제)통화코드 ex) KRW, USD
    INT AppBuildId;       // 앱 빌드ID
};

GetAgreementStatus

약관 동의 정보를 조회합니다.

static void GetAgreementStatus(std::function<void(HybePlatform::AgreementPayload)> callback)

리턴

• callback 약관 동의 정보 수신 콜백

  • AgreementPayload 약관 동의 정보

AgreementPayload

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

UpdateAgreement

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

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

파라미터

• agreementPayload 약관 정보(AgreementPayload)

리턴

• callback 약관 동의 정보 수신 콜백

  • bool 약관 동의 업데이트 성공 유무

  • AgreementPayload 업데이트 된 약관 동의 결과

업데이트 요청한 약관 정보와 백엔드에 반영된 약관 동의 정보를 다를 수 있습니다.

예를 들어, 마케팅 정보 동의(advertising) 속성이 false 로 되어있으면 푸시 수신 동의는 유저가 설정한 푸시(adPush), 야간 수신(adNightPush) 동의 정보에 관계없이 항상 false로 처리됩니다.

GetUrl

인게임에서 사용하는 다양한 URL을 요청합니다

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

파라미터

• urlType URL 종류, 종류는 아래 표를 참고하세요.

• language 언어 정보, SetClientLanguage에 지정한 언어 정보를 사용해서 자동 반영됩니다.

URL 종류

SDK에서 미리 정의한 상수를 사용하세요.

용도	url 타입	설명
개인정보 처리 방침	URLKey::PRIVACY_POLICY
계정 센터(마이 페이지)	URLKey::MYPAGE
약관 보기	URLKey::TERMS_OF_SERVICE
공지사항	URLKey::NOTICE
고객센터	URLKey::CS
홈페이지	URLKey::HOMEPAGE	커뮤니티
한도 조회	URLKey::PAYMENT_LIMIT
일본 연령 확인	URLKey::BIRTH_REQUIRED	연령 정보 등록하지 않은 일본 계정으로 PC에서 결제 진행하는 경우
쿠폰 등록	URLKey::COUPON
거래 내역	URLKey::TRANSACTION_HISTORY	거래 내역 조회
이벤트	"connect_event_account"

GetVersion

플랫폼 SDK 버전을 조회합니다.

static FString GetVersion();

리턴

• 버전 문자열. major.minor.patch ex) 0.10.2

GetLastSigninTag

가장 최근 로그인한 정보를 조회합니다.

static FString GetLastSigninTag()

리턴

• 최근 로그인 정보 JSON

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

SetPlatformAuthAgent

HybePlatformAuthAgent을 상속받은 Agent 클래스를 등록합니다.

void SetPlatformAuthAgent(HybePlatformAuthAgent* authAgent)

파라미터

• authAgent HybePlatformAuthAgent을 상속 받은 클래스 인스턴스

리턴

• 없음

SetPlatformWebviewAgent

HybePlatformWebviewAgent을 상속받은 Agent 클래스를 등록합니다.

void SetPlatformWebviewAgent(HybePlatformWebviewAgent* webviewAgent)

파라미터

• webviewAgent HybePlatformWebviewAgent을 상속 받은 클래스 인스턴스

리턴

• 없음

SetPlatformBillingAgent

HybePlatformWebviewAgent을 상속받은 Agent 클래스를 등록합니다.

void SetPlatformBillingAgent(class HybePlatform::HybeBillingAgent* billingAgent)

파라미터

• billingAgent HybeBillingAgent를 상속 받은 클래스 인스턴스

리턴

• 없음

GetAuthAgent

등록한 HybePlatformAuthAgent 인스턴스를 구합니다.

HybePlatformAuthAgent* GetAuthAgent() const

리턴

• 등록한 HybePlatformAuthAgent 인스턴스

GetWebviewAgent

등록한 HybePlatformWebviewAgent 인스턴스를 구합니다.

HybePlatformWebviewAgent* GetWebviewAgent() const

리턴

• 등록한 HybePlatformWebviewAgent 인스턴스

GetBillingAgent

등록한 HybeBillingAgent 인스턴스를 구합니다.

HybePlatform::HybeBillingAgent* GetBillingAgent() const

리턴

• 등록한 HybeBillingAgent 인스턴스

ListenReturnToGame

외부 브라우저에서 전송하는 [게임으로 돌아가기] 이벤트를 수신하는 핸들러를 등록합니다.

void ListenReturnToGame(TFunction<void(const FString&)> Callback)

파라미터

• Callback 이벤트 수신 시 호출하는 콜백

CompleteReturnToGame

[게임으로 돌아가기] 이벤트를 수신 대기를 종료합니다.

void CompleteReturnToGame()

파라미터

• 없음

HybePlatformAuthAgent

플랫폼 로그인 연동 과정에서 발생하는 이벤트를 수신하는 이벤트 리스너 Agent.

게임 클라이언트는 HybePlatformAuthAgent 를 상속받는 Agent를 반드시 구현해야한다.

OnLoginSuccess

Login() 실행 성공 시 호출되는 이벤트 핸들러

void OnLoginSuccess(const FString& resultJson)

파라미터

• resultJson 로그인 결과 JSON

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

키	설명
imid	게임별로 부여되는 유저 ID
loginToken	로그인 토크. 게임 서버에 전달하여 게임 플랫폼 백엔드에 접속한 유저의 유효성을 검사하는 용도로 사용됩니다. RefreshVerifyToken 을 호출하여 갱신할 수 있습니다.

OnLoginFailure

Login() 실패 시 호출되는 이벤트 핸들러

void OnLoginFailure(const FString& resultJson)

파라미터

• resultJson 로그인 결과 JSON

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

에러 코드는 아래와 같이 정의되어 있습니다.

enum class Code
{
    UNKNOWN_ERROR       = 0,
    NO_INITIALIZE       = 1,
    SIGNIN_FAIL         = 2,    // Google/Apple Signin
    PLATFORM_LOGIN_FAIL = 3,    // Platform login
    AUTO_LOGIN_FAIL     = 4,    // Auto login fail
    WITHDRAW_ACCOUNT    = 5,    // 계정 탈퇴 회원 (deprecated)
    SIGNUP_FAIL         = 6,    // 회원가입 실패
};

에러 코드별 전달되는 메시지는 다음과 같습니다.

Code	message	설명
SIGNIN_FAIL	Login cancel	Google/Apple/Line 등 3rd Party Signin 취소
	NO_ACCOUNT	신규 회원 가입 도중 취소
	NOT_SUPPORTED_SIGNIN_PROVIDER	지원하지 않는 로그인 수단
	Unknown login error
PLATFORM_LOGIN_FAIL	DORMANT_ACCOUNT	휴면 유저
	Already log in	로그아웃하지 않고 로그인 시도
	Steam no prepare	스팀 연결 실패
	FAIL_LOCK_REQUEST	로그인 토큰 중복 요청
	Unknown error

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

FAIL_LOCK_REQUEST

플랫폼 백엔드에 로그인 토큰을 짧은 시간 동안(1초 이내) 중복 요청하는 경우 발생합니다.

로그인 토큰을 요청하는 API는 아래와 같습니다.

• Login() : 인증 수단으로 플랫폼 로그인 시 로그인 토큰을 발급합니다.
• RefereshVerifyToken() : 로그인 토큰 새로 발급을 요청합니다.

주로, Login() 호출 후 수신한 OnLoginSuccess 이벤트에서 RefereshVerifyToken() 을 호출하는 경우 발생합니다. OnLoginSuccess 수신한 LoginToken이 일정 시간 유효하기 때문에 RefereshVerifyToken()으로 갱신할 필요가 없습니다.

자세한 내용은 RefereshVerifyToken() 을 참고하세요.

OnLogoutSuccess

Signout, ForceSignout 성공 시 호출되는 이벤트 핸들러

void OnLogoutSuccess()

리턴 없음

OnLogoutFailure

Signout 성공 시 호출되는 이벤트 핸들러

void OnLogoutFailure(const FString& message)

파라미터

• resultJson 로그아웃 실패 메시지

OnMount

플랫폼 초기화(Mount)결과를 수신하는 이벤트 핸들러

void OnMount(bool mounted)

파라미터

• mounted 초기화 성공 여부

void UMyGamePlatformAuthAgent::OnMount(bool mounted)
{
    if(mounted) 
    {
        // 초기화 완료, 로그인, 자동 로그인 등을 구현한다
    }
}

초기화 실패하면 플랫폼 SDK를 더 이상 이용할 수 없습니다.

• 설정 정보에서 BuildEnv 가 유효한지 확인하세요.
• SetWritableStorageDirectory가 유효한지 확인하세요.
• 스팀 게임인 경우 INI에 SteamAppID 를 설정했는지 확인하세요.

OnRefreshVerifyToken

로그인 토큰 갱신(RefreshVerifyToken) 요청 결과를 수신하는 이벤트 핸들러

void OnRefreshVerifyToken(const FString& token)

파라미터

• token 갱신된 로그인 토큰

OnWithDraw

탈퇴(Withdraw) 요청 결과를 수신하는 이벤트 핸들러

void OnWithDraw()

사용 예

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

탈퇴 완료 후 다른 계정으로 로그인을 다시 시도하기 위해서는 로그인 정보 초기화가 필요합니다. 탈퇴한 계정은 유효하지 않기 때문에 Signout()을 시도할 수 없습니다.

ForceSignout()으로 로그인 정보를 초기화할 수 있습니다.

OnInspection

플랫폼 초기화(Mount)시 발생하는 수신하는 점검 이벤트 핸들러

void OnInspection()

초기화 단계에서 점검 중인 경우 이벤트가 전달됩니다. 초기화 완료 이벤트(OnMount)보다 먼저 호출 됩니다.

HybePlatformWebviewAgent

인증 과정에서 발생하는 웹뷰 이벤트를 제공하는 클래스.

게임 클라이언트에서 상속한 클래스를 등록하면 웹뷰 이벤트가 등록된 Agent로 전달됩니다.

게임 SDK는 인증 과정에서 웹뷰를 사용하지만 웹뷰를 직접 제공하지 않습니다.

언리얼에서 제공하는 Web Browser 플러그인을 사용하도록 지원하고 있으며, 개발사에서 직접 가이드에 따라 구현해야 합니다.

별도의 커스텀 웹뷰를 사용하는 경우 기술PM에게 문의하세요.

OnShowWebview

웹뷰 팝업 요청 이벤트 핸들러

void OnShowWebview(const FString& url)

파라미터

• url 웹뷰에 보여지는 URL

회원 가입, 탈퇴, 본인 인증, 이메일 등록 등의 프로세스는 웹뷰를 통해 구현되어 있습니다. 요청한 프로세스 별로 필요한 단계에서 OnShowWebview 이벤트가 전달됩니다. 지정된 url로 웹뷰가 팝업되도록 구현해야 합니다.

OnCloseWebview

웹뷰 닫기 요청 이벤트 핸들러

void OnCloseWebview()

파라미터 없음

회원 가입, 탈퇴 프로세스에서 웹뷰가 출력되고 해당 프로세스가 완료 또는 취소 되는 경우 호출됩니다. 화면에 출력된 웹뷰를 닫는 작업을 구현해야 합니다.

LogneticEvent

Set

속성을 추가합니다.

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

파라미터

• key 속성명

• value 속성 값. int, usingined int, int64_t, uint64_64, 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()는 새로 추가된 이벤트 객체를 리턴합니다.

체이닝(chaning) 형식으로 호출하는 경우 리턴 된 이벤트에 속성이 추가됩니다.

2번 호출하는 경우 새로 추가된 이벤트의 하위 속성으로 추가되기 때문에 주의가 필요합니다.

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"), "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"), "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)의 하위를 등록되며 지정된 키의 배열의 마지막 아이템으로 등록됩니다.

동일한 키(key) 로 호출할 때마다 배열에 새로운 이벤트 객체가 추가 됩니다.

LogneticEvent& LogneticEvent::AddArray(const FString& key)

파라미터

• key 하위 이벤트 키 값

리턴

• 추가된 하위 이벤트 객체

배열 1개 이벤트 추가

LogneticEvent log
  log.Set(TEXT("log_type"), TEXT("LOGOUT"))
     .AddArray(TEXT("play_details")) // online_play/play_details[0]
        .Set(TEXT("dungeon_type"), TEXT("10"))
        .Set(TEXT("scale"), 2);
log.ToJson().Send();

JSON 생성 결과

{
  "log_type": "LOGOUT",
  "play_details": [
      {
        "dungeon_type": "10",
        "dungeon_id": "1",
        "scale": 2
      }
    ]
  }
}

동일한 키(key)로 호출할 때마다 배열에 새로운 이벤트 객체가 추가 됩니다.

배열 2개 이벤트 추가

LogneticEvent log
  log.Set(TEXT("log_type"), TEXT("LOGOUT"))
     .AddArray(TEXT("play_details"))  // online_play/play_details[0]
        .Set(TEXT("dungeon_type"), TEXT("10"))
        .Set(TEXT("scale"), 2);
  log.AddArray(TEXT("play_details"))  // online_play/play_details[1]
     .Set(TEXT("dungeon_type"), TEXT("20"))
     .Set(TEXT("scale"), 5);

log.ToJson().Send();

JSON 생성 결과

{
  "log_type": "LOGOUT",
  "play_details": [
      {
        "dungeon_type": "10",
        "scale": 2
      },
      {
        "dungeon_type": "20",
        "scale": 5
      }    
    ]
  }
}

Send

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

• 공통 속성 추가

• 로그 생성 시간 추가 (cre_time)

void Send()

등록된 속성을 JSON으로 변환 후에 로그 서버에 전송합니다.

파라미터

• 없음

LogneticAgent

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

LogneticEvent를 사용하지 않고, 직접 수집한 로그 JSON을 전송할 수 있습니다.

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개 이상의 로그 전송이 필요한 경우.

로그 전송은 요청 시 마다 개별로 서버에 전송합니다.

여러 개의 로그를 한꺼번에 요청하는 것이 효과적입니다.

1개 이상 로그 전송하기

FString myLog = BuildCustomLog();
FString myLog2 = BuildCustomLog2();
FArray logs = {myLog, myLog2};
LogneticAgent::Instance().SendEvent(logs); // 동일 Lognetic().SendEvent(logs);

SetCommon

공통 속성을 설정합니다.

template<typename T>
typename std::enable_if<is_allowed_log_type<T>::value, void>::type //허용된 타입 제한
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()

Troubleshooting

플러그인 초기화 실패가 발생합니다.

해결

steam_api64.dll 파일이 실행 폴더에 위치하는지 확인합니다

안드로이드 구글 로그인이 실패합니다.

로그인 할 계정을 선택하면 Login cancel 실패 이벤트가 수신 됩니다.

해결

앱 사이닝 적용 후 다시 빌드하세요.

또는초기화 설정 정보에 WebClientId가 현재 접속 환경에 등록된 값인지 확인하세요.

"WebClientId": "xxx-xxxx-xxx"

함께 볼만한 문서

• Firebase 테스트 가이드