kakao developers

Android

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

요구 사양

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

• Android Studio 3.6.1 이상
• API 21: Android 5.0(Lollipop) 이상

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

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

• Android SDK: Gson, Retrofit, OkHttp
• ReactiveX Android SDK: RxJava3, Gson, Retrofit, OkHttp

설치

Gradle 설정

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

• build.gradle: Android Studio Artic Fox(최신) 외 버전
• settings.gradle: Android Studio Artic Fox(최신) 버전

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

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

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" // 카카오톡 소셜 피커, 리소스 번들 파일 포함
}

참고: 모듈간 의존성

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"
    }
}

프로가드 설정(선택)

앱 배포 시, 코드 축소, 난독화, 최적화를 하는 경우, 카카오 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을 다운로드해야 합니다.

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

디버그 키 해시

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

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 

2. 1번 단계에서 얻은 SHA-1 인증서 지문 값을 터미널에 다음과 같이 입력합니다. ${PRINTCERT} 부분에 실제 SHA-1 인증서 지문 값을 입력해야 합니다.

echo "${PRINTCERT}" | xxd -r -p | openssl base64 

생성한 디버그, 릴리즈 키 해시 값들을 개발자 웹사이트의 [내 애플리케이션] > [플랫폼] > [Android]에 모두 등록합니다. 자세한 안내는 플랫폼 등록을 참고합니다.

초기화

설치 및 설정 후 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"
    ...
>

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 비교

공통

• Android SDK v1
  • AndroidManifest.xml에 네이티브 앱 키 설정
  • KakaoSDK를 통해 초기화 함수 호출
  • com.kakao.util 패키지의 Utility를 통해 키 해시 구하기 함수 호출
• 최신 버전
  • KakaoSdk를 통해 네이티브 앱 키를 전달하여 초기화 함수 호출
  • Utility를 통해 키 해시 구하기 함수 호출

카카오 로그인

• Android SDK v1
  • 카카오 로그인 API는 LoginActivity를 통해 호출
  • 토큰 정보 보기 API는 AuthService를 통해 호출
  • 추가 항목 동의 받기 API는 Session을 통해 호출
  • 로그아웃, 연결 끊기, 사용자 정보 가져오기, 사용자 정보 저장하기 API는 UserManagement를 통해 호출
• 최신 버전
  • 카카오 로그인 API는 v2-user 모듈의 UserApiClient를 통해 호출
  • 토큰 존재 여부 확인하기 API는 AuthApiClient를 통해 호출

카카오톡 소셜

• Android SDK v1: KakaoTalkService를 통해 API 호출
• 최신 버전: v2-talk 모듈의 TalkApiClient를 통해 API 호출

메시지: 카카오톡 공유

• Android SDK v1
  • KakaoLinkService를 통해 API 호출
  • 사용자 기기에 카카오톡 미설치 시 내부적으로 웹뷰를 통해 메시지 전달됨
• 최신 버전
  • v2-share 모듈의 ShareClient를 통해 API 호출
  • 메시지 보내기 API는 context 전달 필요
  • 사용자 기기에 카카오톡 미설치 시 웹뷰 또는 기본 브라우저를 통해 공유되도록 구현 필요

메시지: 카카오톡

• Android SDK v1: KakaoTalkService를 통해 API 호출
• 최신 버전: v2-talk 모듈의 TalkApiClient를 통해 API 호출

카카오스토리

• Android SDK v1: KakaoStoryService를 통해 API 호출
• 최신 버전: v2-story 모듈의 StoryApiClient를 통해 API 호출

카카오톡 채널

• Android SDK v1
  • 카카오톡 채널 추가하기, 카카오톡 채널 채팅 API는 PlusFriendService를 통해 호출
  • 채널 관계 확인하기 API는 KakaoTalkService를 통해 호출
• 최신 버전
  • 카카오톡 채널 추가하기, 카카오톡 채널 채팅 API는 v2-talk 모듈의 TalkApiClient를 통해 호출
  • 채널 관계 확인하기 API는 카카오 로그인 구현 필요

카카오싱크

• Android SDK v1
  • 배송지 가져오기, 동의한 약관 확인하기 API는 UserManagement를 통해 호출
  • 약관 선택해 동의 받기 API는 LoginActivity를 통해 호출
• 최신 버전: 배송지 가져오기, 동의한 약관 확인하기, 약관 선택해 동의 받기 API 모두 v2-user 모듈의 UserApiClient를 통해 API 호출

카카오내비

• Android SDK v1
  • KakaoNaviService를 통해 API 호출
  • 파라미터 설정은 각 클래스 newBuilder()와 setNaviOptions() 메소드 사용
• 최신 버전
  • v2-navi 모듈의 NaviClient를 통해 API 호출
  • 파라미터 설정은 각 클래스 생성자 사용

* navigateWebUrl(location, naviOption): Deprecated, 웹 길 안내 서비스 종료, 공지 참고

푸시 알림

• Android SDK v1: PushService를 통해 API 호출
• 최신 버전: 푸시 알림 API 미지원, REST API 사용 가능

Legacy

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

Legacy Android

더 보기

Android SDK 다운로드Android SDK 레퍼런스outlink