Getting Started

We provide API based on Kakao Platform services such as Kakao Talk, Kakao Story and more. Kakao SDK is needed in order for developers to use such tools easily and correctly.

This document is not only for showing instructions on how to use Kakao SDK but also on development environment for using Kakao Platform service.

We recommend that you read this thoroughly before you refer to the guide or test functionalities.

These are the functionalities which this guide will cover on.

  • User management: Provides simple login through kakao account. Also provides tools to easily manage each users information. Details on essential information on dealing with login through Kakao platform.
  • Kakao Link: Send variety of messages through KakaoTalk App.
  • Kakao Talk: Provide direct use of API in apps provided by KakaoTalk.
  • Kakao Navi: Provide navigation through Kakao Navi right from your application.
  • Kakao Story: Provide direct use of API in apps provided by KakaoStory.
  • Push Alert: Explain basics on how to use push alert
  • Applog Analytics: Functionality for analyzing start/end, user session, and particular events of an app.

Following document is based on following environment. Configuration will be somewhat different, based on system environment of developers.

  • Apple OS X system 10.8.5
  • Eclipse in ADT Bundle
  • Java 1.7.0_25
  • Android 4.4.2 (API 19)

In order to test and launch sample, version 4.2.0 or above of KakaoTalk must be installed. Included sample only works in Android SDK version 2.3.3(API level 10) or above.

Environment structure

One way of using Kakao SDK is by importing library that is extracted from maven/gradle. Another way would be to import SDK source manually.

Using library

if you use maven/gradle, you don't need to download the source. You can also download module from remote repository instead of installing module in local. Lastly, you can reduce the size of an app by using only essential library. This can be done easily by settings pom.xml as below.

For gradle configuration please refer Kakao SDK Gradle Samples.

1. maven repository

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

2. Setting essential modules as below. If module have been included, check if it's the latest. It is recommended to update with latest version in case if it's out of date.

    <dependency>
        <groupId>android</groupId>
        <artifactId>android</artifactId>
        <version>5.0_r1</version>
    </dependency>
    <dependency>
        <groupId>com.google.android</groupId>
        <artifactId>support-v4</artifactId>
        <version>r19</version>
    </dependency>

3. For functionalities you wish to use, add module needed.

Enter the sdk version in ${kakaosdk.version}. Supports maven version 1.0.33 and gradle version 1.0.36.

    <!-- User management module -->
    <dependency>
        <groupId>com.kakao.sdk</groupId>
        <artifactId>usermgmt</artifactId>
        <version>${kakaosdk.version}</version>
        <type>aar</type>
    </dependency>
    <!-- KakaoStory module(must be include User management module, because that is based on login) -->
    <dependency>
        <groupId>com.kakao.sdk</groupId>
        <artifactId>kakaostory</artifactId>
        <version>${kakaosdk.version}</version>
        <type>aar</type>
    </dependency>
    <!-- KakaoStory module(must be include User management module, because that is based on login) -->
    <dependency>
        <groupId>com.kakao.sdk</groupId>
        <artifactId>kakaotalk</artifactId>
        <version>${kakaosdk.version}</version>
        <type>aar</type>
    </dependency>
    <!-- KakaoLink module-->
    <dependency>
        <groupId>com.kakao.sdk</groupId>
        <artifactId>kakaolink</artifactId>
        <version>${kakaosdk.version}</version>
        <type>aar</type>
    </dependency>
    <!-- Push alarm module(if you want to use push alarm like sample App based on login, must be include User management module) -->
    <dependency>
        <groupId>com.kakao.sdk</groupId>
        <artifactId>push</artifactId>
        <version>${kakaosdk.version}</version>
        <type>aar</type>
    </dependency>
    <!-- App log Analytics -->
    <dependency>
        <groupId>com.kakao.sdk.analytics</groupId>
        <artifactId>kakao-android-sdk-analytics</artifactId>
        <version>${analyticssdk.version}</version>
        <type>jar</type>
    </dependency>

