이 문서는 카카오 API 플랫폼에서 제공하는 Kakao SDK for Android(이하 Android SDK) 사용 방법을 안내합니다.
Android SDK가 제공하는 모듈과 주요 기능은 아래와 같습니다.
모듈 | 클라이언트 | 설명 |
---|---|---|
v2-common |
- | 필수 요소를 담은 공통 모듈 주요 기능: 초기화 |
v2-auth |
AuthApiClient |
카카오 로그인 인증 및 토큰 관리 모듈 주요 기능: 토큰 존재 여부 확인하기 API |
v2-user |
UserApiClient |
카카오 로그인 API 모듈 주요 기능: 카카오 로그인 API, 사용자 정보 가져오기 API |
v2-share |
ShareClient |
카카오톡 공유 API 모듈 주요 기능: 사용자 정의 템플릿으로 메시지 보내기 API |
v2-talk |
TalkApiClient |
카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 모듈 주요 기능: 카카오톡 채널 간편 추가하기 API |
v2-template |
- | 메시지 템플릿 모듈 |
v2-friend |
PickerClient |
피커 API 모듈 주요 기능: 피커: 친구 선택하기 API |
v2-navi |
NaviClient |
카카오내비 API 모듈 |
v2-cert |
CertApiClient |
카카오톡 인증 서비스 API 모듈 |
모듈 | 클라이언트 | 설명 |
---|---|---|
v2-common-rx |
- | 필수 요소를 담은 공통 모듈 주요 기능: 초기화 |
v2-auth-rx |
AuthApiClient |
카카오 로그인 인증 및 토큰 관리 모듈 주요 기능: 토큰 존재 여부 확인하기 API |
v2-user-rx |
UserApiClient |
카카오 로그인 API 모듈 주요 기능: 카카오 로그인 API, 사용자 정보 가져오기 API |
v2-share-rx |
ShareClient |
카카오톡 공유 API 모듈 |
v2-talk-rx |
TalkApiClient |
카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 모듈 주요 기능: 카카오톡 채널 간편 추가하기 API |
v2-friend-rx |
PickerClient |
피커 API 모듈 주요 기능: 피커: 친구 선택하기 API |
카카오톡 공유 모듈명이 2.11.0 버전부터 변경되었습니다. 아래 내용과 공지사항을 참고합니다. - 2.11.0 미만 버전: com.kakao.sdk:v2-link, com.kakao.sdk:v2-link-rx - 2.11.0 이상 버전: com.kakao.sdk:v2-share, com.kakao.sdk:v2-share-rx
Android SDK의 일부 모듈은 다른 모듈에 의존성이 있으며, 각 모듈은 설치 시 의존하는 모듈을 자동으로 함께 설치합니다. 모듈간 의존성 구조는 아래 이미지를 참고합니다.
Android SDK는 아래와 같은 외부 라이브러리를 사용합니다. Android SDK 설치 시, 해당 외부 라이브러리가 자동으로 설치됩니다.
[내 애플리케이션] > [플랫폼]에서 Android 앱 정보를 입력합니다. 자세한 안내는 플랫폼 등록을 참고합니다.
키 해시(Key Hash)란 인증서(Certificate)의 인증서 지문 값(Certificate fingerprints)을 해시(hash)한 값으로, 악성 앱인지 판별하는 데 사용됩니다. 카카오 API를 호출하면 카카오 API 서버가 요청 헤더에 추가된 키 해시값과 카카오 플랫폼에 등록한 값이 일치하는지 확인합니다. 키 해시는 디버그 키 해시(Debug key hash)와 릴리즈 키 해시(Release key hash) 두 가지가 있습니다.
아래의 방법으로 디버그, 릴리즈 키 해시 값 확인 후, [내 애플리케이션] > [플랫폼] > [Android]에 모두 등록합니다. 자세한 안내는 플랫폼 등록을 참고합니다.
모든 개발 환경의 디버그 키 해시들과 릴리즈 키 해시를 등록해야 합니다. 키 해시가 등록되지 않은 앱에서는 카카오 API를 호출할 수 없습니다. 여러 명의 개발자가 앱의 개발에 참여하고 있다면 각 개발자들의 개발 환경에 따라 디버그 키스토어(keystore)가 각자 다르므로 각 디버그 키 해시를 모두 등록해야 합니다.
터미널에서 키 해시를 생성하려면 키 해시를 관리하는 키툴(keytool)이 필요합니다. Windows의 경우, Windows 라이브러리를 위한 OpenSSL을 다운로드해야 합니다.
사용 중인 운영체제에 따라 아래 명령어를 입력합니다.
keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64
keytool -exportcert -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64
keytool -exportcert -alias <RELEASE_KEY_ALIAS> -keystore <RELEASE_KEY_PATH> | openssl sha1 -binary | openssl base64
keytool -exportcert -alias <RELEASE_KEY_ALIAS> -keystore <RELEASE_KEY_PATH> | openssl sha1 -binary | PATH_TO_OPENSSL_LIBRARY\bin\openssl base64
Android SDK의 Utility
에서 제공하는 편의 기능 중 getKeyHash()
함수를 사용하여 키 해시 값을 문자열(String)로 구할 수 있습니다.
import com.kakao.sdk.common.util.Utility
var keyHash = Utility.getKeyHash(this)
Google Play 앱 서명(App Signing)을 사용한다면 직접 릴리즈 키 해시를 생성하지 않고, Google Play Console에서 얻은 SHA-1 인증서 지문(SHA-1 certificate fingerprint)을 Base64로 인코딩하여 사용해야 합니다. 자세한 내용은 앱 서명 사용하기를 참고합니다.
[Google Play Console] > [설정] > [앱 무결성] 메뉴의 [앱 서명키 인증서] 항목에서 [SHA-1 인증서 지문] 값을 복사합니다.
만약 Google Play Console에 접근 권한이 없고 인증서 파일(deployment_cert.der)만 가지고 있다면 터미널에 다음과 같이 입력합니다.
keytool -printcert -file ./deployment_cert.der
SHA-1 인증서 지문 값을 터미널에 다음과 같이 입력합니다.
echo "${PRINTCERT}" | xxd -r -p | openssl base64
카카오 API를 통해 카카오 서버와 통신하기 위해 앱에 인터넷 사용 권한을 설정해야 합니다. AndroidManifest.xml에 다음과 같이 인터넷 사용 권한을 설정합니다. 이 설정은 카카오 API를 통한 HTTP 요청이 올바르게 완료되도록 해 줍니다.
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.sample">
<!-- 인터넷 사용 권한 설정-->
<uses-permission android:name="android.permission.INTERNET" />
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
...
또한 Java 8 사용을 위해 아래 설정을 build.gradle.kts(Module) 파일에 추가합니다. 자세한 내용은 Android 개발자 사이트 공식 가이드를 참고합니다.
// Java 8 사용을 위한 build.gradle.kts 설정
android {
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
kotlinOptions {
jvmTarget = "1.8"
}
}
앱 배포 시, 코드 축소, 난독화, 최적화를 하는 경우, 카카오 SDK를 제외하기 위하여 프로가드(ProGuard) 규칙 파일에 다음 코드를 추가합니다.
-keep class com.kakao.sdk.**.model.* { <fields>; }
-keep class * extends com.google.gson.TypeAdapter
# https://github.com/square/okhttp/pull/6792
-dontwarn org.bouncycastle.jsse.**
-dontwarn org.conscrypt.*
-dontwarn org.openjsse.**
프로젝트의 Gradle 설정을 통해 Android SDK를 간편하게 연동할 수 있습니다. Android Studio의 버전에 따라 다음의 해당하는 파일에 Maven 레파지토리(Repository)를 설정합니다. Dependency management in Gradle을 참고합니다.
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url = java.net.URI("https://devrepo.kakao.com/nexus/content/groups/public/") }
}
}
build.gradle.kts(Module) 파일에 필요한 모듈을 설정합니다.
dependencies {
implementation "com.kakao.sdk:v2-all:2.20.6" // 전체 모듈 설치, 2.11.0 버전부터 지원
implementation "com.kakao.sdk:v2-user:2.20.6" // 카카오 로그인 API 모듈
implementation "com.kakao.sdk:v2-share:2.20.6" // 카카오톡 공유 API 모듈
implementation "com.kakao.sdk:v2-talk:2.20.6" // 카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 모듈
implementation "com.kakao.sdk:v2-friend:2.20.6" // 피커 API 모듈
implementation "com.kakao.sdk:v2-navi:2.20.6" // 카카오내비 API 모듈
implementation "com.kakao.sdk:v2-cert:2.20.6" // 카카오톡 인증 서비스 API 모듈
}
dependencies {
implementation "com.kakao.sdk:v2-all-rx:2.20.6" // 전체 모듈 설치, 2.11.0 버전부터 지원
implementation "com.kakao.sdk:v2-user-rx:2.20.6" // 카카오 로그인 API 모듈
implementation "com.kakao.sdk:v2-share-rx:2.20.6" // 카카오톡 공유 API 모듈
implementation "com.kakao.sdk:v2-talk-rx:2.20.6" // 카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 모듈
implementation "com.kakao.sdk:v2-friend-rx:2.20.6" // 피커 API 모듈
implementation "com.kakao.sdk:v2-navi:2.20.6" // 카카오내비 API 모듈
implementation "com.kakao.sdk:v2-cert:2.20.6" // 카카오톡 인증 서비스 API 모듈
}
설치 및 설정 후 Android SDK를 사용하기 위해서는 가장 먼저 네이티브 앱 키로 초기화를 해야 합니다. Application
을 상속한 클래스를 사용하고 있다면 다음과 같이 초기화할 수 있습니다.
class GlobalApplication : Application() {
override fun onCreate() {
super.onCreate()
// 다른 초기화 코드들
// Kakao SDK 초기화
KakaoSdk.init(this, "{NATIVE_APP_KEY}")
}
}
AndroidManifest.xml의 application
에도 Kakao SDK 초기화를 수행한 클래스의 이름을 설정해야 합니다. 위 예제에서는 GlobalApplication
클래스에서 초기화를 했으므로 아래와 같이 동일한 이름을 설정에 추가합니다.
<application
<!-- android:name 설정 -->
android:name=".GlobalApplication"
...
>