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

Android

시작하기

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

모듈 정보

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

Kotlin
RxKotlin
모듈 클라이언트 설명
v2-common - 필수 요소를 담은 공통 모듈

주요 기능: 초기화
v2-auth AuthApiClient 카카오 로그인 인증 및 토큰 관리 모듈

주요 기능: 토큰 존재 여부 확인하기 API
v2-user UserApiClient 카카오 로그인 API 모듈

주요 기능: 카카오 로그인 API, 사용자 정보 가져오기 API
v2-share ShareClient 카카오톡 공유 API 모듈

주요 기능: 사용자 정의 템플릿으로 메시지 보내기 API
v2-talk TalkApiClient 카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 모듈

주요 기능: 카카오톡 채널 간편 추가하기 API
v2-template - 메시지 템플릿 모듈
v2-friend PickerClient 피커 API 모듈

주요 기능: 피커: 친구 선택하기 API
v2-navi NaviClient 카카오내비 API 모듈
v2-cert CertApiClient 카카오톡 인증 서비스 API 모듈
모듈 클라이언트 설명
v2-common-rx - 필수 요소를 담은 공통 모듈

주요 기능: 초기화
v2-auth-rx AuthApiClient 카카오 로그인 인증 및 토큰 관리 모듈

주요 기능: 토큰 존재 여부 확인하기 API
v2-user-rx UserApiClient 카카오 로그인 API 모듈

주요 기능: 카카오 로그인 API, 사용자 정보 가져오기 API
v2-share-rx ShareClient 카카오톡 공유 API 모듈
v2-talk-rx TalkApiClient 카카오톡 채널, 카카오톡 소셜, 카카오톡 메시지 API 모듈

주요 기능: 카카오톡 채널 간편 추가하기 API
v2-friend-rx PickerClient 피커 API 모듈

주요 기능: 피커: 친구 선택하기 API
주의: 카카오톡 공유 모듈명 변경

카카오톡 공유 모듈명이 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

모듈간 의존성

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

모듈간 의존성 구조도

준비

요구 사양

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

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

플랫폼

[내 애플리케이션] > [플랫폼]에서 Android 앱 정보를 입력합니다. 자세한 안내는 플랫폼 등록을 참고합니다.

키 해시

키 해시(Key Hash)란 인증서(Certificate)의 인증서 지문 값(Certificate fingerprints)을 해시(hash)한 값으로, 악성 앱인지 판별하는 데 사용됩니다. 카카오 API를 호출하면 카카오 API 서버가 요청 헤더에 추가된 키 해시값과 카카오 플랫폼에 등록한 값이 일치하는지 확인합니다. 키 해시는 디버그 키 해시(Debug key hash)와 릴리즈 키 해시(Release key hash) 두 가지가 있습니다.

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

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

주의: 키 해시 등록

모든 개발 환경의 디버그 키 해시들과 릴리즈 키 해시를 등록해야 합니다. 키 해시가 등록되지 않은 앱에서는 카카오 API를 호출할 수 없습니다. 여러 명의 개발자가 앱의 개발에 참여하고 있다면 각 개발자들의 개발 환경에 따라 디버그 키스토어(keystore)가 각자 다르므로 각 디버그 키 해시를 모두 등록해야 합니다.

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

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

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"
    ...
인터넷 사용 설정 권한 화면

Java 8 사용

또한 Java 8 사용을 위해 아래 설정을 build.gradle.kts(Module) 파일에 추가합니다. 자세한 내용은 Android 개발자 사이트 공식 가이드를 참고합니다.

// Java 8 사용을 위한 build.gradle.kts 설정
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.**

설치

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) 파일에 필요한 모듈을 설정합니다.

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