페이지 이동경로
  • 문서>
  • 시작하기>
  • Android

시작하기

Android

이 문서는 Kakao SDK for Android(이하 Android SDK) 사용법을 설명합니다.

요구 사양

Android SDK를 사용하기 위한 최소 요구 사양은 다음과 같습니다.

참고: 외부 라이브러리 의존성

Android SDK는 다음과 같은 외부 라이브러리를 사용합니다. Android SDK 설치 시, 해당 외부 라이브러리가 자동으로 설치됩니다.

설치

Gradle 설정

프로젝트의 Gradle 설정을 통해 Android SDK를 간편하게 연동할 수 있습니다. Android Studio의 버전에 따라 다음의 해당하는 파일에 Maven 레파지토리(Repository)를 설정합니다.

프로젝트 레벨의 파일을 구분하는 방법은 다음 이미지를 참고합니다.

build.gradle 참고 화면
build.gradle

Android SDK를 적용할 프로젝트의 build.gradle(Project) 파일에 다음과 같이 Android SDK 레파지토리를 설정합니다.

// 최신 Android Studio에서는 allprojects 사용 불가능
allprojects {    
    repositories {        
        google()        
        jcenter()        
        maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/'}    
    }
}
settings.gradle

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) 파일에 필요한 모듈을 설정합니다. 전체 모듈을 설치하거나 필요한 모듈만 선택해 설치할 수 있습니다.

Kotlin
RxKotlin
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 사용 설정

또한 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"
    }
}
JAVA 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) 두 가지가 있습니다.

  • 디버그 키 해시: 프로젝트를 처음 생성하거나 디버그할 때, 안드로이드 스튜디오에서 개발 환경에 맞게 자동으로 생성되는 디버그 인증서에서 해시(hash)한 값입니다.
  • 릴리즈 키 해시: 앱 스토어에 앱을 배포하기 위해 생성한 릴리즈 인증서로부터 해시한 값입니다.

다음 중 원하는 방법을 선택하여 디버그 키 해시와 릴리즈 키 해시 값을 구합니다.

터미널에서 디버그, 릴리즈 키 해시 생성

터미널에서 키 해시를 생성하려면 키 해시를 관리하는 키툴(keytool)이 필요합니다. Windows의 경우, Windows 라이브러리를 위한 OpenSSL을 다운로드해야 합니다.

사용 중인 운영체제에 따라 다음 명령어를 입력합니다.

디버그 키 해시
Mac
Windows
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
릴리즈 키 해시
Mac
Windows
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로 디버그, 릴리즈 키 해시 확인

Kakao SDK를 통해서도 키 해시 확인이 가능합니다. Utility에서 제공하는 편의 기능 중 getKeyHash() 함수를 사용하여 키 해시 값을 문자열(String)로 구할 수 있습니다.

import com.kakao.sdk.common.util.Utility

var keyHash = Utility.getKeyHash(this)

Google Play Console 앱 서명으로 릴리즈 키 해시 확인

Google Play 앱 서명(App Signing)을 사용한다면 직접 릴리즈 키 해시를 생성하지 않고, Google Play Console에서 얻은 SHA-1 인증서 지문(SHA-1 certificate fingerprint)을 Base64로 인코딩하여 사용해야 합니다. 자세한 내용은 Play Console 고객센터 > 앱 서명 사용하기를 참고합니다.

  1. [Google Play Console] > [설정] > [앱 무결성] 메뉴의 [앱 서명키 인증서] 항목에서 [SHA-1 인증서 지문] 값을 복사합니다.
    만약 Google Play Console에 접근 권한이 없고 인증서 파일(deployment_cert.der)만 가지고 있다면 터미널에 다음과 같이 입력합니다.
