1.5. Unreal SDK 설치

1.5.1. 설치 환경 및 실행 환경

• 권장 버전

  • Unreal 4.24.3 이상 지원

1.5.2. SDK 파일 구성

전달받은 KakaoGameSDK_Unreal_[버전].zip 파일은 다음과 같은 파일들로 구성되어 있습니다.

 
1.5.3. SDK 환경 설정

1.5.3.1. Unreal Plugin 추가하기

• Unreal 프로젝트 폴더에서 Plugins 폴더를 찾습니다. (Plugins 폴더가 없는 경우 폴더를 생성합니다.)

• 생성한 Plugins 폴더에 KakaoGameSDKPlugin 폴더를 추가합니다.

  Open

  

• Unreal Engine의 플러그인 메뉴에서 새로 추가한 KakaoGameSDK Plugin을 활성화 합니다.

  Open

  

• Unreal SDK를 프로젝트에서 사용하기 위해 프로젝트의 Build.cs 파일에서 다음과 같이 KakaoGameSDKPlugin과 Json 모듈을 추가합니다.

  KakaoGameSample.Build.cs

  using UnrealBuildTool;   public class KakaoGameSample : ModuleRules {   public KakaoGameSample(ReadOnlyTargetRules Target) : base(Target)   {     PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;         PublicDependencyModuleNames.AddRange(new string[] {       "KakaoGameSDKPlugin",       "Json",     });           PrivateDependencyModuleNames.AddRange(new string[] {  });   } }

1.5.3.2. Unreal Engine 설정하기

• (중요) iOS 빌드를 하기 위해서는 아래 링크의 Unreal Engine 추가 설정이 되어 있어야 합니다.

  • 1.5 Unreal SDK 설치 | 1.5.6.1. Swift 환경 설정

  • 1.5 Unreal SDK 설치 | 1.5.6.8. iOS 빌드 SwiftSupport 관련 앱스토어 리젝 이슈

• (중요) Android 빌드를 하기 위해서는 아래 링크의 Unreal Engine 추가 설정이 되어 있어야 합니다.

  • 1.5 Unreal SDK 설치 | 1.5.5.6. Unreal Engine aar imports 설정 변경

1.5.3.3. 카카오게임 SDK 설정 하기

1. Unreal Editor에서 세팅 -> 프로젝트 세팅 메뉴를 선택합니다.

    

2. 좌측 메뉴의 플러그인 -> KakaoGameSDK 항목에서 카카오게임 SDK 설정이 가능한 메뉴가 있습니다.

1.5.3.4. 카카오게임 속성 설정

1. 먼저 카카오게임 속성 설정을 해야 합니다. 아래는 설정 항목에 대한 설명 입니다.

1. 아래 그림과 같이 카카오게임 속성을 설정하도록 합니다.

1.5.3.5. 카카오 멀티앱 로그인 기능 사용시 필요한 설정

SDK 3.11.0 버전부터 iOS의 경우 카카오 멀티앱 로그인을 지원하게 됩니다.(Android는 기존처럼 키해시로 지원가능)

그에 따라 멀티앱 로그인을 사용하고 싶은 게임에서 각각 프로젝트의 언리얼 Setting UI 상에서 Kakao MultiApp Login 체크 박스를 클릭 후에 빌드합니다.

중요 : 기존처럼 하나의 앱에서 사용할 게임들은 저 체크박스를 해제 상태로 두시면 됩니다.(해당 옵션을 설정하는 경우 redirect uri 설정이 잘못될 수 있어서 사용하지 않는 앱에서는 반드시 해제 상태로 두어야 합니다.)

1.5.4. IDP 인증 정보 설정

1.5.4.1.카카오 정보 설정

게임에서 카카오 인증을 사용할 경우, 설정 하도록 합니다.

1. 카카오 인증을 사용할 경우, Kakao Login 체크 박스를 클릭합니다.

1.5.4.2.구글 정보 설정

게임에서 구글(구글게임 포함) 인증을 사용할 경우, 설정 하도록 합니다.

1. 구글 인증을 사용할 경우, Google Login 체크 박스를 클릭합니다.

    

