1. 설치 환경 및 실행 환경

• 최소 버전

  • Unreal 4.24.3 이상 지원

2. SDK 파일 구성

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

3. SDK 환경 설정

3.1. Unreal Plugin 추가하기

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

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

  Open

  

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

  Open

  

   

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

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

3.2. Unreal Engine 설정하기

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

  • Unreal SDK 설치 | 6. iOS 플랫폼 설정

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

  • Unreal SDK 설치 | 5. Android 플랫폼 설정

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

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

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

4.1. 카카오게임 속성 설정

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

2. 아래와 같이 카카오게임 속성을 설정하도록 합니다.

4.2. IDP 인증 정보 설정

4.2.1. 카카오 정보 설정

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

Windows 환경 및 Unreal Editor 환경에서 카카오 로그인을 사용하는 경우 JavaScript Key를 추가로 설정해야 합니다.

모바일 환경에서 카카오 멀티앱 로그인을 사용하는 게임에서 각각 프로젝트의 Setting UI 상에서 Kakao MultiApp Login 체크 박스를 클릭 후에 빌드합니다.

(멀티앱 로그인을 사용하려는 경우 별도 문의가 필요합니다.)

4.2.2. Sign in with Apple 정보 설정

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

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

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

    

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

5. Android 플랫폼 설정

5.1. 기본 설정

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

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

  • android.permission.INTERNET

  • android.permission.ACCESSNETWORK_STATE

• ADID 를 얻기 위한 구글 설정

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

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

    KakaoGameSDKV4_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 --> ...

5.1.1. APK Packaging 설정

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

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

   1. Minimum SDK Version : 23

   2. Target SDK Version : 34

5.1.2. Manifest 설정

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

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

  • android:usesCleartextTraffic="true"

5.1.3. Http 사용 설정

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

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

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

  • KakaoGameSDKV4/Source/KakaoGameSDKV4/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>

• KakaoGameSDKV4_Android_UPL.xml 파일에서 networkSecurityConfig 설정

  KakaoGameSDKV4_Android_UPL.xml

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

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

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

5.2. Unreal Engine 설정

5.2.1. Unreal Engine aar-imports 설정 변경

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

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

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

aar-imports.txt

5.2.2. Unreal Engine 빌드 Gradle 버전 변경

5.2.2.1. Gradle 설정

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

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

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

(UE_X.XX/Engine/Build/Android/Java/gradle/gradle/wrapper/gradle-wrapper.properties)

gradle-wrapper.properties

Android 14 (Target SDK 34) 대응을 위해 Gradle v7.2 이상으로 설정 되어 있어야 합니다.

Unreal Editor Android Gradle Plugin 버전 설정

Android 14 (Target SDK 34) 대응을 위해 Android Gradle Plugin 버전 설정이 필요합니다.

(개발 환경에 따라서 설정하는 버전이 다를 수 있습니다.)

• KakaoGameSDK 4.0 > Android > Gradle Plugin 메뉴에서 아래와 같이 설정할 수 있습니다.

  • Use Custom Android Gradle Plugin 체크 활성화

  • Custom Android Gradle Plugin Version 버전 7.1.2 설정

5.2.3. Unreal Engine Android 설정

5.2.3.1. Android 14 지원을 위한 JDK 설정

• Gradle v7.2, Android Gradle Plugin v7.1.2 버전으로 설정한 경우 JDK 버전 변경이 필요합니다.

• OpenJDK 11 버전을 다운로드 합니다. (Archived OpenJDK GA Releases)

• Android SDK 빌드 설정에서 JDK 경로를 새로 다운로드한 JDK 11로 설정합니다.

• Android 빌드 설정 시 Target SDK 버전을 34로 설정합니다.

5.2.4. Unreal Engine Android 빌드 이슈 관련 설정

5.2.4.1. Android 14 이상 디바이스 지원을 위한 설정

Android targetSDK 34로 설정하고 Shipping이 아닌 개발 모드로 빌드하는 경우 Engine 환경에 따라서 Android 14 디바이스에서 아래와 같은 에러가 발생하는 경우가 있습니다.

UE_4.XX\Engine\Build\Android\Java\src\com\epicgames\ue4\GameActivity.java.template

아래 GameActivity.java.template 부분의 registerReceiver 호출 부분 수정이 필요합니다.

5.2.4.3. Android 12 이상 디바이스 지원을 위한 설정

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

(https://developer.android.com/about/versions/12/behavior-changes-12#exported )

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

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

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

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

6. iOS 플랫폼 설정

6.1. 기본 설정

6.1.1. SigninWithApple 환경 설정

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

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

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

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

Unreal Engine의 Extra PList Data 메뉴에서 추가할 수 있습니다. 

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

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

추적 허용 팝업 기능을 사용하기 위해서는 아래 NSUserTrackingUsageDescription 접근 권한 안내 문구 추가가 필요합니다.

6.1.4. 접근 권한 설정

카카오게임 SDK에서 사용자 추적 허용 팝업을 노출하는 경우 NSUserTrackingUsageDescription 설정이 필요합니다.

게임에서 사용하는 권한에 따라서 해당 부분의 접근 권한 설명을 아래와 같은 예시로 입력할 수 있습니다.

Unreal Engine의 Extra PList Data 메뉴에서 추가할 수 있습니다. 

맞춤형 광고 동의 안내 설정

추가 접근 권한을 설정하는 경우

iOS 환경에서 아래 경로에 다국어 지원을 위한 리소스 추가가 필요합니다. (Unreal Engine 가이드 문서)

{UEProjectDir}/Build/IOS/Resources/Localizations/

아래는 영어, 일본어, 한국어, 중국어(번체) 설정 예시입니다.

InfoPlist.strings (en.lproj 영어 설정 파일 예시)

InfoPlist.strings (ja.lproj 일본어 설정 파일 예시)

InfoPlist.strings (ko.lproj 한국어 설정 파일 예시)

InfoPlist.strings (zh-hant.lproj 중국어(번체) 설정 파일 예시)

다국어 리소스가 추가된 경우 .ipa 내부에 아래와 같이 리소스 폴더가 포함되어 있습니다.

6.1.5. 다중 Bundle ID 지원에 대한 안내

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

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

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

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

6.2. Unreal Engine 설정

6.2.1. Swift 환경 설정

Unreal Swift Issue

Unreal Engine에서 직접 수정하는 방법

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

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

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

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

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

  • 빌드 환경에 따라서 IOSIPAScript.sh 스크립트 수정이 필요할 수 있습니다.

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

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

6.2.2.1. IOSIPAScript

Utils 폴더에 포함되어 있는 IOSIPAScript.sh 스크립트 입니다.

빌드를 수행하는 환경에 따라서 toolchain_path 수정이 필요할 수 있습니다.

(기본 Xcode 경로로 설정되어 있습니다.)

• 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 기본 경로로 설정되어 있습니다.

7. Windows 플랫폼 설정

7.1. 기본 설정

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

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

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

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

7.2. Unreal Editor 모드

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

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

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

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