시작하기

카카오 플랫폼 서비스는 카카오톡, 카카오스토리와 같은 카카오 서비스 및 카카오 플랫폼 기술과 관련된 API를 제공합니다. 해당 기능을 쉽게, 올바르게 사용하기 위해서는 카카오에서 제공하는 Kakao SDK가 필요합니다.

본 문서는 카카오 플랫폼 서비스를 사용하기 위한 기본 개발환경 구성 및 Kakao SDK 사용법뿐만 아니라, 카카오 플랫폼 서비스가 제공하는 각각의 기능별 상세 설명을 포함합니다.

앞으로 제공될 상세기능에 대한 설명을 참고하거나 해당 기능을 실행해 보기전에, 반드시 아래의 기본 과정을 숙지하기를 권장합니다.

본 문서에서 제공되는 상세기능은 다음과 같습니다.

  • 사용자 관리
    카카오계정을 통한 간편 로그인을 제공합니다. 이외에도 사용자들의 개별 정보를 손쉽게 관리해주는 기능을 포함합니다. 카카오 플랫폼 서비스에서 제공하는 기능 중 로그인이 필요한 기능을 사용하기 위해서는 반드시 선행되어야 할 내용들을 다룹니다.
  • 카카오링크
    카카오톡 앱을 이용하여 다양한 메시지를 보낼 수 있습니다.
  • 카카오톡
    카카오톡에서 제공하는 API를 앱에서 직접 사용할 수 있습니다.
  • 카카오내비
    카카오내비에서 제공하는 API를 앱에서 직접 호출할 수 있습니다.
  • 카카오스토리
    카카오스토리에서 제공하는 API를 앱에서 직접 사용할 수 있습니다.
  • 푸시 알림
    카카오계정에서 로그인한 앱에서 푸시 알림을 사용하기 위한 과정에 대해 설명합니다.
  • 앱로그 분석
    앱의 시작/종료, 사용자의 세션, 특정 이벤트 등 앱의 활동성 등을 분석할 수 있는 기능입니다.

아래 문서는 다음의 환경을 기준으로 작성되었으며, 개발자의 시스템 환경에 따라 구성이 조금씩 다를 수 있습니다.

  • Apple OS X system 10.13
  • Android Studio 3.0
  • Embedded JDK in Android Studio 3.0
  • Gradle 4.1
  • Android Gradle Plugin 3.0
  • Android 7.1 (API 25)

올바른 테스트 및 샘플 실행을 위해서는 Android SDK 버젼 4.0 (API level 14), 카카오톡 버젼 4.2.0 이상이 요구됩니다.

개발환경 구성

카카오 SDK를 사용하는 방법

Gradle 환경에서 사용하기

Gradle을 이용하면 소스를 받을 필요 없고, 로컬에 인스톨해줘야 하는 모듈도 리모트에서 받아올 수 있으며, 필요한 기능 라이브러리만 사용하여 앱파일 크기를 줄일 수 있습니다.

1. Gradle repository

subprojects {
    repositories {
        mavenCentral()
        maven { url 'http://devrepo.kakao.com:8088/nexus/content/groups/public/' }
    }
}

2. 사용할 앱의 build.gradle 파일에 아래와 같이 필요한 모듈을 선택적으로 설정합니다.

project.KAKAO_SDK_VERSION 에는 sdk 버전을 명시합니다. gradle 지원은 1.0.36부터 지원되지만 최신 패키지 구조가 변경된 1.1.0버전 이상의 gradle project를 사용하시길 권장합니다.

dependencies {
    // 카카오 로그인 sdk를 사용하기 위해 필요.
    compile group: 'com.kakao.sdk', name: 'usermgmt', version: project.KAKAO_SDK_VERSION

    // 카카오링크 sdk를 사용하기 위해 필요.
    compile group: 'com.kakao.sdk', name: 'kakaolink', version: project.KAKAO_SDK_VERSION

    // 카카오톡 sdk를 사용하기 위해 필요.
    compile group: 'com.kakao.sdk', name: 'kakaotalk', version: project.KAKAO_SDK_VERSION

    // 카카오내비 sdk를 사용하기 위해 필요.
    compile group: 'com.kakao.sdk', name: 'kakaonavi', version: project.KAKAO_SDK_VERSION

    // 카카오스토리 sdk를 사용하기 위해 필요.
    compile group: 'com.kakao.sdk', name: 'kakaostory', version: project.KAKAO_SDK_VERSION

    // push sdk를 사용하기 위해 필요.
    compile group: 'com.kakao.sdk', name: 'push', version: project.KAKAO_SDK_VERSION
}

3. SDK 소스보기

Android용 최신 Kakao SDK에 포함된 kakao-open-android-sdk-sample 참조.

Maven 환경에서 사용하기