2. iOS앱에서 구글 인증을 할 경우, iOS 클라이언트 ID를 설정합니다.

    

3. 안드로이드앱에서 구글 인증하거나, 구글 게임 인증을 사용할 경우, Webapp Client ID를 설정합니다.

    

4. Windows에서 구글 인증을 사용할 경우 Webapp Client Secret을 설정합니다.

    

5. 구글 AppId를 설정합니다.

    

6. 구글 인증시, 기본 퍼미션 이외에 추가로 더 사용자의 동의를 받을 퍼미션이 있다면 목록을 추가하도록 합니다. 없을 경우, 해당 과정은 생략합니다.

    

1.5.4.3. 구글 게임 관련 언리얼 엔진 설정

구글 인증을 사용하는 경우 추가로 Google Play Service 설정이 필요합니다.

(프로젝트 세팅 -> 플랫폼 -> Android -> Google Play Services 메뉴에서 설정합니다.)ㅇ

1. Enable Google Play Support 체크 박스를 클릭합니다.

2. 위에서 설정한 구글 AppId를 Games App ID 항목에 설정합니다.

1.5.4.4. 페이스북 정보 설정

게임에서 페이스북 인증을 사용할 경우, 설정 하도록 합니다.

1. 페이스북 인증을 사용할 경우, Facebook Login 체크 박스를 클릭합니다.

    

2. 페이스북 App Key를 등록합니다.

    

3. 페이스북 Client Token을 등록합니다. (SDK 3.15.0 이상을 사용하는 경우 필수)

    

4. 페이스북 App Title을 등록합니다. 페이스북 로그인창이 노출 될 때 표기되는 타이틀입니다.

    

5. 페이스북 인증시, 기본 퍼미션외 추가로 더 사용자의 동의를 받을 퍼미션이 있다면, Add버튼을 눌러서 추가하도록 합니다. 없을 경우, 해당 과정은 생략합니다.

    

1.5.4.5. Sign in with Apple 정보 설정

게임에서 Sign in with Apple을 사용할 경우, 설정 하도록 합니다.

1. 아래 링크에 따라서 언리얼 엔진 설정을 추가합니다. (iOS Only)
   SigninWithApple 환경 설정

2. SigninWithApple 체크 박스를 클릭합니다.

    

3. 애플 어드민에서 발급받은 ClientId 항목을 입력합니다.

1.5.4.6. Game Center 정보 설정 (iOS Only)

게임에서 Game Center 인증을 사용할 경우, 설정 하도록 합니다.

프로젝트 세팅 -> 플랫폼 -> iOS-> Online -> Enable Game Center Support 체크 박스를 클릭합니다.

1.5.5. Android 플랫폼 설정

1.5.5.1. 기본 설정

• 플러그인에 포함된 KakaoGameSDK_Android_UPL.xml 파일을 통해 SDK에 필요한 기본 설정을 추가하고 있습니다.

• SDK 에서는 아래 퍼미션들을 추가해서 사용하고 있습니다.

  • android.permission.INTERNET

  • android.permission.ACCESSNETWORK_STATE

• ADID 를 얻기 위한 구글 설정

  • 구글 Ads 최신 버전에서 해당 설정이 없는 경우 앱이 동작하지 않는 이슈가 있어 아래와 같이 기본 설정되어 있습니다.

  • 만약 게임에서 AdMob을 사용하고 있는 경우, KakaoGameSDK_Android_UPL.xml 파일에서 해당 필드에 게임의 AdMob App Id를 삽입합니다.

    KakaoGameSDK_Android_UPL.xml

    ... <!-- Google Ads Default Setting START --> <meta-data   android:name="com.google.android.gms.ads.APPLICATION_ID"   android:value="ca-app-pub-3940256099942544~1234567890"/> <!-- Google Ads Default Setting END --> ...

1.5.5.2. APK Packaging 설정

1. 프로젝트 셋팅 -> 플랫폼 -> Android 메뉴를 선택합니다.

2. 아래와 같이 APK Packaging 메뉴에서 Minimun SDK Version과 Target SDK Version을 설정합니다.

   1. Minumum SDK Version : 23 (SDK 3.17.5 이하 버전인 경우 21로 설정합니다.)

   2. Target SDK Version : 31

