Getting Started

Before you begin

Requirements

Check the programming language used by the Android Directions SDK and the minimum requirements.

Programming language: Kotlin
Java 11 or later
Android Studio Ladybug 2024.2.2 or later
API 26: Android 8.0 (Oreo) or later

Registering an app and checking the native app key

DANGER

To use the Android Directions SDK, you must register an app and obtain a native app key for SDK initialization.

1. Registering an app

[On Kakao Developers]

Log in to Kakao Developers. If you do not have an account, sign up and then proceed to the next step.
After logging in, click App → Create app at the top right of the screen.
Check the content to add for each item below and add your app.

App icon: Add an image to use as the app icon. The recommended image size is 128x128 px, and you can upload a file of up to 250 KB. Supported file formats are JPG, GIF, and PNG.
App name: Set the name of your app (service). * Required
Company name: Enter the business name. You must use the same name as your business information. * Required

DANGER

Note: The app (service) name can be up to 30 characters, including spaces.

Category: Select the category of your service. * Required
App primary domain: Enter the primary domain of your service.

Enter each item, verify that it does not violate any restrictions in the operating policy, and click Save to create the app. The new app appears under App.

2. Generating a key hash

To use the SDK, a key hash is required for app authentication. Generate the key hash using keytool in the Android Studio terminal.

Open Android Studio and click View → Terminal in the top menu.
Enter the command below to generate the key hash. The keystore password is android.

MacWindows

bash

keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64

bash

keytool -exportcert -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64

Enter the generated key hash value when registering the service information in the next step.

3. Registering service information

[On Kakao Developers]

SDK initialization requires a native app key, and you must register the service information on Kakao Developers before use.

Click App → select the app to issue an app key for → App → Platform key.
Select Add key to add a native app key, or select the default key that was created.
Register the required service information items.

Native app key: Check the issued key value and its status, and copy it.
Key name: Specify a name to identify the key. * Required
Package name: The unique identifier of the Android app, which you can find in the package attribute of AndroidManifest.xml.
(Android) Store URL: Register the Play Store URL to open when the app is not installed. When you enter the package name, the default URL is set automatically.
(Android) Key hash: The identifier of the Android app signing key, which must be registered to use the SDK. Enter the hash value generated in the Generating a key hash step.
Scheme: Check the app scheme information issued for the key.
Additional information: Check the key's activation status, creation date, and modification date.

4. Checking the native app key

[On Kakao Developers]

Click App → select the app to issue an app key for → App → Platform key.
Copy and use the native app key value.

TIP

For details, see App settings on Kakao Developers.

Starting a project

The Android Directions SDK is built on Gradle and provides an optimized environment in the Android Studio IDE. This guide uses Android Studio.

TIP

If you have not installed Android Studio, click Download Android Studio to download it.

How do I use the Android Directions SDK in Eclipse?

Support for the Eclipse development environment through Kakao SDK source is no longer officially provided. To use the Android Directions SDK in Eclipse, you must use Gradle.

1. Creating a new project

Follow the steps below to create a project.

TIP

This content is based on Android Studio version 4.3.0. The screens and details may differ from the descriptions in this document depending on the version you use.

Launch Android Studio and click Projects → New Project.
Under Templates, select Phone and Tablet → Empty Activity, then click Next.
Set the project name, save location, and other settings. Set Language and Minimum SDK based on the requirements section. Once the settings are complete, click Finish.

When the project is created successfully, it appears as shown below.

2. Adding the framework

From Android Directions UI SDK version 1.6.0, you can configure the repository through Maven. If you are using a version earlier than 1.6.0, refer to When using a version earlier than 1.6.0.

Configuring Gradle

You can easily integrate the Android Directions SDK through the project's Gradle settings.

The Gradle configuration differs depending on the Android Studio version. Check your version in the table below, then configure the Maven repository in the file that matches your version.

Table 1 Repository configuration path by Android Studio version

Version	File path
Arctic Fox - 2020.3.1 or earlier	build.gradle
Bumblebee - 2021.1.1 or later	settings.gradle

Arctic Fox or earlierBumblebee or later

kotlin

// Configure the Android Directions SDK repository in the build.gradle(Project) file as follows

allprojects {
    repositories {
	      google()
	      jcenter()
        maven { url "https://devrepo.kakaomobility.com/repository/kakao-mobility-android-knsdk-public/"}
        maven { url "https://www.jitpack.io" } 
	  }
}

kotlin

// Configure the Android Directions SDK repository in the settings.gradle(Project) file as follows

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
	      google()
	      mavenCentral()
        maven { url "https://devrepo.kakaomobility.com/repository/kakao-mobility-android-knsdk-public/"}
        maven { url "https://www.jitpack.io" } 
	  }
}

Configuring ABI filters