Maven 환경은 기본적으로 gradle 환경과 비슷합니다. Gradle의 빌드 파일 대신 앱의 pom.xml에 아래 처럼 repository를 추가해주고 dependency들을 설정해주면 됩니다.

1. Maven repository

<repositories>
    <repository>
        <id>kakaodev-public</id>
        <url>http://devrepo.kakao.com:8088/nexus/content/groups/public/</url>
    </repository>
</repositories>

**2.** 사용하고 싶은 기능에 해당하는 모듈을 추가로 설정 합니다.
> ${kakaosdk.version} 에는 sdk 버전을 명시합니다. maven 지원은 1.0.33부터 지원됩니다. 다양한 모듈들 추가하는 법은 위의 <a href="#gradle-환경설정">Gradle 환경설정</a>을 참고하세요.

```xml
<!-- 사용자 관리 모듈 -->
<dependency>
    ...
    <groupId>com.kakao.sdk</groupId>
    <artifactId>usermgmt</artifactId>
    <version>${kakaosdk.version}</version>
    <type>aar</type>
    ...
</dependency>

Eclipse 환경에서 사용하기

SDK 소스를 통한 Eclipse 개발 환경은 더 이상 공식적으로 지원하지 않습니다. Eclipse에서 사용하려면 Maven이나 Gradle 프로젝트를 사용하셔야 합니다.

Full Source 환경설정

Kakao SDK는 gradle을 기반으로 작성이 되었으며, Android Studio IDE에서 최적화된 환경을 제공합니다. Android용 최신 Kakao SDK를 다운로드하여 압축을 풉니다.

1. Kakao SDK를 Import 합니다. Import Project를 하여 다운로드 받은 Full Source를 추가합니다.

Workspace File encoding이 UTF-8로 되어 있는지 확인합니다.

2. local.properties 설정 local.properties 내부에 sdk.dir에 local에 설정된 Android SDK의 경로를 맞춰줍니다.

앱 생성

1. 내 애플리케이션 > 앱 만들기를 통해 앱을 생성합니다.

  • 앱 이름을 지정하고 만들기를 클릭하면 앱 생성이 완료되고 앱 키가 할당됩니다. dev_0017.png
  • Android SDK를 사용할 때에는 네이티브 앱 키를 사용합니다. 설정을 클릭하여 설정을 이어 갑니다.
  • 플랫폼 추가 > Android 선택후 패키지명을 입력합니다. 기본적으로 패키지명을 입력하면 구글 플레이 마켓 URL이 채워집니다. 구글 플레이 외의 마켓을 이용할 경우라면 직접 수정할 수 있습니다. dev_018.png

2. 프로가드 적용시에는 아래 옵션을 설정에 추가합니다.

-keep class com.kakao.** { *; }
-keepattributes Signature
-keepclassmembers class * {
  public static <fields>;
  public *;
}
-dontwarn android.support.v4.**,org.slf4j.**,com.google.android.gms.**

Kakao SDK에포함된 kakao-open-android-sdk-sample에서 제공되는 SampleLoginActivity, SampleSignupActivity을 통해 로그인 기반 앱을 가볍게 만들어 볼 수 있습니다. 아래의 설정 예제를 참고하여, 생성하고자 하는 앱에 설정을 적용합니다.

3. 다음과 같이 앱 설정을 합니다. [kakao_strings.xml]

앱생성시 발급된 네이티브 앱키를 kakao_app_key이란 이름으로 정의하고, AndroidManifest.xml에서 앱키를 등록합니다.

<resources>
    <string name="kakao_app_key">AAAAAAAAAAAAAAAAAAAAAA</string>
</resources>

앱키 값은 개발자 웹사이트에서 제공하는 대쉬보드의 설정 > 일반 > 앱 키 > 네이티브 앱 키 메뉴를 통해 확인 가능합니다.

[AndroidManifest.xml]

1. 서버와의 통신을 위해 network 권한을 설정합니다.

2. com.kakao.sdk.AppKey 이름으로 앱키를 등록합니다.

<!-- 1 -->
<uses-permission android:name="android.permission.INTERNET" />

<application>
    <!-- 2 -->
    <activity
        ...
        android:name=".SampleLoginActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
    <!-- 3 -->
    <meta-data
        android:name="com.kakao.sdk.AppKey"
        android:value="@string/kakao_app_key" />
    <!-- 4 -->
    <activity
        android:name="com.kakao.auth.authorization.authcode.KakaoWebViewActivity"
        android:launchMode="singleTop"
        android:windowSoftInputMode="adjustResize">

        <intent-filter>
            <action android:name="android.intent.action.MAIN"/>
            <category android:name="android.intent.category.DEFAULT"/>
        </intent-filter>
    </activity>
    ...
</application>

키해시 등록

카카오 API 콜을 수행하려면 앱별 키 해시를 등록해야 합니다. 카카오 API는 앱에서 추출한 키해시를 통하여 악의적인 앱인지 아닌지를 판별합니다. 키해시는 앱의 사이닝 키 시그너쳐를 해시한 값이기 때문에 앱의 사이닝 키 별로 모두 등록해줘야 합니다.

사인(sign)과정에 대한 자세한 설명은 여기를 참고하세요.

보통의 안드로이드 개발 환경에서 등록해야하는 키 해시에는 디버그 키해시릴리즈 키해시가 있습니다.

디버그 키해시

Android Studio로 앱을 디버그 빌드하게 되면 기본적으로 Android SDK 설치시 생성되는 개발용 디버그 키스토어를 사용하여 앱을 사인하게 됩니다. 등록해야할 디버그 키해시는 개발 머신의 터미널에서 아래와 같이 수행한 값입니다.

Commandline으로 키해시 구하기
keytool -exportcert -alias androiddebugkey -keystore <debug_keystore_path> -storepass android -keypass android | openssl sha1 -binary | openssl base64
  • <debug_keystore_path>
    • OS X와 리눅스 : ~/.android/debug.keystore
    • Windows Vista와 Windows 7 예: C:\Users\<user>\.android\debug.keystore
    • Windows XP 예 : C:\Documents and Settings\<user>\.android\debug.keystore
  • keytool : $JAVA_HOME/bin 아래에 존재합니다.
  • openssl : Windows의 경우는 다운받아 설치합니다.
앱 내 자바 코드로 키해시 구하기
public static String getKeyHash(final Context context) {
    PackageInfo packageInfo = getPackageInfo(context, PackageManager.GET_SIGNATURES);
    if (packageInfo == null)
        return null;

    for (Signature signature : packageInfo.signatures) {
        try {
            MessageDigest md = MessageDigest.getInstance("SHA");
            md.update(signature.toByteArray());
            return Base64.encodeToString(md.digest(), Base64.NO_WRAP);
        } catch (NoSuchAlgorithmException e) {
            Log.w(TAG, "Unable to get MessageDigest. signature=" + signature, e);
        }
    }
    return null;
}

만약 여러 명의 개발자가 앱의 개발에 참여하고 있다면 각 개발자들의 개발 환경의 디버그 키스토어가 다를 것이므로 여러개의 키해시를 모두 등록하셔야 개발에 지장이 없습니다.

릴리즈 키해시

앱 배포를 위하여 릴리즈 빌드로 APK를 생성할 경우에는 디버그 키스토어가 아닌 .jks 확장자를 가진 릴리즈용 키스토어로 사인을 하게 됩니다. 이 릴리즈용 키스토어도 동일한 절차를 거쳐 키해시를 구할 수 있습니다.

keytool -exportcert -alias <release_key_alias> -keystore <release_keystore_path> | openssl sha1 -binary | openssl base64

이 릴리즈 키해시도 등록을 해주셔야 릴리즈 빌드로 생성한 APK와 마켓에서 유저들이 설치한 APK에서 카카오 API가 정상동작합니다. 만약 위의 절차들을 정상적으로 거치지 않았다면 아래와 같은 에러를 받게 됩니다.

{"msg":"appkey does not match to registered app info (ios bundle id, android key hash, web domain url).","code":-401}

만약 구글 플레이 개발자 콘솔에서 Google play app signing 기능을 활성화시키셨다면 구글 플레이에 앱이 릴리즈되기 전에 개발자의 로컬 개발 환경에서 릴리즈 키스토어의 시그너쳐가 삭제되고 구글 서버에 저장되어 있는 사이닝키의 시그너쳐로 교체됩니다. 그렇기 때문에 이 사이닝키로 생성한 키해시 또한 등록해줘야 합니다.

위와 같은 방법으로 구한 키 해시를 아래와 같이 등록 하도록 합니다. dev_019_android2.png

샘플앱 실행

1. SDK내부의 Sample앱을 실행하기 위한 가이드입니다. 샘플앱을 실행하기 위해서는 샘플앱 키해시 를 등록 해야합니다.

  • 키해시를 확인하는 법은 키해시 등록을 참고하세요.
  • 키해시 값을 얻어 내 계정 > 샘플앱 설정에 등록합니다.
  • 여러 머신에서 샘플앱을 빌드하는 경우는 여러개의 키 해시를 등록해야 합니다. dev_001.png
  • 샘플앱의 경우, 편의를 위해 개발자 계정에 하나의 키해시를 등록하면 됩니다.
    • 샘플앱은 키해시를 등록한 개발자 계정으로만 로그인이 허용됩니다.

문제해결

시작하기를 진행하면서 어려움이 있거나, 샘플앱 등이 잘 실행되지 않는다면 샘플앱 문제해결을 참고해 보세요.



Last Modified : 2017-11-06