페이지 이동경로
  • Docs>
  • Getting Started>
  • Android

Getting Started

Android

This document describes what you should do to integrate the Kakao SDK for Android (hereinafter referred to as 'Android SDK') into your web before leveraging the Kakao APIs.

IMPORTANT

To use Android SDK, you must register the Android platform in advance. Go to [My Application] > [Platform] and register the Android platform by specifying its package name and key hashes.

Features

The Android SDK has the following features:

  • Uses Kotlin.
  • Has intuitive interface similar to the usability of REST API.
  • Adopts networking and JSON libraries such as Gson to maximize performance.
  • Provides ReactvieX Extension that makes your code reactive and helps you to program more effectively when you use RxJava or RxKotlin.
  • Adopts a default browser (AuthenticationSession) instead of WebView to enhance security.

Requirements

Here are what you need to use the Android SDK:

  • Android Studio 3.6.1 or higher
  • API 21: Android 5.0 (Lollipop) or higher
External library dependency

The Android SDK uses the following libraries that are automatically installed when installing the Android SDK:

Install and configure SDK

You can install the Android SDK in your project. To do so,

  1. Set Gradle.
  2. Add modules.
  3. Grant Internet permission.

Set Gradle

You need to set Gradle by declaring a Maven repository to sync your project with the Android SDK. Depending on the version of Android Studio, how you declare repositories is different.

If you use Android Studio Arctic Fox, declare the Maven repository in dependencyResolutionManagement in the project-level settings.gradle file. For more information, refer to Centralizing repositories declaration.

//If you use Android Studio Arctic Fox, add this block in settings.gradle.
dependencyResolutionManagement {    
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)    
        repositories {        
            google()        
            mavenCentral()        
            maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/' }    
    }
}
Screenshot of setting gradles in Android Studio

If you use an earlier version of Android Studio Arctic Fox, declare the Maven repository in allprojects in the project-level build.gradle file.

// NOTE: You cannot declare repositories through 'allprojects' in Android Studio Arctic Fox.
allprojects {    
    repositories {        
        google()        
        jcenter()        
        maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/'}    
    }
}
Screenshot of setting Maven repository in Android Studio

Add modules

To use the Kakao APIs, add the desired modules to the module-level build.gradle file according to the APIs you want to use.

Screenshot of adding modules in Android Studio
Kotlin
RxKotlin
dependencies {
  implementation "com.kakao.sdk:v2-all:2.11.2" // Add all modules (Available in 2.11.0 or higher)

  implementation "com.kakao.sdk:v2-user:2.11.2" // Kakao Login
  implementation "com.kakao.sdk:v2-talk:2.11.2" // Kakao Talk Social, Kakao Talk messaging
  implementation "com.kakao.sdk:v2-friend:2.11.2" // Friend picker
  implementation "com.kakao.sdk:v2-story:2.11.2" // Kakao Story
  implementation "com.kakao.sdk:v2-share:2.11.2" // Kakao Talk sharing
  implementation "com.kakao.sdk:v2-navi:2.11.2" // Kakao Navi 
}
dependencies {
  implementation "com.kakao.sdk:v2-all-rx:2.11.2" // Add all modules (Available in 2.11.0 or higher)

  implementation "com.kakao.sdk:v2-user-rx:2.11.2" // Kakao Login
  implementation "com.kakao.sdk:v2-talk-rx:2.11.2" // Kakao Talk Social, Kakao Talk messaging
  implementation "com.kakao.sdk:v2-friend-rx:2.11.2" // Friend picker
  implementation "com.kakao.sdk:v2-story-rx:2.11.2" // Kakao Story
  implementation "com.kakao.sdk:v2-share-rx:2.11.2" // Kakao Talk sharing
  implementation "com.kakao.sdk:v2-navi:2.11.2" // Kakao Navi 
}
Module dependency

Some modules in the Kakao SDK are dependent on another module. If you add the Common or Auth module, its subordinate modules are automatically added together.

Kakao SDK module dependency tree

Grant Internet permission

To communicate with the Kakao Sever through the Kakao APIs, allow the internet permission.

Screenshot of allowing internet permission in Android Studio
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.sample">
 
    <!-- Allow Internet permission -->
    <uses-permission android:name="android.permission.INTERNET" />

    <application
    android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
    ...


Enable Java 8 features

To use the Java 8 features, the following code snippet must be included in your project. If not, add the following to the module-level build.gradle file. For more details, refer to the official site for Android app developers.

Screenshot of setting Java version in Android Studio
// Use Java 8 features

android {

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    // For Kotlin projects
    kotlinOptions {
        jvmTarget = "1.8"
    }
}


Optional: Configure for shrinking and obfuscation

If you enable shrinking, obfuscation, and optimization when buiding the release version of your app, add the following -keep lines in the ProGuard rules file to exclude the Kakao SDK from shrinking and obfuscation.

-keep class com.kakao.sdk.**.model.* { <fields>; }
-keep class * extends com.google.gson.TypeAdapter

Initialize SDK

