1. Installation and Runtime Environment

• Minimum version

  • Supports Unreal 4.24.3 or higher

2. Configuring SDK Files

The KakaoGameSDK_Unreal_[Version].zip file consists of the following files:

3. SDK Configuration

3.1. Add Unreal Plugin

• In the Unreal project folder, locate the Plugins folder. (If the Plugins folder does not exist, create it.)

• Add the KakaoGameSDKV4 folder to the Plugins folder.

  Open

  

• Activate the newly added KakaoGameSDK in the Unreal Engine's plugin menu.

  Open

  

   

• To use the Unreal SDK in the project, add the KakaoGameSDKV4 and Json modules to the project’s Build.cs file as shown below.
  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. Configure Unreal Engine

• (Important) To build for iOS, the platform settings in the following link must be configured:

  • Unreal SDK Installation | 6. iOS Platform Configuration

• (Important) To build for Android, the platform settings in the following link must be configured:

  • Unreal SDK Installation | 5. Android Platform Configuration

4. Configure the KakaoGame SDK

1. In Unreal Editor, select Settings -> Project Settings.

2. In the left menu, under Plugins -> KakaoGameSDK 4.0, there is a menu where the KakaoGame SDK can be configured.

4.1. Configure KakaoGame Properties

1. Configure the KakaoGame properties. Below is an explanation of the configuration items.

2. Configure the KakaoGame properties as shown below.

4.2. IDP Authentication Information Configuration

4.2.1. Kakao Information Configuration

Configure the following settings if Kakao authentication is used in the game.

When using Kakao Login in a Windows environment or Unreal Editor environment, additional configuration of the JavaScript Key is needed.

In games that use Kakao MultiApp Login on mobile devices, click the Kakao MultiApp Login checkbox in the project’s Setting UI before building.

(Note: If intended to use MultiApp Login, further consultation is required.)

4.2.2. Sign in with Apple Information Configuration

Configure the following settings if Sign in with Apple is used in the game.

1. Add the Unreal Engine settings according to the link below (iOS Only):
   SigninWithApple Environment Configuration

2. Click the SigninWithApple checkbox.

3. Enter the ClientId issued by Apple Admin.

5. Android Platform Configuration

5.1. Basic Configuration

• The KakaoGameSDKV4_Android_UPL.xml file included in the plugin adds the basic settings required by the SDK.

• The SDK uses the following permissions:

  • android.permission.INTERNET

  • android.permission.ACCESSNETWORK_STATE

• Google Ads Configuration

  • In the latest version of Google Ads, the app may not function if the following setting is not configured, so it is set by default as shown below.

  • If the game uses AdMob, insert the game’s AdMob App Id into the corresponding field in the KakaoGameSDKV4_Android_UPL.xml file.

    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 Configuration

1. Select Project Settings -> Platforms -> Android.

2. In the APK Packaging menu, configure the Minimum SDK Version and Target SDK Version as follows:

   1. Minimum SDK Version : 23

   2. Target SDK Version : 34

5.1.2. Manifest Configuration

You can add or modify values in the Android Manifest through the Unreal Engine settings menu and the KakaoGameSDKV4_Android_UPL.xml file

• In API 23 and above, configure whether the app uses plaintext network traffic such as HTTP:

  • android:usesCleartextTraffic="true"

5.1.3. HTTP Usage Configuration

If the targetSdkVersion is set to 28 or higher and the game uses HTTP communication, the following configuration is required.

The Kakao Game SDK does not use HTTP internally. This configuration is only necessary if the developer needs to use HTTP calls for issues like CDN.

• Setting HTTP Domains

  • Add the required domains to the KakaoGameSDKV4/Source/KakaoGameSDKV4/ThirdParty/Android/res/xml file.

    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>

• Configure the networkSecurityConfig setting in the KakaoGameSDKV4_Android_UPL.xml file:

  KakaoGameSDKV4_Android_UPL.xml

