1.5. Unreal SDK Installation
1.5. Unreal SDK Installation
1.5.1. Installation and Runtime Environment
Recommended
Unreal 4.24.3 or later recommended
1.5.2. Configuring SDK Files
The KakaoGameSDK_Unreal_[version] .zip file consists of the following files:
File | Description |
---|---|
KakaoGameSDKPlugin |
|
APIReference |
|
Sample.zip |
|
Utils |
|
Utils/IOSIPAScript.sh |
|
1.5.3. SDK Configuration
1.5.3.1. Add Unreal Plugin
Kakao Game SDKs for Android, iOS, and Windows are all included in the Unreal Plugin. There is no need to download or set up a separate SDK for the platforms
Find the Plugins folder in the Unreal project folder. (If the Plugins folder does not exist, create a folder.)
Add the KakaoGameSDKPlugin folder to the Plugins folder you created.
Activate the newly added KakaoGameSDK Plugin in the Plugin menu of Unreal Engine.
To use the Unreal SDK in the project, add the KakaoGameSDKPlugin and Json modules from the project's Build.cs file as follows.
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 Configuration
(Important) Unreal engine configuration setting for iOS environment.
(Important) Unreal engine configuration setting for Android environment.
1.5.3.3. Setting up KakaoGameSDK
Select the Setting -> Project Setting menu in the Unreal Editor.
There is a menu that allows you to set up KakaoGameSDK in the plug-in -> KakaoGameSDK item on the left menu.
1.5.3.4. Set KakaoGame SDK Properties
Enter a valid value in each field of the setup screen using the following table as reference:
Key | Type | Required | Description | Example |
---|---|---|---|---|
App Id | String | O | Issued App ID You can check it in 3.0 Admin -> Game Build -> Client Version Control. | 103815 |
App Secret | String | O | This is the same as the Native App Key, which can be found in Kakao Partner Center> Game Management> Select App> Game Details. | 951b75bf17fe0885ab5106ba2a9f9bc9 |
App Key | String | O | This is the same as the JavaScript Key, which can be found in Kakao Partner Center> Game Management> Select App> Game Details. | 8fb581e48885cb370a0f203433653583 |
Market (Android) | String | O | Setup a market for Android deployments. | googlePlay |
Market (Windows) | String | O | Setup a market for Windows deployments. | gameWeb |
App Version | String | O | App version | 1.0.0 |
Server Type | String | X | Server type. ("real") | real |
Debug Level | String | X | Log level of the Kakao Game SDK. ("Verbose", "Debug", "Error", "None") | none |
Set the KakaoGame attributes as shown in the picture below.
1.5.3.5. Settings required when using the Kakao multi-app login function
From SDK 3.11.0 version, iOS supports Kakao multi-app login (Android can support with key hash as before).
Accordingly, in the game you want to use the multi-app login, click the Kakao MultiApp Login check box on the Unreal Setting UI of each project and build it.
Important: As before, for games that will be used in one app, you can leave that checkbox unchecked.(If you turn it on, the redirect uri setting may be wrong, so be sure to leave it off in apps you are not using.)
1.5.4. IDP Authentication Configuration
1.5.4.1. Kakao information setting
If you use Kakao authentication in the game, set it up.
Activate the Kakao check button if Kakao IDP is used.
1.5.4.2. Google information setting
If you use Google (including Google Games) authentication in the game, set it up.
Activate the Google check button if Google IDP is used.
If you are authenticating with Google in iOS apps, set your iOS client ID.
If you want to use Google Apps authentication in your Android app, or if you want to use Google Apps authentication, set your Webapp Client ID.
If you use Google authentication on Windows, set Webapp Client Secret.
Set up Google AppId.
If you want to request Google permission for additional Google authentication, add it as shown in the following example.
1.5.4.3. Google Game Unreal Engine Settings.
If you use Google authentication, additional Google Play Service settings are required.
(Project Settings -> Platform -> Android -> Google Play Services menu)
Click the Enable Google Play Support checkbox.
Set Google AppId to the Games App ID item.
1.5.4.4. Facebook information setting
This explanation is applicable if Faebook IDP is used.
If you are using Facebook authentication, click the Facebook Login check box.
Register your Facebook App Key.
Register your Facebook App Title. When the Facebook login window appears, it is the exposed title.
Add additional permissions if needed for Facebook authentication.
Since the SDK provided by Facebook can not request Read permission and Publish permission at the same time, only Read permission can be added to Facebook authentication through the KakaoGame SDK.
(Publish permission: Permission to start with a specific word ("publish" or "manage") or "ads_management", "create_event", "rsvp_event", etc)
Therefore, if you need Publish-related functionality, you will need to get additional authentication with the Publish permission or use the Publish API provided by the Facebook SDK, such as ShareDialog.
1.5.4.5. SignInWithApple information setting
If you use Signin with Apple in your game, please set it up.
Add the Unreal Engine settings according to the link below. (iOS Only)
- SigninWithApple Environment SettingIf you use Signin with Apple, click the SigninWithApple check box.
Enter the ClientId field issued by Apple Admin.
1.5.4.6. GameCenter information Setting (iOS Only)
If you use Game Center authentication in the game, set it up.
Click the Project Settings -> Platform -> iOS -> Online -> Enable Game Center Support check box.
1.5.5. Android Environment Settings
1.5.5.1. Default Setting
The KakaoGameSDK_Android_UPL.xml file included in the KakaoGameSDKPlugin is adding the required preferences for SDK.
The SDK uses the following common permissions:
android.permission.INTERNET
android.permission.ACCESS_NETWORK_STATE
Add Google configuration to get ADID
If there is no setting in the latest version of Google Ads, there is an issue where the app does not work.
If your game uses AdMob, insert the game's AdMob App Id in the appropriate field. (KakaoGameSDK_Android_UPL.xml)
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 Setting
Select the Project Setting -> Platform -> Android menu.
Set the Minimun SDK Version and Target SDK Version in the APK Packaging menu.
Minumum SDK Version : 21
Target SDK Version : 31
1.5.5.3. Manifest Setting
Values can be added to Android Manifest through the settings menu of Unreal Engine and the KakaoGameSDK_Android_UPL.xml file of the plug-in.
If you are using the community webview, add the following permissions for the shortcut functionality
com.android.launcher.permission.INSTALL_SHORTCUT
API 23 or later allows you to set whether an app uses plain text network traffic such as plain text HTTP.
android:usesCleartextTraffic="true"
1.5.5.4. Setting Enable Http
If targetSdkVersion is set to 28 version or higher, and the game using http requires the following settings.
Do not use http inside the Kakao Game SDK. This is only required if the developer needs an http call such as cdn.
Domain settings that require http call
KakaoGameSDKPlugin/Source/KakaoGameSDKPlugin/ThirdParty/Android/res/xml/network_security_config.xml file to add domain list that requires http connection
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>
Set the above generated file to networkSecurityConfig in the KakaoGameSDK_Android_UPL.xml file
KakaoGameSDK_Android_UPL.xml
1.5.5.5. Confirming and registering key hash
Confirming and registering key hash Guide
The build machine's key hash must be registered for the built app. The key has can be confirmed with the following method.
Find the debug key hash and release key has will the guidelines provided below and register at [GameCenter > Admin > Register Key Hash].
1.5.5.6. Unreal Engine aar-imports Setting
The file below in Unreal Engine is adding the dependencies required by the engine.
(UE_4.XX/Engine/Build/Android/Java/aar-imports.txt)
As errors may occur due to conflicts with other items included in the KakaoGame Android SDK, remove com.google.android.gms items as follows.
KakaoGame Android SDK Dependencies (Link)
aar-imports.txt
1.5.5.7. Unreal Engine Build Gradle Version Change
Gradle version should be set for each SDK version as below.
If it is an incompatible version, a build error may occur.
You can change the gradle version by modifying distributionUrl in the gradient-wrapper.properties file of the Unreal Engine.
(UE_4.2X/Engine/Build/Android/Java/gradle/gradle/wrapper/gradle-wrapper.properties)
gradle-wrapper.properties
If SDK v3.14.11 or higher is applied, it must be set to Gradle v6.1.1 or higher.
1.5.5.8. Add Unreal Engine Android 12 Build Support Settings
Activity, service, and broadcast receiver using int-filter to support Android 12 devices must explicitly declare the android:exported attribute.
(https://developer.android.com/about/versions/12/behavior-changes-12#exported )
When you do Android Build, you need to add attributes for Android 12 devices to GameActivity and SplashActivity, which are used as defaults by Unreal Engine.
Find and run the UnrealBuildTool.csproj file on the following path. (Visual Stidio should be installed.)
(UE_4.XX\Engine\Source\Programs\UnrealBuildTool\UnrealBuildTool.csproj)Modify as follows in the UEDeployAndroid.cs file.
(UE_4.XX\Engine\Source\Programs\UnrealBuildTool\Platform\Android\UEDeployAndroid.cs)In the GenerateManifest function, add the following code to the SplashActivity, GameActivity settings and perform a build in Visual Studio.
1.5.6. iOS Environment Settings
1.5.6.1. Swift Setting
Unreal Swift Issue
Unreal Engine does not support mixing Objective-c and Swift. If used in combination, a build error occurs. iOS SDK includes Swift, so you need to add related settings.
You can check the UnrealBuildTool.csproj file in the path below of the Unreal Engine.
(UE_4.XX/Engine/Source/Programs/UnrealBuildTool/UnrealBuildTool.csproj)Click the file UnrealBuildTool.csproj to run VisualStudio (You can use VisualStudio Community in Mac).
Select the XcodeProject.cs file from the project.
(UE_4.XX/Engine/Source/Programs/UnrealBuildTool/ProjectFiles/Xcode/XcodeProject.cs)In the AppendProjectBuildConfiguration function of the XcodeProject.cs file, add the code related to Swift settings.
XcodeProject.cs
XcodeProject.cs
Select the IOSToolChain.cs file from the project.
(UE_4.XX/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSToolChain.cs)Add the code related to Swift settings in the GetLinkArguments_Global function of the IOSToolChain.cs file.
IOSToolChain.cs
IOSToolChain.cs
In order to apply the changes after adding the code, the build is performed as follows.
1.5.6.3. SigninWithApple Environment Setting
If you're using Unreal Engine 4.25 or higher
In the /Script/IOSRuntimeSettings.IOSRuntimeSettings section of DefaultEngine.ini, add bEnableSignInWithAppleSupport as follows.
If you are using Unreal Engine 4.24 or lower version
You can check the UnrealBuildTool.csproj file in the path below of the Unreal Engine.
(UE_4.XX/Engine/Source/Programs/UnrealBuildTool/UnrealBuildTool.csproj)Select the IOSExports.cs file from the project.
(UE_4.XX/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSExports.cs)Add the code related to SigninWithApple settings in the WriteEntitlements function of the IOSExports.cs file.
IOSExports.cs
IOSExports.cs
In the /Script/IOSRuntimeSettings.IOSRuntimeSettings section of DefaultEngine.ini, add bEnableSignInWithAppleSupport as follows.
1.5.6.4. Set access permissions
The Kakao Game SDK requires access to your camera and photo library. Therefore, enter a description of the access rights of the part as shown below.
Access Permission | Guide |
---|---|
NSCameraUsageDescription | It is used for customer center file attachment. |
NSPhotoLibraryUsageDescription | It is used for customer center file attachment. |
You can add it to the Additional Plist Data of the Unreal Engine as follows.
Additional Plist Data
1.5.6.5. Supported language resource
You need to set info.plist to load the language provided by KakaoGameSDK to match your device language setting.
Key | Type | Description | Example |
---|---|---|---|
Localized resources can be mixed | Boolean | You need to set the language provided by KakaoGameSDK to load in accordance with your device language setting. | YES |
You can add it to the Additional Plist Data of the Unreal Engine as follows.
Additional Plist Data
1.5.6.6. Control pop-up exposure to allow user tracking
iOS 14 users can display the user tracking permission pop-up.
SHOW_ADID_USAGE_POPUP attribute is added to the info.list.
1.5.6.7. (Reference) Support for Multiple Bundle IDs
Multiple bundle IDs can be used for one application(App ID).
Kakao will provide support for cases requiring multiple bundle IDS (e.g. test build).
Note that a bundle ID you set in GameCenter should equal to a bundle ID to release to AppStore.
A bundle ID can call KakaoGame API if it satisfies the following rule.
However, some functions may be restricted.
1.5.6.8. iOS Build SwiftSupport AppStore Rejection Issue
If you build after Swift setup in Unreal Engine, the SwiftSupport folder is not included in the ipa file.
App registration may be rejected in the appstore for the following reasons. (ITMS-90426: Invalid Swift Support - The SwiftSupport folder is missing.)
You can create ipa with the SwiftSupport folder added using the IOSIPAScript.sh script.
(IOSIPAScript.sh file is included in the Utils folder of the downloaded KakaoGameUnreal SDK.)
Inside the script, toolchain_path is set as /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/swift-5.0/iphoneos default path.
(Depending on the build environment, the script may need to be modified.)
In the script, the path of the ipa file generated after the ios build is received as ipa_path and used.
When the script action is complete, you can see that an ipa file with -with-swift-support is created and the SwiftSupport folder is included inside.
1.5.7. Windows Environment Settings
1.5.7.1. Default Setting
The plug-in includes binary x64 of the Kakao game window SDK.
(KakaoGameSDKPlugin/Source/KakaoGameSDKPlugin/ThirdParty/Windows/Binary/x64)In order to use Windows SDK in an Unreal environment, the Binaries/Win64 folder must contain the KakaoGame Windows SDK.
The KakaoGameSDKPlugin.Build.cs file has the default settings as below.
When Windows builds are performed in Unreal Editor, KakaoGame Windows SDK copies the Binaries/Win64 of the project and the PROJECT_NAME/Binaries/Win64 path of the built path.
1.5.7.2. Unreal Editor Environment
If you add and run KakaoGameSDKPlugin on a project, the KakaoGameSDK is not included in the project's Binaries/Win64 by default, so the KakaoGameSDK feature is not available in the Editor environment.
You need to add the binary of the KakaoGame Windows SDK to the path of the project's Binaries/Win64
(If you are building Windows in Unreal Editor, it will be automatically added.)
If you are in a 64-bit environment, copy the files in the following path: (KakaoGameSDKPlugin/Source/KakaoGameSDKPlugin/ThirdParty/Windows/Binary/x64)