After installing the SDK, you need to initialize the SDK for initial setup.

Initialize the KakaoSDK instance by adding the init method in the Application instance with your Native app key.

class GlobalApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    // Other codes for initialization 

    // Initialize Android SDK 
    KakaoSdk.init(this, "${YOUR_NATIVE_APP_KEY}")
  }
}

Add key hashes

Key hashes are the values hashed from the certificate fingerprints of the certificate and used to check if your app is malicious and the updates or changes are from your original app. When you call the Kakao APIs, the API server checks if the key hash added to your request matches the value specified in [My Application] > [Platform] for identification. Key hash has two types:

  • Debug key hash: is generated from a Debug certificate that is automatically generated from Android Studio when you run or debug your project.
  • Release key hash: is generated from a Release certificate that you have created to release your app to the store. If you use Google Play App Signing, obtain a Release certificate from the app signing page in the Play Console.

Use one of methods to get a debug key hash and a release key hash.

Using Terminal to generate Debug and Release key hashes

To get key hashes using Terminal, you need the Keytool program, key and certificate management tool. On Windows, you need to download OpenSSL for Windows libraries. on Mac, Keytool has already installed.

Run the command in Command Prompt according to your operating system.

Debug key hash
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
Release key hash
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
Using Kakao SDK to get Debug and Release key hashes

You can also get a key hash by calling the getKeyHash() method provided in Utility through the Android SDK. With this, you can obtain either a debug or release key hash depending on when you call this method.

import com.kakao.sdk.common.util.Utility

var keyHash = Utility.getKeyHash(this)
Using the Google Play Console to get Release key hash

If you use Google Play App Signing, you must use the SHA-1 certificate fingerprint obtained on the Google Play Console, not generating a Release key hash on the Terminal. Refer to Play Console Help > Use Play App Signing for more details.

  1. In the Google Play Console, select [Release Management] > [App Signing] menu, and then copy the value of 'SHA-1 certificate fingerprint'.
    If you have a certificate file (deployment_cert.der) only without permission to access the Google Play Console, run the following command.
keytool -printcert -file ./deployment_cert.der 
  1. Run the following command in Terminal with the SHA-1 certificate fingerprint value obtained in Step 1.
echo "{SHA-1_CERTIFICATE_FINGERPRINT}" | xxd -r -p | openssl base64 

When you get key hashes, go to [My Application] > [Platform] > [Android platform registration], and register all of your key hashes in 'Key hash'. Refer to Register platforms for more details.

IMPORTANT: When registering key hashes

Make sure to add all debug key hashes by development environments and a release key hash. You cannot make Kakao API calls from an app which a key hash is not registered in.

If several developers are participated in developing an app, you must register all debug key hashes that each developer has because they have all different debug key hashes depending on development environments.

Migrate v1 to v2

You can migrate the Legacy Android SDK (version 1.x.x) to the latest version of Android SDK (version 2.x.x) using this migration guide.

Module structure

The latest Android SDK has a simpler module structure compared to the Legacy Android SDK. The latest Android SDK provides the common module that contains the common and utility features and the Kakao Login function. In addition, each module provides APIs that are grouped by service under Client, and object and structure information is located in Model, which allows you to use the Android SDK more efficiently and conveniently.

Notice when using token-based APIs

The token-based APIs refer to the APIs that require Kakao Login with which you can get an access token. To use the token-based APIs in the latest Android SDK, you must implement Kakao Login that the common module provides. When you add the desired modules, the common module is installed by default.

API comparison by version

Common
  • Legacy SDK:
    • Set an app key in AndroidManifest.xml.
    • Call a function that initializes SDK through KakaoSDK.
    • Call a function that gets a key hash through Utility in the com.kakao.util package.
  • Latest SDK:
Name Legacy SDK SDK
Initializing Kakao SDK init() init()
Getting a key hash getKeyHash() getKeyHash()
Kakao Login
Name Legacy SDK SDK
Checking if Kakao Talk is installed - isKakaoTalkLoginAvailable()
Login with Kakao Talk - loginWithKakaoTalk(context)
Login with Kakao Account - loginWithKakaoAccount(context)
Checking token presence isOpened() hasToken()
Logout requestLogout() logout()
Unlink requestUnlink() unlink()
Retrieving token information requestAccessTokenInfo() accessTokenInfo()
Retrieving user information me() me()
Retrieving shipping address shippingAddresses() shippingAddresses()
Storing user information requestUpdateProfile(properties) updateProfile()
Requesting additional consent updateScopes(scopes) loginWithNewScopes(context, scopes)
Retrieving user agreed terms serviceTerms() serviceTerms()
Getting consent to desired term - loginWithKakaoTalk(context, serviceTerms)
loginWithKakaoAccount(context, serviceTerms)
Kakao Talk Social
  • Legacy SDK: Call the Kakao Talk Social APIs through KOSessionTask.
  • Latest SDK: Call the Kakao Talk Social APIs through TalkApiClient in the v2-talk module.
