Unreal Engine

Unreal Plugin 기본 설명

---

해당 문서는 플러그인 방식을 사용하여 Unreal Engine 4, 5 개발 환경에서 기존 SDK 적용 방식보다 보다 손쉽게 적용하는 방법을 제공하기 위하여 작성되었습니다.

Unreal Plugin 다운로드 및 설치하기

Unreal Plugin을 설치하고, Unreal Engine 4, 5에서 프로젝트를 구성하는 방법은 다음과 같습니다.

1. AppGuard 매니저 서버에 접속하여 Download > Unreal Pluings 를 선택하여 최신 버전으로 다운로드합니다.

2. 다운로드된 AppGuardUnrealPlugin.zip 파일 내 /AppGuardSDK 라는 폴더가 존재하며, 해당 AppGuardSDK 폴더를 Project/Plugins/ 경로 내로 복사합니다.

3. Project/Source/ProjectName/ 경로 내의 APPNAME.Build.cs 파일을 열어 아래와 같이 "AppGuardSDK"를 추가하여 Unreal 프로젝트 내 AppGuard SDK 설치할 수 있습니다.

APPNAME.Build.cs

PublicDependencyModuleNames.AddRange(new string[] 
{ 
    "Core", "CoreUObject", "Engine", "InputCore", "AppGuardSDK" 
});

AppGuard Config 파일 다운로드 및 설정하기

1. AppGuard 매니저 서버에 접속하여 Applying Security > 다운로드 > CHAPTER 2. nProtect AppGuard CONFIG 파일 다운로드 > CONFIG FILE DOWNLOAD 를 선택하여 다운로드합니다.

2. 다운로드된 Config 파일을 압축 해제 시 AppGuard Config 파일은 appguard, appguard.crt, appguard.mf, appguard106000 4개의 파일로 구성되어있습니다.

3. 위 4개의 파일을 아래의 경로에 복사합니다.
   Copy To : Project/Binaries/IOS/Payload/APPNAME.app/

주의

[Unreal Editor] 에서 아직 IOS 빌드를 수행한 적이 없는 경우, Project/Binaries/IOS 폴더가 존재하지 않을 수 있습니다. 이러한 경우에는 IOS 빌드를 한 번 수행한 후 위의 작업을 수행해 주시기 바랍니다.

AppGuardSDK Unreal Plugin 적용

---

Delegate에 콜백 등록 및 AppGuard 초기화 함수 호출하기

App 실행 시 보안 정책 위반 행위가 탐지될 경우 Callback을 통해 이벤트를 받으려면 Delegate에 콜백을 등록해야 합니다. 또한 AppGuard 초기화 작업을 위해 UAppGuardSDKBlueprintLibrary::Start(); 함수를 반드시 호출해야 합니다. 이때 해당 함수의 호출 시점은 앱 실행 시 가장 먼저 실행되는 시점 에 적용하여야 합니다.

ASampleProjectGameMode.cpp

#include “AppGuardSDKPlugin.h”
#include “AppGuardSDKBlueprintLibrary.h”

void ASampleProjectGameMode::InitGame(const FString& MapName, const FString& Options, FString& ErrorMessage) { 
    //. 보안 탐지용 콜백 함수 등록
    FAppGuardSDKModule::OnDetected.AddUObject(this, &ASampleProject::OnDetected); // 콜백 등록

    //. 서버인증용 콜백 함수 등록
    FAppGuardSDKModule::OnS2AuthCompleted.AddUObject(this, &ASampleProject::OnS2AuthCompleted);

    //. AppGuardCore.framework 사용을 위한 AppGuard 초기화
    UAppGuardSDKBlueprintLibrary::Start(); 
}

/* 보안 탐지용 콜백 함수 샘플 */
void ASampleProjectGameMode::OnDetected (int data) {
    bool killed = data > 0;
    int code = data > 0 ? data : data * -1;

    /*
    Data 의 값이 양수일 경우, Appguard 는 30초 후 종료 처리됩니다.
    아래 샘플 코드를 이용하여 사용자에게 노출될 화면에 출력하도록 하여야 합니다. 
    */
    if (killed) {
        //. 종료 알림 창을 노출하여 게임이 종료되는 것을 사용자에게 알립니다.
        //. 종료 알림 창은 확인 버튼 클릭 시 앱이 종료되도록 구성하여야 합니다.
    }
}