1.5.5.3. Manifest 설정

Unreal Engine의 설정 메뉴와 플러그인의 KakaoGameSDK_Android_UPL.xml 파일을 통해서 Android Manifest에 값을 추가하거나 수정할 수 있습니다.

• 커뮤니티 웹뷰를 사용하는 경우, 바로가기 기능을 위하여 아래 퍼미션을 추가합니다.

  • com.android.launcher.permission.INSTALL_SHORTCUT

• API 23 이상에서는 앱이 일반 텍스트 HTTP와 같은 일반 텍스트 네트워크 트래픽을 사용하는지 여부를 설정할 수 있습니다.

  • android:usesCleartextTraffic="true"

     

1.5.5.4. Http 사용 설정

targetSdkVersion을 28 버전 이상으로 설정하고 http 통신을 사용하는 게임은 아래와 같은 설정이 필요합니다.

카카오 게임 SDK 내부에서는 http를 사용하지 않습니다. 개발사에서 cdn등 이슈로 http 콜이 필요한 경우에만 설정합니다.

• http 콜이 필요한 도메인 설정

  • KakaoGameSDKPlugin/Source/KakaoGameSDKPlugin/ThirdParty/Android/res/xml/network_security_config.xml 파일에 domain 추가

    network_security_config.xml

     <?xml version="1.0" encoding="utf-8"?> <network-security-config>   <domain-config cleartextTrafficPermitted="true">     <!-- Add Your Http Domain -->     <domain includeSubdomains="true">example.com</domain>   </domain-config> </network-security-config>

• KakaoGameSDK_Android_UPL.xml 파일에서 networkSecurityConfig 설정

  KakaoGameSDK_Android_UPL.xml

1.5.5.5. 키 해시 확인 및 등록 방법

• 앱의 빌드를 위해서는 빌드 머신의 키 해시를 등록해야 하며 다음과 같은 방법으로 키 해시를 확인하실 수 있습니다.

• 디버그 키 해시 및 릴리즈 키 해시를 위 가이드대로 구해서 [게임센터 > 게임관리 > 키 해시등록] 메뉴에 등록해주세요.

1.5.5.6. Unreal Engine aar-imports 설정 변경 

Unreal Engine의 아래 파일에서 엔진에서 필요한 종속성을 추가하고 있습니다.

(UE_4.XX/Engine/Build/Android/Java/aar-imports.txt)

KakaoGame Android SDK에서 포함하고 있는 다른 항목과 충돌하여 에러가 발생할 수 있어 다음과 같이 com.google.android.gms 항목들을 제거합니다.

aar-imports.txt

1.5.5.7. Unreal Engine 빌드 Gradle 버전 변경

KakaoGame Android SDK의 경우 SDK 버전에 따라서 아래와 같이 Gradle 버전을 지원하고 있습니다.

만약 호환되지 않은 버전인 경우 빌드 에러가 발생할 수 있습니다.

Unreal Engine의 다음 경로의 gradle-wrapper.properties 파일에서 distributionUrl을 수정하여 gradle 버전을 변경할 수 있습니다.

(UE_4.2X/Engine/Build/Android/Java/gradle/gradle/wrapper/gradle-wrapper.properties)

gradle-wrapper.properties

 SDK v3.14.11 이상을 적용하는 경우 Gradle v6.1.1 이상으로 설정 되어 있어야 합니다.

1.5.5.8. Unreal Engine Android 12 빌드 지원

Android 12 디바이스를 지원하기 위해 intent-filter를 사용하는 activity, service, broadcast receiver에서는 android:exported 속성을 명시적으로 선언해야 합니다.

( )

Android 빌드 시 언리얼 엔진에서 기본으로 사용하는 GameActivity와 SplashActivity에 Android 12 대응을 위한 속성을 추가해야 합니다.

• 다음 경로에서 UnrealBuildTool.csproj 파일을 찾아서 실행합니다. (Visual Stidio가 설치되어 있어야 합니다.)
  (UE_4.XX\Engine\Source\Programs\UnrealBuildTool\UnrealBuildTool.csproj)

