시작하기

이 문서는 카카오 API 플랫폼에서 제공하는 Android SDK(Kakao SDK for Android) 사용 방법을 안내합니다.

모듈 정보

Android SDK가 제공하는 모듈과 주요 기능은 아래와 같습니다.

모듈간 의존성

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

준비

요구 사양

• 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)한 값
• 릴리즈 키 해시: 앱 스토어에 앱을 배포하기 위해 생성한 릴리즈 인증서로부터 해시한 값

아래의 방법으로 디버그, 릴리즈 키 해시 값 확인 후, [내 애플리케이션] > [플랫폼] > [Android]에 모두 등록합니다. 자세한 안내는 플랫폼 등록을 참고합니다.

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

터미널에서 키 해시를 생성하려면 키 해시를 관리하는 키툴(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로 디버그, 릴리즈 키 해시 확인

Android 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로 인코딩하여 사용해야 합니다. 자세한 내용은 앱 서명 사용하기를 참고합니다.

[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"
    ...

선택: 프로가드 규칙

앱 배포 시, 코드 축소, 난독화, 최적화를 하는 경우, 카카오 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 설정

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

settings.gradle.kts

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:${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 모듈
}

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