이 문서는 Kakao SDK for Android(이하 Android SDK) 사용법을 설명합니다.
Android SDK를 사용하기 위한 최소 요구 사양은 다음과 같습니다.
Android SDK는 다음과 같은 외부 라이브러리를 사용합니다. Android SDK 설치 시, 해당 외부 라이브러리가 자동으로 설치됩니다.
프로젝트의 Gradle 설정을 통해 Android SDK를 간편하게 연동할 수 있습니다. Android Studio의 버전에 따라 다음의 해당하는 파일에 Maven 레파지토리(Repository)를 설정합니다.
프로젝트 레벨의 파일을 구분하는 방법은 다음 이미지를 참고합니다.
Android SDK를 적용할 프로젝트의 build.gradle(Project) 파일에 다음과 같이 Android SDK 레파지토리를 설정합니다.
// 최신 Android Studio에서는 allprojects 사용 불가능
allprojects {
repositories {
google()
jcenter()
maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/'}
}
}
Android SDK를 적용할 프로젝트의 settings.gradle(Project) 파일에 다음과 같이 Android SDK 레파지토리를 설정합니다.
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/' }
}
}
자세한 정보는 Dependency management in Gradle을 참고합니다.
Gradle 설정하기 완료 후, build.gradle(Module) 파일에 필요한 모듈을 설정합니다. 전체 모듈을 설치하거나 필요한 모듈만 선택해 설치할 수 있습니다.
dependencies {
implementation "com.kakao.sdk:v2-all:2.13.0" // 전체 모듈 설치, 2.11.0 버전부터 지원
implementation "com.kakao.sdk:v2-user:2.13.0" // 카카오 로그인
implementation "com.kakao.sdk:v2-talk:2.13.0" // 친구, 메시지(카카오톡)
implementation "com.kakao.sdk:v2-story:2.13.0" // 카카오스토리
implementation "com.kakao.sdk:v2-share:2.13.0" // 메시지(카카오톡 공유)
implementation "com.kakao.sdk:v2-navi:2.13.0" // 카카오내비
implementation "com.kakao.sdk:v2-friend:2.13.0" // 카카오톡 소셜 피커, 리소스 번들 파일 포함
}
dependencies {
implementation "com.kakao.sdk:v2-all-rx:2.13.0" // 전체 모듈 설치, 2.11.0 버전부터 지원
implementation "com.kakao.sdk:v2-user-rx:2.13.0" // 카카오 로그인
implementation "com.kakao.sdk:v2-talk-rx:2.13.0" // 친구, 메시지(카카오톡)
implementation "com.kakao.sdk:v2-story-rx:2.13.0" // 카카오스토리
implementation "com.kakao.sdk:v2-share-rx:2.13.0" // 메시지(카카오톡 공유)
implementation "com.kakao.sdk:v2-navi:2.13.0" // 카카오내비
implementation "com.kakao.sdk:v2-friend-rx:2.13.0" // 카카오톡 소셜 피커, 리소스 번들 파일 포함
}
카카오톡 공유 모듈명이 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
Kakao SDK의 일부 모듈은 다른 모듈에 의존성이 있으며, 각 모듈은 설치 시 의존하는 모듈을 자동으로 함께 설치합니다. 모듈간 의존성 구조는 아래 이미지를 참고합니다.
[내 애플리케이션] > [플랫폼]에서 Android 플랫폼 정보를 입력합니다. 이 설정은 Android SDK를 통해 카카오 API를 사용하려면 필수입니다. 자세한 안내는 플랫폼 등록을 참고합니다.
카카오 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(Module) 파일에 자바 버전을 설정합니다. 자세한 내용은 Android 개발자 사이트 공식 가이드를 참고합니다.
// Java 8 사용을 위한 build.gradle 설정
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.**
키 해시(Key Hash)란 인증서(Certificate)의 인증서 지문 값(Certificate fingerprints)을 해시(hash)한 값으로, 악성 앱인지 판별하는 데 사용됩니다. 카카오 API를 호출하면 카카오 API 서버가 요청 헤더에 추가된 키 해시값과 카카오 플랫폼에 등록한 값이 일치하는지 확인합니다. 키 해시는 디버그 키 해시(Debug key hash)와 릴리즈 키 해시(Release key hash) 두 가지가 있습니다.
다음 중 원하는 방법을 선택하여 디버그 키 해시와 릴리즈 키 해시 값을 구합니다.
터미널에서 키 해시를 생성하려면 키 해시를 관리하는 키툴(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
Kakao 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로 인코딩하여 사용해야 합니다. 자세한 내용은 Play Console 고객센터 > 앱 서명 사용하기를 참고합니다.
keytool -printcert -file ./deployment_cert.der
${PRINTCERT}
부분에 실제 SHA-1 인증서 지문 값을 입력해야 합니다.echo "${PRINTCERT}" | xxd -r -p | openssl base64
생성한 디버그, 릴리즈 키 해시 값들을 개발자 웹사이트의 [내 애플리케이션] > [플랫폼] > [Android]에 모두 등록합니다. 자세한 안내는 플랫폼 등록을 참고합니다.
- 모든 개발 환경의 디버그 키 해시들과 릴리즈 키 해시를 등록해야 합니다. 키 해시가 등록되지 않은 앱에서는 카카오 API를 호출할 수 없습니다. - 만약 여러 명의 개발자가 앱의 개발에 참여하고 있다면 각 개발자들의 개발 환경에 따라 디버그 키스토어(keystore)가 각자 다르므로 각 디버그 키 해시를 모두 등록해야 합니다.
설치 및 설정 후 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"
...
>
다음은 Android SDK v1(2.0.0 미만 버전)에서 Android SDK v2로 업그레이드하는 사용자를 위한 참고 정보입니다.
Android SDK v2는 Android SDK v1에 비해 간결한 모듈 구조를 갖고 있습니다. Android SDK v2는 카카오 로그인과 공통 및 유틸리티 성격의 기능들을 common
모듈 하나에 모아 제공합니다. 또한 제품 단위로 구성된 모듈별 API는 Client
, 객체 및 구조체 정보는 Model
패키지에 모여 있어 보다 효율적이고 편리하게 사용할 수 있습니다.
최신 버전 SDK 사용 시, 카카오 로그인을 통해 발급받은 액세스 토큰을 전달해야 하는 API를 사용하려면 common
모듈에서 제공하는 카카오 로그인 기능을 함께 구현해야 합니다. common
모듈은 기본 모듈이므로, 모듈 설정 시 설정한 모듈들과 함께 기본적으로 설치됩니다.
KakaoSDK
를 통해 초기화 함수 호출com.kakao.util
패키지의 Utility
를 통해 키 해시 구하기 함수 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
초기화 | init() | init() |
키 해시 구하기 | getKeyHash() | getKeyHash() |
LoginActivity
를 통해 호출AuthService
를 통해 호출Session
을 통해 호출UserManagement
를 통해 호출v2-user
모듈의 UserApiClient
를 통해 호출AuthApiClient
를 통해 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
카카오톡으로 로그인 | - | loginWithKakaoTalk(context) |
카카오계정으로 로그인 | - | loginWithKakaoAccount(context) |
로그아웃 | requestLogout() | logout() |
연결 끊기 | requestUnlink() | unlink() |
사용자 정보 가져오기 | me() | me() |
사용자 정보 저장하기 | requestUpdateProfile(properties) | updateProfile() |
추가 항목 동의 받기 | updateScopes(scopes) | loginWithNewScopes(context, scopes) |
카카오톡 실행 가능 여부 확인하기 | - | isKakaoTalkLoginAvailable() |
토큰 정보 보기 | requestAccessTokenInfo() | accessTokenInfo() |
토큰 존재 여부 확인하기 | isOpened() | hasToken() |
KakaoTalkService
를 통해 API 호출v2-talk
모듈의 TalkApiClient
를 통해 API 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
카카오톡 프로필 가져오기 | requestProfile() | profile() |
카카오톡 친구 목록 가져오기 | requestAppFriends() | friends() |
KakaoLinkService
를 통해 API 호출v2-share
모듈의 ShareClient
를 통해 API 호출context
전달 필요Name | Android SDK v1 | Android SDK v2 |
---|---|---|
카카오톡 앱을 통한 공유 가능 여부 확인하기 | - | isKakaoTalkSharingAvailable() |
기본 메시지 보내기 | sendDefault(template) | shareDefault(context, defaultTemplate) |
스크랩 메시지 보내기 | sendScrapWithURL(url) | shareScrap(context, url) |
사용자 정의 메시지 보내기 | sendCustomWithTemplateId(templateId) | shareCustom(context, templateId) |
이미지 업로드하기 | uploadImage(imageFile) | uploadImage(file) |
이미지 스크랩하기 | scrapImage(imageUrl) | scrapImage(url) |
KakaoTalkService
를 통해 API 호출v2-talk
모듈의 TalkApiClient
를 통해 API 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
나에게 기본 메시지 보내기 | requestSendMemo(template) | sendDefaultMemo(template) |
나에게 스크랩 메시지 보내기 | requestSendMemo(url) | sendScrapMemo(url) |
나에게 사용자 정의 메시지 보내기 | requestSendMemo() | sendCustomMemo(templateId) |
친구에게 기본 메시지 보내기 | sendMessageToFriends(template, uuids) | sendDefaultMessage(template, receiverUuids) |
친구에게 스크랩 메시지 보내기 | sendMessageToFriend(url, uuids) | sendScrapMessage(url, receiverUuids) |
친구에게 사용자 정의 메시지 보내기 | sendMessageToFriends(templateId, uuids) | sendCustomMessage(templateId, receiverUuids) |
KakaoStoryService
를 통해 API 호출v2-story
모듈의 StoryApiClient
를 통해 API 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
사용자 확인하기 | requestIsStoryUser() | isStoryUser() |
프로필 가져오기 | requestProfile() | profile() |
스토리 쓰기 | requestPostNote(content) | postNote(content) |
사진 스토리 쓰기 | requestPostPhoto(content, fileList) | postPhoto(content, images) |
링크 스토리 쓰기 | requestPostLink(content, linkUrl) | postLink(content, linkInfo) |
내 스토리 가져오기 > 하나의 스토리 가져오기 | requestGetMyStory(id) | story(id) |
내 스토리 가져오기 > 여러 개의 스토리 가져오기 | requestGetMyStories() | stories() |
내 스토리 삭제하기 | requestDeleteMyStory(id) | delete(id) |
이미지 업로드하기 | - | upload(images) |
웹 페이지 스크랩하기 | - | linkInfo(url) |
PlusFriendService
를 통해 호출KakaoTalkService
를 통해 호출v2-talk
모듈의 TalkApiClient
를 통해 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
카카오톡 채널 추가하기 | addFriend(plusFriendId) | addChannelUrl(channelPublicId) |
카카오톡 채널 채팅 | chat(plusFriendId) | channelChatUrl(channelPublicId) |
채널 관계 확인하기 | requestPlusFriends() | channels() |
UserManagement
를 통해 호출LoginActivity
를 통해 호출v2-user
모듈의 UserApiClient
를 통해 API 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
배송지 가져오기 | shippingAddresses() | shippingAddresses() |
동의한 약관 확인하기 | serviceTerms() | serviceTerms() |
약관 선택해 동의 받기 | - | loginWithKakaoTalk(context, serviceTerms) loginWithKakaoAccount(context, serviceTerms) |
KakaoNaviService
를 통해 API 호출newBuilder()
와 setNaviOptions()
메소드 사용v2-navi
모듈의 NaviClient
를 통해 API 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
길 안내 | navigate(destination) | navigateIntent(location, naviOption) |
목적지 공유하기 | shareDestination(destination) | shareDestinationIntent(location, naviOption) |
길 안내 조건 설정하기 | newBuilder() setNaviOptions(options) |
NaviOption() |
목적지 정보 설정하기 | newBuilder() setNaviOptions(options) |
Location() |
* navigateWebUrl(location, naviOption): Deprecated, 웹 길 안내 서비스 종료, 공지 참고
PushService
를 통해 API 호출Name | Android SDK v1 | Android SDK v2 |
---|---|---|
푸시 토큰 등록하기 | registerPushToken(pushToken, deviceId) | - |
푸시 토큰 보기 | getPushTokens() | - |
푸시 토큰 삭제하기 | deregisterPushToken(deviceId) | - |
기존 버전인 Legacy Android SDK(Android SDK v1) 사용 방법은 다음 링크를 통해 확인할 수 있습니다. 추후 Legacy Android SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 Android SDK로 변경할 것을 권장합니다.