4. Import android maven plugin

     <plugin>
         <groupId>com.jayway.maven.plugins.android.generation2</groupId>
         <artifactId>android-maven-plugin</artifactId>
         <version>3.9.0-rc.2</version>
         <extensions>true</extensions>
     </plugin>
Using SDK source

1. Download ADT Bundle and unzip these files. For detail about installing ADT, please refer here

2. Download Latest Kakao SDK for Android and unzip these files. Sdk, samples, templates, docs folders and project files will be unzipped

  • sdk folder: include SDK source.
  • samples folder: Example code for showing how API works.
  • templates folder: Template source code for creating project when creating new app.

3. Import Kakao SDK.

  • Launch Eclipse in ADT, then select 'File > Import' menu.
  • In Select window, select 'Android', 'Existing Android Code into Workspace' options, followed by next button.
  • Select unzipped Kakao SDK folder by clicking 'Browse' button. If each project appears in import-list, in a state in which the project is selected, click the 'Finish' button

4. In order to use Push API, import google-play-services_lib additionally.

  • Launch Eclipse in ADT, then download 'Extras > Google Play service' by using SDK Manager. 001.png
  • Import $ANDROID_HOME/extras/google/google_play_services/libproject/google-play-services_lib as described above.
  • An error can occur, due to difference in path of google-play-services_lib included in Kakao SDK. If an error occurs, follow the solutions mentioned below.
  • Select Properties(command + I) by using right-click menu of sdk project.
  • In Library section, located at right corner of Android category, delete google-play-services_lib, and add google-play-services_lib newly.

Confirm if Workspace File encoding is UTF-8.

  • OS X and Linux : "ADT > Preferences > General > Workspace > Text file encoding > Select 'Others: UTF-8'"
  • Windows : "Window > Preferences > General > Workspace > Text file encoding > Select 'Others: UTF-8'"

Launch sample app

Samples are included in Kakao SDK.

  • usermgmt-sample: These are samples related to user management.
  • kakaostory-sample: THis is sample app related to KakaoStory API.
  • kakaotalk-sample: This is sample app for KakaoTalk API.
  • kakaolink-sample: This is a sample app related to KakaoLink.
  • push-sample: This is a sample app related to Push.

1. In order to launch sample App based on login, you will register sample App key-hash.

Since kakaolink sample does not require login, you can skip registering key hash if you only wish to launch kakao link sample.

  • Each Android app that has been developed by developers must register key hash.
    • For details regarding registering Key-hash in developed Android App, refer Create App.
  • In case of sample App, you only need to register key hash once for convenience.
    • Sample App allows login from only developer's account that registered Key-hash.
  • Sample App Key-hash is default hash value regarding binary certification saved in your own Android development environment *if you install Android SDK, certification for development will be saved in debug.keystore file as alias of androiddebugkey. Check for certification as below.

    keytool -exportcert -alias androiddebugkey -keystore <debug_keystore_path> -storepass android -keypass android
    • Following is a value of result ran in build machine of sample for key hash, which must be registered in keystore.
      keytool -exportcert -alias androiddebugkey -keystore <debug_keystore_path> -storepass android -keypass android | openssl sha1 -binary | openssl base64
  • <debug_keystore_path>
    • OS X and Linux : Confirm key in this path, Eclipse "ADT > Preferences > Android > Build > Default debug keystore".
      • e.g. : ~/.android/debug.keystore
    • Windows : Confirm key in this path, Eclipse "Window > Preferences > Android > Build > Default debug keystore".
      • e.g.(Windows Vista, Windows 7) : C:\Users\<user>\.android\debug.keystore
      • e.g.(Windows XP) : C:\Documents and Settings\<user>\.android\debug.keystore
  • keytool : Exist in this path, $JAVA_HOME/bin.
  • openssl : Install openssl, In case of Windows.
  • Get hash value as following and register in My account > Setting sample App.
  • When building sample App in multiple machines, you can register multiple Key-hash. dev_001.png