5.1.4. Key Hash Verification and Registration Method

• To build the app, register the build machine's key hash. Verify the key hash using the following method:

• Obtain the debug key hash and release key hash as per the guide above and register them in the [Game Center > Game Management > Key Hash Registration] menu.

5.2. Unreal Engine Configuration

5.2.1. Modify Unreal Engine aar-imports Settings

In the following file of Unreal Engine, the necessary dependencies for the engine are added:

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

To avoid conflicts with other items included in the KakaoGame Android SDK, remove the com.google.android.gms items as shown below.

aar-imports.txt

5.2.2. Change Unreal Engine Build Gradle Version

5.2.2.1. Gradle Settings

The KakaoGame Android SDK supports Gradle versions as shown below, depending on the SDK version.

If an incompatible version is used, a build error may occur.

The Gradle version can be changed by modifying the distributionUrl in the gradle-wrapper.properties file located at the following path in Unreal Engine:

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

gradle-wrapper.properties

To support Android 14 (Target SDK 34), need Gradle v7.2 or higher.

Set Unreal Editor Android Gradle Plugin Version

To support Android 14 (Target SDK 34), configure the Android Gradle Plugin version.

(The version set may vary depending on the development environment.)

• In KakaoGameSDK 4.0 > Android > Gradle Plugin menu, configure the settings as follows:

  • Enable Use Custom Android Gradle Plugin checkbox

  • Set Custom Android Gradle Plugin Version to version 7.1.2

5.2.3. Unreal Engine Android Configuration

5.2.3.1. JDK Configuration for Android 14 Support

• If Gradle is set to v7.2 and the Android Gradle Plugin is set to v7.1.2, the JDK version needs to be changed.