/* 서버인증용 콜백 함수 샘플 */
void ASampleProjectGameMode::OnS2AuthCompleted (int value, FString data) {
    //. 서버인증 용 콜백 함수 구현 부분은 [서버인증 적용] 단계 참조 요망
}

주의

실제 서비스 Release 시 위의 보안 탐지용 콜백 함수와 서버인증용 콜백 함수 내 로그 출력 함수를 반드시 제거해주시길 바랍니다.

UserID 설정하기

정책 위반 탐지 시 로그 서버에 User ID를 전송하기 위한 SetUserId() 메소드를 제공합니다.

아래 샘플 코드와 같이 userID 부분에 실제 해당 세션의 사용자 ID를 FString 형태의 데이터로 전달하여 사용할 수 있습니다.

ASampleProjectGameMode.cpp

#include “AppGuardSDKPlugin.h”
#include “AppGuardSDKBlueprintLibrary.h”

UAppGuardSDKBlueprintLibrary::SetUserId(TEXT("userID"));

서버인증 적용(선택)

---

본 내용은 서버인증 사용 시 필요한 내용이며, 서버인증 미사용 시 아래 내용은 무관한 내용입니다.

서버인증용 콜백 함수 구현하기

서버인증 관련 콜백은 Delegate에 콜백 등록 및 AppGuard 초기화 함수 호출하기 부분에서 작성한 OnS2AuthCompleted() 콜백 메서드를 통하여 서버인증 동작 이벤트가 전달됩니다.

아래 샘플 코드와 같이 서버인증 상태 결과를 OnS2AuthCompleted() 콜백 메서드를 통해 확인할 수 있습니다.

ASampleProjectGameMode.cpp

#include “AppGuardSDKPlugin.h”
#include “AppGuardSDKBlueprintLibrary.h”

// 서버인증용 콜백 함수 샘플
void ASampleProjectGameMode::OnS2AuthCompleted (int value, FString data) 
{ 
    switch (value) 
    {
        case AppGuardEventType::S2Auth::S2AUTH_RESULT_SUCCESS: 
            /*
            서버 인증이 성공하였으며, 정상적으로 인증이 완료되었습니다. 
            */
            break;
        case AppGuardEventType::S2Auth::S2AUTH_RESULT_RETRY: 
            /*
            서버 인증이 실패하였으며, 재인증을 시도할 것입니다. 일시적인 클라이언트 네트워크 장애 또는 서버 장애일 수 있으며, 
            해당 재시도는 내부 메커니즘에 따라 최대 3분 동안 수행될 수 있습니다.
            */
            break;
        case AppGuardEventType::S2Auth::S2AUTH_RESULT_FAIL: 
            /*
            서버 인증이 완전히 실패하였으며, 더 이상 서버 인증을 시도하지 않습니다. 
            */
            break;
    }
}

팁

아래의 서버인증 시작하기 설명과 같이 UAppGuardSDKBlueprintLibrary::SetUniqueClientId() 메서드를 호출하면 해당 시점부터 AppGuard 보안 모듈이 서버 인증을 시도하며, 위 샘플 코드에 예시된 것과 같이 3가지 상태 코드를 콜백 메서드로 전달합니다.

주의

실제 서비스 Release 시 위의 서버인증용 콜백 함수 내 로그 출력 함수를 반드시 제거 해주시길 바랍니다.

서버 인증 시작하기

클라이언트에서 서버 인증을 시작하기 위해서는 아래 샘플 코드와 같이 서버에서 수신한 해당 사용자의 세션에 대한 UniqueClientID 를 아래와 같은 메서드를 사용하여 사용할 수 있습니다.

ASampleProjectGameMode.cpp

#include “AppGuardSDKPlugin.h”
#include “AppGuardSDKBlueprintLibrary.h”

UAppGuardSDKBlueprintLibrary::SetUniqueClientId(TEXT("Formatted-Unique-Client-Id", 180));

팁

위 함수의 첫번째 인자로 주어진 Formatted-Unique-Client-Id의 규칙 및 생성 방법은 [주요 API] 를 참고하여 주시기 바랍니다.