Unity SDK Installation
- Eric
- KG PDM
- 1 1. Installation and Runtime Environment
- 2 2. SDK File Structure
- 3 3. SDK Installation
- 4 4. Kakao Game SDK Configuration
1. Installation and Runtime Environment
Minimum Version
Unity 2021.3.37f1 or later
Recommended Version
Unity 2022.3.21f1 or later
If you do not use the recommended version, you may encounter the following issues:
The app may crash upon execution with the message "USING MEMORY ADDRESSES FROM MORE THAN 16GB OF MEMORY." (Related Issues)
In version 2018.x, there is a bug that causes a black screen to appear when building for Android 12 or higher.
As gradle uses 6.7.1, certain Unity versions may require an upgrade.
2. SDK File Structure
The provided KakaoGamesSDK_Unity_[버전].zip file consists of the following files
File | Description |
|---|---|
KakaoGamesSDK.unitypackage |
|
com.kakaogames.sdk-[버전].tgz |
|
SampleApp.zip |
|
ApiReference.zip |
|
3. SDK Installation
3.1. Installing via unitypackage
First, open the game project in Unity.
Run the KakaoGamesSDK.unitypackage file, and a menu will appear in Unity allowing you to import it. Proceed with the import with all items checked.
When building on macOS, you may encounter a warning like below:
Click ? > Click Open Privacy & Security Settings > Click Allow Anyway, then
click Open.
3.1.1 Installing Newtonsoft.Json Package
As the SDK uses Newtonsoft.Json, this package must be installed.
Open Packages/manifest.json in your project’s root directory and add "com.unity.nuget.newtonsoft-json": "3.0.2".
{
"dependencies": {
//...
"com.unity.nuget.newtonsoft-json": "3.0.2"
}
}If not added, the following error will occur, and the build will fail.
3.2. Installing via Package Manager (tgz file)
Open the Package Manager via the "Window" menu.
Install the dependencies via Add Package from tarball…
Install in the following order: EDM, Firebase App, Firebase Crashlytics.
Similarly, install using the file com.kakaogames.sdk-<버전>.tgz package.
4. Kakao Game SDK Configuration
4.1. Opening the Kakao Game SDK Configuration Inspector
SOnce the SDK installation is complete, you’ll see a new menu in Unity: KakaoGames/Configure SDK.
Clicking on it will take you to KGTConfiguration.asset. Alternatively, you can directly check the Assets/KakaoGames/KGTConfiguration.asset file's Inspector.
You can configure the properties to be used in Kakao Games through the KGTConfiguration.asset Inspector.
4.2. Common Settings
4.2.1. Basic Settings
First, configure the basic settings for Kakao Games. Be sure to check the descriptions for each setting.
Kakao Games SDK Basic Settings | ||||
|---|---|---|---|---|
Key | Type | Required | Description | Example |
App Id | String | O | Can be found in one of the two following locations. | 909428 |
App Secret | String | O | Same as the native app key found in the Kakao Developers Page > My Applications > Select App > App Settings > Summary Information. | c3c38bbfa3828b342d946e9770c974d0 |
Log Level | Enum | O | Sets the SDK log output level. You can choose from "Verbose," "Debug," "Error," or "None." | None |
Enter the Kakao Games basic settings as shown in the image below.
After configuring, click the "Test Configuration" button.
If configured correctly
If configured incorrectly
4.3. Android Settings
4.3.1. Custom Build File Settings
Navigate to Player → Publishing Settings → Build to configure the custom files.
The following custom build files are mandatory for the SDK:
| 2021.3 | 2022.3 |
|---|---|---|
Required Items |
|
|
AndroidManifest.xml | Automatically generated by the SDK's internal logic. | Automatically generated by the SDK's internal logic. |
mainTemplate.gradle | Must be checked, and necessary dependencies are automatically configured by EDM. Android dependencies are set up through the External Dependency Manager. | Must be checked, and necessary dependencies are automatically configured by EDM. Android dependencies are set up through the External Dependency Manager. |
launcherTemplate.gradle | Add the following lines to the automatically generated file: apply plugin: 'com.google.firebase.firebase-perf'
apply plugin: 'com.google.firebase.crashlytics' | Add the following lines to the automatically generated file: apply plugin: 'com.google.firebase.firebase-perf'
apply plugin: 'com.google.firebase.crashlytics' |
baseProjectTemplate.gradle | Add the following lines to the automatically generated file: | Add the following lines to the automatically generated file: |
gradleTemplate.properties | Use the file automatically generated by Unity and EDM. | Use the file automatically generated by Unity and EDM. |
settingTemplate.gradle | File doesn't exist in version 2021.3. | Use the automatically generated file. |
4.3.2. Permission Settings
You can add the permissions needed by the game in the Assets/Plugins/Android/AndroidManifest.xml file.
4.3.3. Setting google-services.json
Download the google-services.json file that matches the game's settings.
Place the downloaded file under the Assets/Plugins/Android folder.
Firebase sdk will automatically generate google-services.xml or google-services-desktop.json.
If not using firebase sdk isn’t installed, download generate_xml_from_google_services_json.exe and generate_xml_from_google_services_json.py from GitHub - firebase/firebase-cpp-sdk: Firebase C++ SDK and add them to the project. Or manually create google-services.xml or google-services-desktop.json.
4.4. iOS Settings
4.4.1. Setting Minimum Supported Version
In Unity3D, go to "File" -> "Build Settings...".
Set the platform to iOS in the "Build Settings" window, then click "Player Settings...
The minimum supported iOS version for the KakaoGames SDK is iOS 13.0.
Click the Build button to build, which will generate an Xcode project upon success.
4.4.2. Multi-App Login Settings
If the game uses multi-app login, check the "Kakao MultiApp Login" checkbox in the Inspector before building.
4.4.3. Native SDK Dependency Configuration
You can remove or add dependencies as needed in the Kakaogames/Edtior/KakaoGamesDependencies.xml file.
Modify the iosPods section by removing or adding iosPod entries as required.
For example, if you only want to use the Kakao module,
You can configure it as shown.
4.4.4. iOS App Localization Settings
This section covers the steps to configure localization.
For example, we'll set up localization for the "User Tracking Usage Description.”
Install Localization.
Go to Project Settings - Localization and click Create.
Click the Locale Generator and select the desired countries.
In MetaData, click on iOS-App Info.
Set the default country. In this example, we’ll use “en.”
Open the "Localization Table" window from Window > Asset Management > Localization Scene Controls and create a table named 'App Data'.
In Edit Table Collection configure the multilingual setting.
Finally, add the table to the User Tracking Usage Description.
If set up correctly, the app will apply the localization.
4.5. IDP Settings
4.5.1. Kakao Information Settings
If your game uses Kakao authentication, configure the settings accordingly.
Click the Kakao checkbox if using Kakao authentication.
Set the App Key if using the Windows SDK.
4.5.2. Sign in with Apple Information Settings
If your game uses Sign in with Apple, configure the settings accordingly.
Click the SignInWithApple checkbox if using Sign in with Apple.
Enter the ClientId issued by the Apple Admin.
Additional Sign in with Apple settings may be required depending on your Unity version.
4.6. Notes for Using Unity SDK
4.6.1. Reference When Using PlayerPref Class
The iOS/Android Native SDK has internal logic that stores necessary values in the app data.
If the developer calls PlayerPref deleteAll to clean up game data, the SDK may malfunction because it deletes data that the SDK requires.
To avoid this, the developer should organize the keys/values used and implement the cleanup using the deleteKey API (not deleteAll), ensuring only the game data saved by the game itself is deleted.