Name Legacy SDK SDK
Retrieving Kakao Talk profile requestProfile() profile()
Retrieving list of friends requestAppFriends() friends()
Message: Kakao Talk Sharing
  • Legacy SDK:
    • Call the Kakao Talk sharing APIs through KakaoLinkService.
    • If Kakao Talk is not installed on a user's device, a message is internally sent through a WebView.
  • Latest SDK:
    • Call the Kakao Talk sharing APIs through ShareClient in the v2-share module.
    • Pass context for the Sending message API.
    • If Kakao Talk is not installed on a user's device, implement a process to share URI through a WebView or a default browser.
IMPORTANT

In Android SDK 2.11.0, the names of the module, classes, and methods related to Kakao Talk sharing have been changed due to the change of its service name. To see more detailed changes, see Version history.

Name Legacy SDK SDK
Checking if Kakao Talk is installed - isKakaoTalkSharingAvailable()
Sending with default template sendDefault(template) shareDefault(context, defaultFeed)
Sending with custom template sendCustomWithTemplateId(templateId) shareCustom(context, templateId)
Sending a scrap message sendScrapWithURL(url) shareScrap(context, url)
Uploading an image uploadImage(imageFile) uploadImage(file)
Scraping an image scrapWithImageURL:imageURL: scrapImage(url)
Message: Kakao Talk Messaging
  • Legacy SDK: Call the Kakao Talk APIs through KakaoTalkService.
  • Latest SDK: Call the Kakao Talk APIs through TalkApiClient in the v2-talk module.
Name Legacy SDK SDK
Sending me with default template requestSendMemo(template) sendDefaultMemo(template)
Sending me with custom template requestSendMemo() sendCustomMemo(templateId)
Sending me a scrap message requestSendMemo(url) sendScrapMemo(url)
Sending friends with default template sendMessageToFriends(template, uuids) sendDefaultMessage(template, receiverUuids)
Sending friends with custom template sendMessageToFriends(templateId, uuids) sendCustomMessage(templateId, receiverUuids)
Sending friends a scrap message sendMessageToFriend(url, uuids) sendScrapMessage(url, receiverUuids)
Kakao Story
  • Legacy SDK: Call the Kakao Story APIs through KakaoStoryService.
  • Latest SDK: Call the Kakao Story APIs through StoryApiClient in the v2-story module.
Name Legacy SDK SDK
Validating Kakao Story user requestIsStoryUser() isStoryUser()
Retrieving Kakao Talk profile requestProfile() profile()
Posting text story requestPostNote(content) postNote(content)
Posting photo story requestPostPhoto(content, fileList) postPhoto(content, images)
Posting link story requestPostLink(content, linkUrl) postLink(content, linkInfo)
Retrieving specified story requestGetMyStory(id) story(id)
Retrieving multiple stories requestGetMyStories() stories()
Deleting story requestDeleteMyStory(id) delete(id)
Uploading image - upload(images)
Scraping web page - linkInfo(url)
Kakao Talk Channel
  • Legacy SDK:
    • Call the Adding Kakao Talk Channel and Kakao Talk Channel chat APIs through PlusFriendService.
    • Call the Checking Kakao Talk Channel relationship API through KakaoTalkService.
  • Latest SDK:
    • Call the Adding Kakao Talk Channel and Kakao Talk Channel chat APIs through TalkApiClient in the v2-talk module.
    • Call the Checking Kakao Talk Channel relationship API after implementing Kakao Login.
Name Legacy SDK SDK
Adding Kakao Talk Channel addFriend(plusFriendId) addChannelUrl(channelPublicId)
Starting Kakao Talk Channel chat chat(plusFriendId) channelChatUrl(channelPublicId)
Checking Kakao Talk Channel relationship requestPlusFriends() channels()
Kakao Navi
  • Legacy SDK:
    • Call the Navi APIs through KakaoNaviService.
    • Call newBuilder() of each class and setNaviOptions() to set parameters.
  • Latest SDK:
    • Call the Navi APIs through NaviClient in the v2-navi module.
    • Define the constructor for each class to set parameters.
Name Legacy SDK SDK
Navigation navigate(destination) navigateIntent(location, naviOption)
Getting URL for navigation - Deprecated navigateWebUrl(location, naviOption)
Sharing location shareDestination(destination) shareDestinationIntent(location, naviOption)
Setting conditions for navigation newBuilder()
setNaviOptions(options)
NaviOption()
Setting conditions for destination information newBuilder()
setNaviOptions(options)
Location()
Push Notification
  • Legacy SDK
  • Latest SDK: Not support Push Notification API. You can send the push notifications only using REST API.
Name Legacy SDK SDK
Registering push token registerPushToken(pushToken, deviceId) -
Retrieving push token getPushTokens() -
Deleting push token deregisterPushToken(deviceId) -

See more

Legacy

To see how to use the Legacy Kakao SDK for Android, see Getting Started Guide for Legacy Android SDK.

It is highly recommended to migrate to the new version of Android SDK as soon as possible because the Legacy version may not be supported anymore.