• 프로젝트의 UEDeployAndroid.cs 파일에서 아래와 같이 수정합니다.
  (UE_4.XX\Engine\Source\Programs\UnrealBuildTool\Platform\Android\UEDeployAndroid.cs)

• GenerateManifest 함수에서 SplashActivity, GameActivity 설정 부분에 다음 코드를 추가하고 Visual Studio에서 빌드를 수행합니다.

1.5.6. iOS 플랫폼 설정

1.5.6.1. Swift 환경 설정

Unreal Swift Issue

• Unreal Engine의 아래 경로에서 UnrealBuildTool.csproj 파일을 확인할 수 있습니다.
  (UE_4.XX/Engine/Source/Programs/UnrealBuildTool/UnrealBuildTool.csproj)

• UnrealBuildTool.csproj 파일을 클릭하여 Visual Studio를 실행합니다. (Mac에서 Visual Studio Community를 사용해도 됩니다.)

• Unreal 5.x 버전

  • 프로젝트에서 XcodeProjectLegacy.cs 파일을 선택합니다. 
    (UE_5.XX/Engine/Source/Programs/UnrealBuildTool/ProjectFiles/Xcode/XcodeProjectLegacy.cs)

• Unreal 4.x 버전

  • 프로젝트에서 XcodeProject.cs 파일을 선택합니다. 

  • (UE_4.XX/Engine/Source/Programs/UnrealBuildTool/ProjectFiles/Xcode/XcodeProject.cs)

• XcodeProject.cs 파일의 AppendProjectBuildConfiguration 함수에서 Swift 설정 관련 코드를 추가합니다.

  XcodeProject.cs

  XcodeProject.cs

• 프로젝트에서 IOSToolChain.cs 파일을 선택합니다. 
  (UE_4.XX/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSToolChain.cs)

• IOSToolChain.cs 파일의 GetLinkArguments_Global 함수에서 Swift 설정 관련 코드를 추가합니다.

  IOSToolChain.cs

  IOSToolChain.cs

  • Unreal 5.x 버전

  • Unreal 4.x 버전

• 코드 추가 후 변경 사항을 적용하기 위해서 다음과 같이 빌드를 수행합니다.

1.5.6.3. SigninWithApple 환경 설정

• Unreal Engine 4.25 이상 버전을 사용하는 경우

  • 프로젝트 DefaultEngine.ini의 /Script/IOSRuntimeSettings.IOSRuntimeSettings 부분에 다음과 같이 bEnableSignInWithAppleSupport을 추가합니다.

• Unreal Engine 4.24 이하 버전을 사용하는 경우

  • Unreal Engine의 아래 경로에서 UnrealBuildTool.csproj 파일을 확인할 수 있습니다.
    (UE_4.XX/Engine/Source/Programs/UnrealBuildTool/UnrealBuildTool.csproj)

  • 프로젝트에서 IOSExports.cs 파일을 선택합니다. 
    (UE_4.XX/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExports.cs)

  • IOSExports.cs 파일의 WriteEntitlements 함수에서 SigninWithApple 설정 관련 코드를 추가합니다.

    IOSExports.cs

    IOSExports.cs

  • 프로젝트 DefaultEngine.ini의 /Script/IOSRuntimeSettings.IOSRuntimeSettings 부분에 다음과 같이 bEnableSignInWithAppleSupport을 추가합니다.

1.5.6.4. 접근 권한 설정

1. 카카오게임 SDK에서는 카메라와 포토라이브러리에 접근 권한이 필요합니다. 따라서 해당 부분의 접근 권한 설명을 아래와 같이 입력하도록 합니다.

1. Additional Plist Data에 다음과 같이 추가할 수 있습니다. 

Additional Plist Data

1.5.6.5. 게임 내 지원 언어 리소스

1. KakaoGameSDK에서 제공하는 언어를 사용자의 기기 언어 설정에 맞게끔 로드하기 위해서 info.plist 설정 필요.

1. Unreal Engine의 Additional Plist Data에 다음과 같이 추가할 수 있습니다.

Additional Plist Data

