이 문서는 카카오디벨로퍼스에서 제공하는 Android SDK(Kakao SDK for Android) 사용 방법을 안내합니다.

• Android Studio 3.6.1 이상
• API 23: Android 6.0(Marshmallow) 이상

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

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

앱 관리 페이지의 [앱] > [플랫폼 키] > [네이티브 앱 키]에서 Android 앱 정보를 입력합니다. 자세한 안내는 네이티브 앱 키를 참고합니다.

키 해시(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 <RELEASE_KEY_ALIAS> -keystore <RELEASE_KEY_PATH> | openssl sha1 -binary | 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

카카오디벨로퍼스는 Android SDK의 주요 기능을 빠르게 확인할 수 있는 샘플 앱을 제공합니다. 샘플 앱으로 카카오 로그인, 카카오톡 공유 등 SDK 기능을 직접 테스트하고, 구현 예제 코드를 확인할 수 있습니다.

Android SDK 샘플 앱을 실행하는 방법에 대해 안내합니다.

1. 다운로드에서 Android SDK 샘플 앱을 다운로드 받습니다.
2. 키 해시를 참고해 샘플 앱 프로젝트의 디버그 키 해시를 생성합니다.
3. 계정 설정 페이지의 [Android SDK 샘플 앱]에 생성한 키 해시를 등록합니다.
   • 등록한 샘플 앱의 키 해시는 샘플 앱 요청의 유효성 검증에 사용됩니다.
   • 샘플 앱의 키 해시가 누락되거나 잘못 등록된 경우, KOE009 또는 401 에러가 발생합니다.
4. 샘플 앱을 실행해 Android SDK의 주요 기능을 테스트하고, 구현 에제 코드를 확인할 수 있습니다.

카카오 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"
    ...

인터넷 사용 설정 권한 화면

앱 배포 시, 코드 축소, 난독화, 최적화를 하는 경우, 카카오 SDK를 제외하기 위하여 프로가드(ProGuard) 규칙 파일에 아래 코드를 추가합니다.

-keep class com.kakao.sdk.**.model.* { <fields>; }

# https://github.com/square/okhttp/pull/6792
-dontwarn org.bouncycastle.jsse.**
-dontwarn org.conscrypt.*
-dontwarn org.openjsse.**

# refrofit2 (with r8 full mode)
-if interface * { @retrofit2.http.* <methods>; }
-keep,allowobfuscation interface <1>
-keep,allowobfuscation,allowshrinking class kotlin.coroutines.Continuation
-if interface * { @retrofit2.http.* public *** *(...); }
-keep,allowoptimization,allowshrinking,allowobfuscation class <3>
-keep,allowobfuscation,allowshrinking class retrofit2.Response

프로젝트의 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 파일에 필요한 모듈을 추가합니다. 전체 모듈 또는 필요한 모듈만 추가할 수 있습니다.

dependencies {
  implementation("com.kakao.sdk:v2-all:${LATEST_VERSION}") // 전체 모듈 추가, 2.11.0 버전부터 지원
  implementation("com.kakao.sdk:v2-user:${LATEST_VERSION}") // 카카오 로그인 API 모듈
  implementation("com.kakao.sdk:v2-share:${LATEST_VERSION}") // 카카오톡 공유 API 모듈
  implementation("com.kakao.sdk:v2-talk:${LATEST_VERSION}") // 카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 모듈
  implementation("com.kakao.sdk:v2-friend:${LATEST_VERSION}") // 피커 API 모듈
  implementation("com.kakao.sdk:v2-navi:${LATEST_VERSION}") // 카카오내비 API 모듈
  implementation("com.kakao.sdk:v2-cert:${LATEST_VERSION}") // 카카오톡 인증 서비스 API 모듈
}

Android SDK를 사용하려면 설치 후 init() 메서드에 카카오디벨로퍼스 앱의 네이티브 앱 키를 포함해 초기화해야 합니다. 네이티브 앱 키는 앱 관리 페이지의 [앱] > [플랫폼 키] > [네이티브 앱 키]에서 확인할 수 있습니다.

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가 제공하는 모듈과 주요 기능은 아래와 같습니다.

Android SDK의 일부 모듈은 다른 모듈에 의존성이 있으며, 각 모듈은 설치 시 의존하는 모듈을 자동으로 함께 설치합니다. 모듈간 의존성 구조는 아래 이미지를 참고합니다.

모듈간 의존성 구조도