Getting Started

This guide explains how to add navigation to your Android app with the Kakao Navi Directions SDK with UI (the Directions SDK with UI). The SDK includes ready-made navigation UI components, so you can add route guidance to your app without building your own UI.

TIP

This document is based on Directions SDK with UI version 1.12.8-hotfix02.

Launching Kakao Navi for route guidance

To share a destination or launch route guidance through the Kakao Navi app, use the Kakao Navi module of the Kakao SDK. If the Kakao Navi app is not installed, the user is directed to the app installation page.

For details, see Kakao Navi on Kakao Developers.

Before you begin

Requirements

Check the programming language used by the Directions SDK with UI 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 Directions SDK with UI, 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 steps.
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. You can view the created app 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.

Mac

bash

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

Windows

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 Directions SDK with UI 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 Directions SDK with UI in Eclipse?

Support for the Eclipse development environment via Kakao SDK source is no longer officially provided. To use the Directions SDK with UI 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

Configuring Gradle

You can easily integrate the Directions SDK with UI 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.

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 Directions SDK with UI 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 Directions SDK with UI 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-v7a", "arm64-v8a"
     }
   }
}

Configuring the module

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

kotlin

dependencies {
    implementation 'com.kakaomobility.knsdk:knsdk_ui:1.12.8-hotfix02'
}

3. Configuring permissions

Internet connection permission

To use the internet in the Directions SDK with UI, 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 Directions SDK with UI. 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 Directions SDK with UI, 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 Directions SDK with UI, which you can obtain from Kakao Developers. With it, you can initialize the SDK and use route guidance features.

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

Getting Started

Launching Kakao Navi for route guidance

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

Getting Started ​

Launching Kakao Navi for route guidance ​

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 ​

Getting Started

Launching Kakao Navi for route guidance

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