1.1. Unity SDK 설치
| 목차 |
|---|
...
1.1.1. 설치 환경 및 실행 환경
최소 버전
Unity 20172019.14.0 15f1 이상 지원
권장 버전
Unity 20182020.43.12 43f1 이상
| 참고사항 |
|---|
권장 버전을 사용하지 않을 경우, 아래와 같은 문제가 있습니다.
|
...
|
1.1.2. SDK 파일 구성
전달받은 KakaoGameSDK_Unity_[버전].zip 파일은 다음과 같은 파일들로 구성되어 있습니다.
파일 | 설명 |
|---|---|
KakaoGameSDK.unitypackage |
|
SampleApp.zip |
|
ApiReference.zip |
|
1.1.3. SDK 설치
1.1.3.1. Unity 패키지 파일 import하기
...
| 정보 |
|---|
Android용 카카오게임 SDK와 iOS용 카카오게임 SDK는 모두 Unity 패키지 내에 포함되어 있습니다. 별도로 해당 SDK를 설치할 필요는 없습니다. |
1.1.3.2. Migration의 경우
KakaoGameSdk.unitypackage를 실행하면, Unity3d툴에서 import할 수 있는 메뉴가 뜹니다.
기존 SDK에서 필요한 항목이 체크된 상태로 import를 진행합니다.
...
| 경고 |
|---|
이전 버전 SDK 파일들에 의해 컴파일 에러가 발생할 수 있습니다. |
...
Assets > Reimport All 또는 에디터를 재부팅하면 KGAssetImporter에 의해 자동으로 이전 SDK 파일들을 제거합니다.
...
이후 SDK 변경 사항들을 수정해주면 됩니다.
1.1.3.
...
3. 카카오게임 SDK 설정 인스펙터 열기
Unity 패키지 파일 import가 되면, Unity3d툴 메뉴에 Kakao라는 메뉴가 새로 생긴걸 확인할 수 있습니다.
...
...
ConfigureSDK를 클릭하면, 아래와 같이 카카오게임 SDK 설정이 가능한 인스펙터가 열립니다.
...
...
1.1.3.
...
4. 카카오게임 속성 설정
...
먼저 카카오게임 속성 설정을 해야 합니다. 먼저 설정 항목에 대한 설명을 확인하시길 바랍니다.
카카오게임 |
|---|
...
SDK 속성 | ||||
|---|---|---|---|---|
키 | 타입 | 필수 | 설명 | 예시 |
App Id | String | O | ||
아래 둘 중 한곳에서 확인할 수 있습니다. |
> 앱 설정 > 요약 정보 | 103815 | ||
App Secret | String | O | 카카오 |
개발자 페이지 > 내 어플리케이션 > 앱 선택 |
> 앱 설정 > 요약 정보에서 확인할 수 있는 |
네이티브 앱 키와 동일합니다. | 951b75bf17fe0885ab5106ba2a9f9bc9 | |||
Debug Level | String | X | SDK 로그 출력 레벨을 설정합니다. "Verbose", "Debug", "Error", "None" 중 하나를 선택할 수 있습니다. | None |
아래 그림과 같이 카카오게임 속성을 설정하도록 합니다.
...
설정 이후 잘 설정되었는지 확인하기 위해 Check configuration setting 버튼을 클릭합니다.
...
잘 설정되어있지 않을 경우, 아래와 같이 원인 문구가 나옵니다.
아래의 경우는 유효하지 않은 앱아이디를 사용하고 있어서 발생합니다.
기술PM님이 전달받은 앱아이디가 잘 등록되었는지 확인합니다. 잘 등록되어 있을 경우, 기술PM님께 문의부탁드립니다.
...
1.1.3.
...
5. 카카오 멀티앱 로그인 기능 사용시 필요한 설정
SDK 3.11.0 버전부터 iOS의 경우 카카오 멀티앱 로그인을 지원하게 됩니다.(Android는 기존처럼 키해시로 지원가능)
그에 따라 멀티 앱 로그인을 사용하고 싶은 게임에서 각각 게임 프로젝트 유니티 인스펙터 상에서 Kakao MultiApp Login 체크 박스를 클릭 후에 빌드합니다.
...
| 정보 |
|---|
중요 : 기존처럼 하나의 앱에서 사용할 게임들은 저 체크박스를 해제 상태로 두시면 됩니다.(저걸 켜면 redirect uri 설정이 잘못될 수 있어서 사용하지 않는 앱에서는 반드시 해제 상태로 두어야 합니다.) |
1.1.3.
...
채널링은 카카오 푸시를 사용하지 않으므로 체크해제 합니다.
...
푸시를 사용하지 않으므로, Push Setting 아래의 Push 체크 박스를 클릭합니다.
...
3.7.0SDK 이후 버전을 사용할 경우) 유니티 상의 gradle script에서도 해당 스크립트 부분을 제거해준다.
...
1.1.3.6. 구글 정보 설정
게임에서 구글(구글게임 포함) 인증을 사용할 경우, 설정 하도록 합니다.
구글 인증을 사용할 경우, Google 체크 박스를 클릭합니다.
...
...
iOS앱에서 구글 인증을 할 경우, iOS 클라이언트 ID를 설정합니다.
...
안드로이드앱에서 구글 인증하거나, 구글 게임 인증을 사용할 경우, Webapp Client ID를 설정합니다.
...
구글 인증시, 기본 퍼미션외 추가로 더 사용자의 동의를 받을 퍼미션이 있다면, Add버튼을 눌러서 추가하도록 합니다. 없을 경우, 해당 과정은 생략합니다.
...
1.1.3.7. 페이스북 정보 설정
게임에서 페이스북 인증을 사용할 경우, 설정 하도록 합니다.
페이스북 인증을 사용할 경우, Facebook 체크 박스를 클릭합니다.
...
페이스북 App Key를 등록합니다.
...
페이스북 App Title을 등록합니다. 페이스북 로그인창이 뜰때, 노출되는 타이틀입니다.
...
페이스북 Client Token을 등록합니다.
페이스북 인증시, 기본 퍼미션외 추가로 더 사용자의 동의를 받을 퍼미션이 있다면, Add버튼을 눌러서 추가하도록 합니다. 없을 경우, 해당 과정은 생략합니다.
...
FB SDK Settings를 클릭할 경우 Facebook SDK에서 생성한 FacebookSettings.assets을 확인할 수 있습니다. 빌드시 제대로 생성되었는지 확인이 필요합니다.
| 참고사항 |
|---|
페이스북에서 제공하는 SDK 에서는 인증 시 Read 퍼미션과 Publish 퍼미션을 동시에 요청할 수 없기 때문에 카카오 SDK를 통한 페이스북 인증 시에는 Read 퍼미션만 추가하 실 수 있습니다. (Publish 퍼미션: "publish" 나 "manage" 로 시작하는 퍼미션 이나 "ads_management", "create_event", "rsvp_event" 등) 때문에 Publish 관련 기능이 필요한 경우에는 Publish 퍼미션으로 추가 인증을 받거나 ShareDialog 같은 페이스북 SDK에서 제공하는 Publish API 를 사용하셔야 합니다. |
...
게임에서 Signin with Apple을 사용할 경우, 설정 하도록 합니다.
...
1.1.3.9. Signin with Apple 관련 빌드 스크립트 설정
Signin with Apple을 사용할 경우, SigninWithApple 체크 박스를 클릭합니다.
애플 어드민에서 발급받은 ClientId 항목을 입력합니다.
...
유니티 버전별로 signin with apple 관련 설정이 추가로 필요합니다.Assets
| 경고 |
|---|
...
...
docs.unity3d.com/2018.4/Documentation/ScriptReference/iOS.Xcode.PBXCapabilityType.SignInWithApple.html |
|
|
|
...
현재는 개발에서 사용중인 2018.4.12 버전에 대해서만 분기처리 되어 있기 때문에 개발사에서 적용중인 유니티 버전을 추가로 적용해야 합니다.
예) 2019.2.8 사용 중이라면 #if UNITY_2018_4_12 || UNITY_2019_2_8 형태로 추가해서 사용해야 합니다.
만약, 사용중인 유니티 버전을 추가 후에 버전에서 위의 코드에서 빌드 에러가 발생한다면, 해당 유니티 버전이 signin with apple capabilities를 추가하는 기능을 지원하지 않는 버전입니다.
그런 경우라면 우선 ios 타겟으로 빌드 후에 빌드된 Xcode project 상에서 수동으로 signin with apple capabilities를 추가해줘야 합니다.(참고 : iOS SDK 설치 내 6. Xcode 상에서 signin with apple 설정 참고: https://kakaogames.atlassian.net/wiki/spaces/KS3GFC/pages/413631668/1.3+iOS+SDK#1.3.3.6.-%EC%B9%B4%EC%B9%B4%EC%98%A4%EA%B2%8C%EC%9E%84-SDK-%EC%86%8D%EC%84%B1-%EC%84%A4%EC%A0%95 참고)
1.1.3
...
.9. Newtonsoft.Json 패키지 설치(SDK 3.15.0 이상)
SDK 3.15.0 이상부터 내부 로직에 newtonsoft-json을 사용하게 되면서 해당 패키지를 필수로 설치해야 합니다.
프로젝트 루트 디렉토리에서 Packages/manifest.json을 열고 "com.unity.nuget.newtonsoft-json": "3.0.2" 을 추가합니다.
| 코드 블럭 |
|---|
{
"dependencies": {
//...
"com.unity.nuget.newtonsoft-json": "3.0.2"
}
} |
| 참고사항 |
|---|
추가하지 않을 경우 다음과 같은 오류가 뜨며 빌드가 되지 않습니다. |
...
1.1.4. Android 설정
1.1.4.1. Permission 설정
unitypackage를 import 후에 Assets/Plugins/Android/AndroidManifest.xml
...
파일에 게임에서 사용할 permission을 추가
<uses-permission android:name="android.permission.XXXXXX" /> 형태로 추가
1.1
...
Unity3d툴에서 File -> Build Settings... 메뉴를 선택합니다.
아래와 같이 "Build Settings"창에서 Platfrom을 Android로 설정하고, "Player Settings..."버튼을 클릭합니다.
카카오게임 SDK의 안드로이드 최소 지원 SDK 버전은 15입니다. Settings for Android -> Other Settings -> Minimum API Level을 15이상으로 설정합니다.
Build 버튼을 클릭하여 빌드합니다.
1.1.3.12. Android 빌드 설정 및 빌드(3.7.x)
Unity3d툴에서 File -> Build Settings... 메뉴를 선택합니다.
3.7.0이후 버전 부터는 Android Gradle build를 지원합니다. Build System을 Gradle(New)로 선택합니다.
각 앱별로 넣어야 할 설정파일들이 있어서 바로 apk 빌드가 아닌 Android Studio로 Export Project를 선택합니다.
Export 버튼을 클릭하여 Android Studio Project를 Export 합니다.
1.1.3.13. Android 빌드 설정 및 빌드 (3.8.0 이후)
3.8.0 버전 부터는 별도의 프로젝트 Export 없이 바로 apk 빌드를 지원합니다.
다만, apk 빌드를 지원할 시에는 SDK 에서 제공하는 Assets/Plugins/Android/mainTemplate.gradle 파일을 수정하면 안 됩니다.(추가하고 싶은 라이브러리나 리소스 추가하는 것은 상관 없습니다.)
apk 빌드를 지원하기 위해서는 유니티에 포함된 gradle library 버전이 맞아야 하기 때문에 권장 유니티 버전을 사용하셔야 합니다.
유니티 내 안드로이드 Gradle 버전 확인
유니티 설치폴더/PlaybackEngines/AndroidPlayer/Tools/gradle/lib/gradle-cli-{VERSION}.jar -> 해당 버전이 유니티에서 사용하는 gradle 버전
gradle 버전별 안드로이드 플러그인 버전 사용 가이드 (https://developer.android.com/studio/releases/gradle-plugin 참고)
gradle 버전에 맞는 plugin 버전 사용
예) gradle 2.14 버전 사용 -> classpath 'com.android.tools.build:gradle:2.1.0 형태로 설정
...
.4.2. google-services.json 세팅
게임 설정에 맞는 google-services.json 파일을 다운로드 합니다. (1.2 Android SDK 설치 항목에서 Firebase 콘솔에서 파일 다운로드 받는 방법 참고)
해당 파일을 다운로드 받은 후에 Assets/Plugins/Android 폴더 아래에 위치시킵니다.
윈도우 환경에서 google-services 관련 오류가 있을 경우(SDK 3.15.0 이하)
https://github.com/firebase/firebase-cpp-sdk 에서 generate_xml_from_google_services_json.exe을 다운받거나 Assets/Firebase/Editor/generate_xml_from_google_services_json.exe 를 이용하여
google-services.xml 또는 google-services-desktop.json을 생성해줄 수 있습니다.
| 코드 블럭 |
|---|
"generate_xml_from_google_services_json.exe" -i "{원본 google-services.json 경로}" -o "{프로젝트 경로}/Assets/Plugins/Android/KakaoGameSDK.androidlib/res/values/google-services.xml" -p "{패키지 이름}" |
또는 파이썬 CLI를 설치후에 환경변수에 설정해서 파이썬을 실행할 수 있도록 설정하는 방법도 있습니다. (Download Link : https://www.python.org/downloads/ )
1.1.4.3. 커스텀 빌드 파일 세팅
Player → Publishing Settings → Build로 이동하여 커스텀 파일을 세팅합니다.
아래 커스텀 빌드 파일은 SDK에서 필수로 사용하는 항목입니다.
...
AndroidManifest.xml
SDK 내부 로직에 의해 자동으로 생성됩니다.
mainTemplate.gradle
반드시 체크가 필요하며 필요한 디펜던시스는 EDM에 의해 자동 세팅됩니다.
launcherTemplate.gradle
유니티와 EDM에 의해 자동 생성된 파일을 사용하시면 됩니다. SDK unitypackage에서 제공하는 파일을 그대로 사용해주셔도 상관없습니다.
baseProjectTemplate.gradle
| 코드 블럭 |
|---|
classpath 'com.google.gms:google-services:4.3.3' |
해당 구문을 추가해야합니다.
SDK unitypackage에서 제공하는 파일을 그대로 사용해주셔도 상관없습니다.
Unity 2022.2 이상을 사용할 경우
자동 생성된 파일에
| 코드 블럭 |
|---|
// Make sure that you have the Google services Gradle plugin dependency
id 'com.google.gms.google-services' version "4.3.15" apply false |
해당 구문을 추가해야합니다.
gradleTemplate.properties
유니티와 EDM에 의해 자동 생성된 파일을 사용하시면 됩니다. SDK unitypackage에서 제공하는 파일을 그대로 사용해주셔도 상관없습니다.
proguard-user.txt
SDK unitypackage에서 제공하는 파일을 사용해주시면 됩니다. 추가적으로 세팅하시는 것도 가능합니다.
SDK 3.15.0부터는 더이상 사용하지않아 제거해주셔도 상관없습니다.
1.1.4.4. gradle 버전 세팅
SDK 3.13.3 버전부터 빌드시 사용하는 gradle이 6.1.1를 사용하게 되면서 특정 유니티 버전 이하에서는 업그레이드가 필요합니다.
1.1.4.5. Http 사용 설정
targetSdkVersion을 28 버전 이상으로 설정하고 http 통신을 사용하는 게임은 아래와 같은 설정이 필요합니다.
카카오 게임 SDK 내부에서는 http를 사용하지 않습니다. 개발사에서 cdn등 이슈로 http 콜이 필요한 경우에만 설정합니다.
Kakao SDK v3.8.3 이상 버전 사용 필수
Unity Inspector 내에 Etc Setting(Use as needed) -> Domains to use HTTP(Android) 항목에 Add 버튼을 통해 게임에서 사용할 http domain을 추가
...
...
3.
...
10.0 이후 버전에서 다음카페뷰를 로드하는 API가 추가되었는데, 이 API를 사용하기 위해서 모든 HTTP Domain의 호출이 필요한데 아래와 같은 설정이 필요합니다.
Etc Setting -> HTTP Domain -> Use All HTTP Domain Check 설정
1.1.4.
...
그래서 배포시에 Assets/Plugins/Editor/generate_xml_from_google_services_json.py 파일을 제공하는데, 이 스크립트를 실행하기 위해서 파이썬 CLI가 설치되어 있어야합니다.
(Mac 환경에서는 기본적으로 python CLI가 포함되어 있어서 별도의 설정단계 필요 없음)
파이썬 CLI를 설치후에 환경변수에 설정해서 아무 path에서도 프로세스를 실행할 수 있도록 설정하는 단계가 필요합니다. (Download Link : https://www.python.org/downloads/ )
...
6. EDM 설정
EDM가 필요한 라이브러리를 다운로드 해주는 Resolver라는 기능을 제공해주는데, 이와 관련한 설정이 제대로 세팅되었는지 체크가 필요합니다.
먼저, Android Resolver Setting을 클릭합니다. (Menu -> Assets → External Dependency Manager → Android Resolver → Settings)
다음과 같이 세팅합니다.(필요에 따라 다르게 세팅하셔도 상관없습니다.)
1.1.4.7. Main Activity 변경하는 방법
SDK에서 자동으로 mainActivity를 KGUnityPlayerActivity로 변경해주고 있습니다.
메인 액티비티를 변경하기 위해서는 KGSharedData.json를 열어서 customManifest를 true로 세팅해주시면 됩니다.
1.1.5. iOS 설정
Unity3d툴에서 File -> Build Settings... 메뉴를 선택합니다.
...
아래와 같이 "Build Settings"창에서 Platfrom을 iOS로 설정하고, "Player Settings..."버튼을 클릭합니다.
...
카카오게임 SDK의 iOS 최소 지원 버전은
...
11.0입니다.
...
...
Build 버튼을 클릭하여 빌드합니다. 빌드가 성공하면, Xcode 프로젝트가 생성됩니다.
...
Xcode 프로젝트를 열고, "Capabilities" 탭의 "Keychain Sharing" 옵션을 ON으로 바꾸고 속성에 KakaoGameAccessGroup을 추가합니다.
...
...
1.1.5.1. EDM 설정
Android 처럼 EDM가 필요한 라이브러리를 다운로드 해주는 Resolver라는 기능을 제공해주는데, 이와 관련한 설정이 제대로 세팅되었는지 체크가 필요합니다.
먼저, iOS Resolver Setting을 클릭합니다. (Menu -> Assets -> External Dependency Manager -> iOS Resolver -> Settings)
다음과 같이 세팅합니다.(필요에 따라 다르게 세팅하셔도 상관없습니다.)
1.1.
...
6.
...
게임 내 지원 언어 리소스
라이브러리에서 게임 내 지원 언어 외 추가적인 언어 팩이 있을 때, 있거나 해당 언어를 제거하고 싶다면 아래 위치의 폴더를 제거 해주시면 폴더에서 세팅해주시면 됩니다.
iOS
...
iOS 프로젝트를 빌드하여 Xcode 프로젝트를 생성한후
Pods > KakaoGamePublishingSDK > KakaoGameFramework > KakaoGameResources.bundle 파일을 찾아서 '패키지 내용보기' 를 클릭한다.
...
제거 하고 싶은 언어의 폴더를 삭제한다.
...
주의) values폴더에는 영어 리소스가 포함된 xml 파일이 있는데, 언어 리소스 외에 다른 파일들은 삭제하지 않도록 주의한다.
...
Android
...
Unitypackage import한 폴더 기준으로 Assets > Kakaogame > AndroidPlugins > KakaoGameSDK.plugin 파일을 찾아서 '패키지 내용보기' 를 클릭한다.
...
제거하고 싶은 폴더의 xml 파일을 삭제한다. 예)일본어를 삭제하려면 res > values-ja 아래에 kakao_game_sdk_strings.xml / zinny_sdk_strings.xml 파일 두개를 삭제한다.
...
Android의 경우 aar에 포함되어 있어 수정이 불가능합니다.
1.1.
...
7. 유니티 에디터 로그인
1.1.
...
7.1.
...
카카오게임 SDK 3.4.0 버전부터 유니티 에디터 상에서 카카오 로그인 및 카카오 관련 기능을 사용할 수 있습니다.
...
카카오 개발자 사이트 세팅
웹 플랫폼 활성화
우선 카카오 개발자 사이트 내에서 카카오 게임 앱 정보에서 웹 플랫폼을 활성화
...
시킵니다. (처음에 앱등록을 한 상태에서 기본적으로 활성화 되지 않으므로 웹 플랫폼을 활성화 시켜야 함)
...
...
플랫폼 - Web- 사이트 도메인 추가
...
3.14.6 이상
카카오 에디터 로그인에 필요한 url이 https://dist-test-sdk.s3.amazonaws.com에서 https://kakao-sdk-release.s3.amazonaws.
...
그리고 2 단계에서 언급했던 JavaScript Key를 유니티 에디터 인스펙터 상에 Editor Setting > Use Kakao Editor Login 항목(3.4.0부터 추가됨)을 체크하고 InputField에 입력한다.
...
이렇게 하면 유니티 에디터 상에서 카카오 로그인을 사용할 준비는 다 되었다.
...
com로 변경되었습니다.
3.14.6 미만
카카오 디벨로퍼 사이트에서 https://kakao-sdk-release.s3.amazonaws.com를 등록하셔야합니다.
1.1.7.2. Unity SDK Configuration 세팅
...
Editor 로그인을 체크후 카카오 개발자 사이트에 있는 JavaScript 키를 등록 해줍니다.
...
1.1.7.3. 에디터 상에서의 카카오 로그인 사용
위와 같이 환경 설정 후에 유니티 에디터 상에서 카카오 로그인을 할 수 있습니다. 사용 방법은 아래 가이드를 참고하시면 됩니다.
로그인시에 Start 호출 → Login 호출 후에 지원하는 IDP 로그인 창 노출 확인 후 카카오 로그인 선택
...
카카오 인증 정보를 입력 받을 수 있는 UI가 노출됨과 동시에 PC / Mac에 설정된 default web browser로 카카오 로그인 페이지 노출
...
로그인 페이지에서 카카오 계정으로 로그인 버튼을 누르면 최초에 카카오 계정으로 로그인 팝업이 떠서 로그인이 가능하고 웹 페이지 캐싱에 의해 로그인 한 적이 있으면 바로 로그인 한 응답이 웹 페이지에 노출
...
웹페이지에 응답으로 노출된 정보를 모두 복사해서 유니티 에디터 상으로 다시 돌아와서 입력창에 입력 후에 OK 버튼
...
위와 같은 과정을 다 거치면 카카오 인증이 완료되고, 인증된 정보 에디터 환경(C# SDK)에서 해당 정보를 가지고 지니 플랫폼에 로그인해서 정상적으로 playerId와 zat발급 및 로그인 프로세스 완료.
1.1.
...
8. Unity SDK 사용시 주의사항
1.1.
...
8.1. PlayerPref class 사용시 참고
iOS / Android Native SDK에서 내부로직 상 저장이 필요한 값들을 해당 앱 데이터에 저장하는 로직 존재.
개발사에서 게임 데이터 정리를 위해 PlayerPref deleteAll 호출하는 경우 있음 -> 이 경우 SDK에서 필요로 인해 저장한 데이터 삭제되게 되어 SDK 오동작이 발생.
개발사에서 사용하는 key / value를 정리해서 개발사에서 deleteAll이 아닌 deleteKey API를 사용해서 게임에서 저장한 게임 데이터만 삭제하도록 구현해야 함.