• Download OpenJDK 11. (https://jdk.java.net/archive/)

• In the Android SDK build settings, set the JDK path to the newly downloaded JDK 11.

• When configuring Android build settings, set the Target SDK Version to 34.

5.2.4. Settings for Unreal Engine Android Build Issues

5.2.4.1. Configuration for Supporting Android 14 and Above Devices

When setting the Android targetSDK to 34 and building in development mode rather than shipping mode, the following error may occur on Android 14 devices, depending on the Engine environment:

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

The registerReceiver call in the GameActivity.java.template needs to be modified as follows:

5.2.4.3. Configuration for Supporting Android 12 and Above Devices

To support Android 12 devices, the androidattribute must be explicitly declared in any activity, service, or broadcast receiver that uses intent-filter.

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

When building for Android, properties need to be added to the GameActivity and SplashActivity used by Unreal Engine to support Android 12.

• Locate and run the UnrealBuildTool.csproj file in the following directory: (Visual Studio must be installed.)
  (UE_X.XX\Engine\Source\Programs\UnrealBuildTool\UnrealBuildTool.csproj)

• In the UEDeployAndroid.cs file of the project, make the following changes:
  (UE_X.XX\Engine\Source\Programs\UnrealBuildTool\Platform\Android\UEDeployAndroid.cs)

• In the GenerateManifest function, add the following code to the SplashActivity and GameActivity configuration sections, and then build it using Visual Studio.

6. iOS Platform Configuration

6.1. Basic Configuration

6.1.1. SigninWithApple Environment Configuration

• If using Unreal Engine 4.25 or higher,,

  • add bEnableSignInWithAppleSupport to the /Script/IOSRuntimeSettings.IOSRuntimeSettings section in the project's DefaultEngine.ini as follows:

6.1.2. Language Resource Support in the Game

To load the languages provided by KakaoGameSDK according to the user's device language settings, the info.plist configuration is required.

This can be added in Unreal Engine's Extra PList Data menu.

6.1.3. Control User Tracking Permission Popup Display

A feature is provided to display a user tracking permission popup for users on iOS 14 or later.

To use the tracking permission popup feature, the NSUserTrackingUsageDescription access permission message needs to be added.

6.1.4. Access Permission Configuration

If the KakaoGame SDK displays a user tracking permission popup, the NSUserTrackingUsageDescription setting is required.

Depending on the permissions used in the game, the access permission descriptions can be entered as shown in the following examples:

These can be added in Unreal Engine's Extra PList Data menu.

Personalized Ad Consent Notice Configuration

Additional Access Permissions Configuration

iOS environment, resources for multilingual support need to be added to the following path (Unreal Engine Guide)

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

Below are examples for English, Japanese, Korean, and Traditional Chinese settings.

InfoPlist.strings (en.lproj English Configuration File Example)

InfoPlist.strings (ja.lproj Japanese Configuration File Example)

InfoPlist.strings (ko.lproj Korean Configuration File Example)

InfoPlist.strings (zh-hant.lproj Traditional Chinese Configuration File Example)

If multilingual resources have been added, the resource folder is included within the .ipa as shown below.

6.1.5. Guide to Multiple Bundle ID Support

• Multiple bundle IDs can be used for a single app (app id).

  • Support is provided for cases where multiple bundle IDs are needed, such as for test builds.

  • However, the bundle ID registered in the Game Center must match the live version (the build version that goes to the market).

• Bundle IDs that meet the following conditions can call the KakaoGame API.
  Though there may be some restrictions on certain features.

6.2. Unreal Engine Configuration

6.2.1. Swift Environment Configuration

Unreal Swift Issue

How to manually modify in Unreal Engine

6.2.2. iOS Build SwiftSupport Related App Store Rejection Issue

When building with Swift-related library settings in Unreal, the SwiftSupport folder is not included in the ipa file.

The app registration may be rejected by the App Store for the following reason: (ITMS-90426: Invalid Swift Support - The SwiftSupport folder is missing.)

The IOSIPAScript.sh script included in the Utils folder can be used to generate an ipa file with the SwiftSupport folder added.

• The ipa_path should be entered as the absolute path of the ipa file.

  • Depending on the build environment, modifications to the IOSIPAScript.sh script may be required.

• The script is used by passing the path of the ipa file generated after building for iOS in Unreal as ipa_path as follows:

Once the script execution is complete, an ipa file with -with-swift-support appended to its name will be generated, and the SwiftSupport folder will be included inside.

6.2.2.1. IOSIPAScript

The IOSIPAScript.sh script is included in the Utils folder.

Depending on the build environment, modifications to the toolchain_path may be required.

(It is set to the default Xcode path.)

• The toolchain_path is set to the default path: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.0/iphoneos

• The toolchain_path5_5 is set to the default path: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.5/iphoneos

7. Windows Platform Configuration

7.1. Basic Configuration

• The binary of the KakaoGame Windows SDK is included in the following path of the plugin:
  (KakaoGameSDKV4/Source/KakaoGameSDKV4/ThirdParty/Windows/Binary)

• To use the Windows SDK in the Unreal environment, the KakaoGame Windows SDK must be included in the Binaries/Win64 folder.

  • The basic configuration is configured in the KakaoGameSDKV4.Build.cs file of the plugin as shown below:

• When performing a Windows build in Unreal Editor, the KakaoGame Windows SDK will be copied to the Binaries/Win64 of the project and the built path (PROJECT_NAME/Binaries/Win64).

7.2. Unreal Editor Mode

When adding and running the plugin in the project, the KakaoGame Windows SDK is not automatically included in the project's Binaries/Win64, so the KakaoGameSDK features cannot be used in the Editor environment.

You need to manually add the binary of the KakaoGame Windows SDK to the Binaries/Win64 path of the project.

(This will be automatically added when performing a Windows build in Unreal Editor.)

• For a 64-bit environment, copy the files from the following path: (KakaoGameSDKV4/Source/KakaoGameSDKV4/ThirdParty/Windows/Binary/x64)