keytool -printcert -file ./deployment_cert.der 
  1. 1번 단계에서 얻은 SHA-1 인증서 지문 값을 터미널에 다음과 같이 입력합니다. ${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.xmlapplication에도 Kakao SDK 초기화를 수행한 클래스의 이름을 설정해야 합니다. 위 예제에서는 GlobalApplication 클래스에서 초기화를 했으므로 아래와 같이 동일한 이름을 설정에 추가합니다.

<application
    <!-- android:name 설정 -->
    android:name=".GlobalApplication"
    ...
>

v1에서 v2로 마이그레이션

다음은 Android SDK v1(2.0.0 미만 버전)에서 Android SDK v2로 업그레이드하는 사용자를 위한 참고 정보입니다.

모듈 구조

Android SDK v2는 Android SDK v1에 비해 간결한 모듈 구조를 갖고 있습니다. Android SDK v2는 카카오 로그인과 공통 및 유틸리티 성격의 기능들을 common 모듈 하나에 모아 제공합니다. 또한 제품 단위로 구성된 모듈별 API는 Client, 객체 및 구조체 정보는 Model 패키지에 모여 있어 보다 효율적이고 편리하게 사용할 수 있습니다.

카카오 로그인이 필요한 API 사용 시 주의사항

최신 버전 SDK 사용 시, 카카오 로그인을 통해 발급받은 액세스 토큰을 전달해야 하는 API를 사용하려면 common 모듈에서 제공하는 카카오 로그인 기능을 함께 구현해야 합니다. common 모듈은 기본 모듈이므로, 모듈 설정 시 설정한 모듈들과 함께 기본적으로 설치됩니다.

버전별 API 비교

공통
Name Android SDK v1 Android SDK v2
초기화 init() init()
키 해시 구하기 getKeyHash() getKeyHash()
카카오 로그인
  • Android SDK v1
    • 카카오 로그인 API는 LoginActivity를 통해 호출
    • 토큰 정보 보기 API는 AuthService를 통해 호출
    • 추가 항목 동의 받기 API는 Session을 통해 호출
    • 로그아웃, 연결 끊기, 사용자 정보 가져오기, 사용자 정보 저장하기 API는 UserManagement를 통해 호출
  • 최신 버전
    • 카카오 로그인 API는 v2-user 모듈의 UserApiClient를 통해 호출
    • 토큰 존재 여부 확인하기 API는 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()
카카오톡 소셜
Name Android SDK v1 Android SDK v2
카카오톡 프로필 가져오기 requestProfile() profile()
카카오톡 친구 목록 가져오기 requestAppFriends() friends()
메시지: 카카오톡 공유
  • Android SDK v1
    • KakaoLinkService를 통해 API 호출
    • 사용자 기기에 카카오톡 미설치 시 내부적으로 웹뷰를 통해 메시지 전달됨
  • 최신 버전
    • v2-share 모듈의 ShareClient를 통해 API 호출
    • 메시지 보내기 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)
메시지: 카카오톡
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)
카카오스토리
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)
카카오톡 채널
  • Android SDK v1
    • 카카오톡 채널 추가하기, 카카오톡 채널 채팅 API는 PlusFriendService를 통해 호출
    • 채널 관계 확인하기 API는 KakaoTalkService를 통해 호출
  • 최신 버전
    • 카카오톡 채널 추가하기, 카카오톡 채널 채팅 API는 v2-talk 모듈의 TalkApiClient를 통해 호출
    • 채널 관계 확인하기 API는 카카오 로그인 구현 필요
Name Android SDK v1 Android SDK v2
카카오톡 채널 추가하기 addFriend(plusFriendId) addChannelUrl(channelPublicId)
카카오톡 채널 채팅 chat(plusFriendId) channelChatUrl(channelPublicId)
채널 관계 확인하기 requestPlusFriends() channels()
카카오싱크
Name Android SDK v1 Android SDK v2
배송지 가져오기 shippingAddresses() shippingAddresses()
동의한 약관 확인하기 serviceTerms() serviceTerms()
약관 선택해 동의 받기 - loginWithKakaoTalk(context, serviceTerms)
loginWithKakaoAccount(context, serviceTerms)
카카오내비
  • Android SDK v1
    • 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, 웹 길 안내 서비스 종료, 공지 참고

푸시 알림
  • Android SDK v1: PushService를 통해 API 호출
  • 최신 버전: 푸시 알림 API 미지원, REST API 사용 가능
Name Android SDK v1 Android SDK v2
푸시 토큰 등록하기 registerPushToken(pushToken, deviceId) -
푸시 토큰 보기 getPushTokens() -
푸시 토큰 삭제하기 deregisterPushToken(deviceId) -

Legacy

기존 버전인 Legacy Android SDK(Android SDK v1) 사용 방법은 다음 링크를 통해 확인할 수 있습니다. 추후 Legacy Android SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 Android SDK로 변경할 것을 권장합니다.

더 보기