The Realm library includes various ABI (Application Binary Interface) versions to support multiple CPU architectures. This can increase the size of the Android application package (APK). Using ABI filters, you can include only the libraries for specific CPU types in the build to reduce the APK size. Configure the ABI filters in build.gradle.

kotlin

android {
   defaultConfig {
     ...
     ndk {
        abiFilters "armeabi, armeabi-v7a", "arm64-v8a"
     }
   }
}

Configuring the module

Once the project Gradle configuration is complete, set the dependencies for the Android Directions SDK module in build.gradle(Module).

kotlin

dependencies {
    implementation 'com.kakaomobility.knsdk:knsdk_ui:1.12.7'
}

3. Configuring permissions

Internet connection permission

To use the internet in the Android Directions SDK, you must configure the internet connection permission. To allow internet use, specify android.permission.INTERNET in the uses-permission attribute.

Path: app → manifests → AndroidManifest.xml

xml

<?xml version="1.0" encoding="utf-8"?>

// Configure the internet connection permission
<uses-permission android:name="android.permission.INTERNET" />

Location access permission

To obtain the user's location information, you must configure the location access permission. Android provides two location access permissions, and the location accuracy varies depending on the permission you choose. Request one of the access permissions below according to the accuracy you need.

android.permission.ACCESS_COARSE_LOCATION: Determines the device's location based on Wi-Fi or mobile data.
android.permission.ACCESS_FINE_LOCATION: Determines the device's location based on GPS (Global Positioning System), Wi-Fi, and mobile data.

Path: app → manifests → AndroidManifest.xml

xml

// Configure the location access permission (choose only one of the two)
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> 
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

4. Composing the app screen

The activity_main.xml file is an xml file that defines the screen structure of the app. Configure the XML file as shown in the following example.

Path: app → res → layout → activity_main.xml

xml

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    ...>
    ...

    <com.kakaomobility.knsdk.ui.view.KNNaviView
        android:id="@+id/navi_view"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintBottom_toBottomOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintEnd_toEndOf="parent" />
    
    ...
</androidx.constraintlayout.widget.ConstraintLayout>

5. Configuring the Main Activity file

You must perform the initial setup to run the Android Directions SDK. Register the context and set the save path for files and other data.

Path: app → java → com.projectname → activity → MainActivity.kt

kotlin

class MainActivity : AppCompatActivity() {

	override fun onCreate() {
		super.onCreate()
		KNSDK.apply {
			// Register the context and set the save path for the DB, files, and so on
			install(instance, "$filesDir/[your_path]")
		}
	}
}

6. Initializing

To use the Android Directions SDK, you must initialize it using the native app key.

Information about the key values you can use is as follows.

AppKey: String The native app key required to use the Android Directions SDK, which you can obtain from Kakao Developers. With it, you can initialize the SDK and use the directions features.
UserKey: String A key for distinguishing users. Assign an arbitrary value and set it freely to suit your environment. For example, you can specify an existing member number as the key value.

kotlin

// Initialize the app
KNSDK.apply {  
    initializeWithAppKey(appKey, VERSION_NAME,
      GlobalApplication.prefs.getUserId(), language, aCompletion = {  
        if (it != null) {  
          when (it.code) {  
            KNError_Code_C302 -> {  
            }  
            else -> {  
            }  
        }  
      } else {                  
    }})  
}

Guide

Guide

Guide

Drawing on the map

Guide

Drawing on the map

Before you begin

Requirements

Registering an app and checking the native app key

1. Registering an app

2. Generating a key hash

3. Registering service information

4. Checking the native app key

Starting a project

1. Creating a new project

2. Adding the framework

Configuring Gradle

Configuring ABI filters

Configuring the module

3. Configuring permissions

Internet connection permission

Location access permission

4. Composing the app screen

5. Configuring the Main Activity file

6. Initializing

Drawing on the map

Drawing on the map

Before you begin ​

Requirements ​

Registering an app and checking the native app key ​

1. Registering an app ​

2. Generating a key hash ​

3. Registering service information ​

4. Checking the native app key ​

Starting a project ​

1. Creating a new project ​

2. Adding the framework ​

Configuring Gradle ​

Configuring ABI filters ​

Configuring the module ​

3. Configuring permissions ​

Internet connection permission ​

Location access permission ​

4. Composing the app screen ​

5. Configuring the Main Activity file ​

6. Initializing ​

Before you begin

Requirements

Registering an app and checking the native app key

1. Registering an app

2. Generating a key hash

3. Registering service information

4. Checking the native app key

Starting a project

1. Creating a new project

2. Adding the framework

Configuring Gradle

Configuring ABI filters

Configuring the module

3. Configuring permissions

Internet connection permission

Location access permission

4. Composing the app screen

5. Configuring the Main Activity file

6. Initializing