2. Select kakaolink-sample module in Kakao SDK project and select Run to install app on device.

  • When you press send button to configure messages you want to send, a confirmation window will appear.
  • When you press confirmation button, Kakaotalk App is launched. When you select friends who will receive messages, messages is sent as following. a_004.png

Create app

2 types of template app is included in Kakao SDK.

  • loginbase-template: This is a template app for guiding app with login. This is a Library Module which used by sample apps included in SDK.
  • loginfree-template: login-free-Template App which helps to create App without login. (e.g. KakaoLink dose not require login)

1. Create app through My application > Create app

  • if you specify name of an App and click Make, app will be created and app key will be issued. dev_004.png
  • When using Android SDK, you should use Native App key. click Setting and move on to the next step.
  • Select Add platform > Android and enter the package name.
    • If you enter package name, google play market URL will be filled automatically. Using other markets beside google market, you can manually edit URL. dev_013.png

2. Register Key-hash for each App, when you are using login based API calls.

  • In case of creating an App,

    When developing an app, sign in through debug key issued per machine, and when releasing app, use release key to sign in which means all of key hash should be registered for each key.

  • For debug key hash, implement it in a way in which is identical to sample app key hash setting, and for release key hash*, implement in a way identical to below.

    • For detail about signing app, please refer here.
      keytool -exportcert -alias <release_key_alias> -keystore <release_keystore_path> | openssl sha1 -binary | openssl base64
  • Key hash obtained from above instruction should be registered as instructed below.

dev_014.png

3. In case of using proguard, you should set options below.

-keep class com.kakao.** { *; }
-keepattributes Signature
-keepclassmembers class * {
  public static <fields>;
  public *;
}
-dontwarn android.support.v4.**,com.ning.http.client.**,org.jboss.netty.**, org.slf4j.**, com.fasterxml.jackson.databind.**, com.google.android.gms.**

loginbase template

Create App with login, simply through SampleLoginActivity and SampleSignupActivity offered by SDK. Apply setting to App, refer template-setting example blow. By following example template setting , apply setting to an app you are about to create.

Sample App(usermgmt-sample, kakaostory-sample, kakaotalk-sample, push-sample) is made by using login-base-template.

[kakao_strings.xml]

Naming App key that is issued when creating App as kakao_app_key. Register App key in AndroidManifest.xml. Define appkey issued when creating an app with the name kakao_app_key, and register it in AndroidManifest.xml.

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

App key can be checked in Setting > General > App key > Native app key menu, which is located in dev-site dashboard.

[AndroidManifest.xml]

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

<application>
    <activity
        ...
        android:name=".SampleLoginActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
    ...
    <!-- 2 -->
    <meta-data
        android:name="com.kakao.sdk.AppKey"
        android:value="@string/kakao_app_key" />
</application>


  1. For communicating with server, set network permissions.
  2. Register App-key with the name, com.kakao.sdk.AppKey .

loginfree template

Setting for App without login is simple. By following template settings below, try to set app's setting as instructed.

Sample App(kakaolink-sample) was made using login-free-template

[kakao_strings.xml]

Name App key that is issued when creating App as kakao_app_key. Register App key in AndroidManifest.xml.

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

App key can be confirm in Setting > General > App key > Native app key menu in dev-site dashboard.

[AndroidManifest.xml]

<application>
    <activity android:name=".LoginFreeTemplateActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
    <!-- 1 -->
    <meta-data
        android:name="com.kakao.sdk.AppKey"
        android:value="@string/kakao_app_key" />
</application>

Register App-key with the name com.kakao.sdk.AppKey .

Copy template

Determine if app with login or app with only kakao link is needed. After what is needed has been decided, copy the template required and create app directory.


troubleshoot

If you have trouble following getting started guide, or have problem launching sample app, refer to Sample App troubleshooting.


Last Modified : 2017-07-28