1.5.6.6. 사용자 추적 허용 팝업 노출 제어하기

iOS 14 이상 버전을 사용하는 사용자로 하여금 추적 허용 팝업을 노출할 수 있는 기능을 제공하고 있습니다.

(NSUserTrackingUsageDescription 권한 설정이 필요합니다.)

1.5.6.7. (참고) 다중 Bundle ID 지원에 대한 안내

• 한 앱(app id)에 대하여 bundle ID를 여러 개 사용할 수 있습니다.

  • 테스트 빌드 등 복수의 번들 아이디가 필요한 경우를 지원 해드립니다.

  • 단, 게임센터에 등록된 bundle ID는 라이브 버전 (마켓에 올라가는 빌드 버전)과 일치해야 합니다.

• 아래의 규칙에 해당하는 bundle ID는 카카오게임 API를 호출할 수 있습니다.
  단, 일부 기능에 대해 다소 제약이 있을 수 있습니다.

1.5.6.8. iOS 빌드 SwiftSupport 관련 앱스토어 리젝 이슈

Unreal에서 Swift 관련 라이브러리 설정 후 빌드를 하게 되면 ipa 파일 내에 SwiftSupport 폴더가 포함되어 있지 않습니다.

앱스토어에서 다음과 같은 사유로 앱 등록이 거절될 수 있습니다. (ITMS-90426: Invalid Swift Support - The SwiftSupport folder is missing.)

Utils 폴더에 포함되어 IOSIPAScript  스크립트를 이용하여 SwiftSupport 폴더가 추가된 ipa를 생성할 수 있습니다.

• ipa_path는 ipa 파일의 절대 경로로 입력되어야 합니다.

• toolchain_path가 /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.0/iphoneos 기본 경로로 설정되어 있습니다.

• toolchain_path5_5가 /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.5/iphoneos 기본 경로로 설정되어 있습니다.

(빌드 환경에 따라서 내부 스크립트 수정이 필요할 수 있습니다.)

스크립트는 다음과 같이 ipa_path로 unreal에서 ios 빌드 후 생성된 ipa 파일의 경로를 넘겨서 사용합니다.

스크립트 동작이 완료 되면 -with-swift-support 가 붙은 ipa 파일이 생성 되고 내부에 SwiftSupport 폴더가 포함 된 것을 확인할 수 있습니다.

1.5.7. Windows 플랫폼 설정

1.5.7.1. 기본 설정

• 플러그인의 아래 경로에 KakaoGame Windows SDK의 Binary(x64)가 포함되어 있습니다.
  (KakaoGameSDKPlugin/Source/KakaoGameSDKPlugin/ThirdParty/Windows/Binary)

• Unreal 환경에서 Windows SDK를 사용하기 위해서는 Binaries/Win64 폴더에 KakaoGame Windows SDK가 포함되어 있어야 합니다.

  • 플러그인의 KakaoGameSDKPlugin.Build.cs 파일에 아래와 같이 기본 설정이 되어 있습니다.

  • Unreal Editor에서 Windows 빌드를 수행하는 경우 KakaoGame Windows SDK가 프로젝트의 Binaries/Win64와 빌드 된 경로의 PROJECT_NAME/Binaries/Win64 경로에 복사가 됩니다.

1.5.7.2. Unreal Editor 모드

프로젝트에 플러그인을 추가하고 실행하는 경우 KakaoGame Windows SDK가 기본적으로 프로젝트의 Binaries/Win64에 포함되어 있지 않아 Editor 환경에서 KakaoGameSDK 기능을 사용할 수 없습니다.

KakaoGame Windows SDK의 Binary를 프로젝트의 Binaries/Win64의 경로에 직접 추가해야 합니다.

(Unreal Editor에서 Windows 빌드를 수행하는 경우 자동으로 추가됩니다.)

• 64-bit 환경인 경우 다음 경로의 파일들을 복사합니다. (KakaoGameSDKPlugin/Source/KakaoGameSDKPlugin/ThirdParty/Windows/Binary/x64)

• Editor에서 로그인 기능을 사용하기 위해서는 에서 Windows 관련 설정이 필요합니다.