시작하기 | 카카오모빌리티 디벨로퍼스

카카오모빌리티 디벨로퍼스 문서 카카오내비 길찾기 SDK with UI 시작하기

시작하기 전에 링크 복사

요구 사항 링크 복사

Android 길찾기 UI SDK에서 사용하는 프로그래밍 언어와 필요한 최소 요구 사항을 확인하세요.

프로그래밍 언어: Kotlin
Java 11 이상
안드로이드 스튜디오(Android Studio) Ladybug 2024.2.2 버전 이상
API 26: Android 8.0(Oreo) 이상

앱 등록 및 네이티브 앱 키 확인하기 링크 복사

Android 길찾기 UI SDK를 사용하려면 반드시 앱 등록과 SDK 초기화를 위한 네이티브 앱 키를 발급 받아야 합니다.

1. 앱 등록하기 링크 복사

[카카오디벨로퍼스에서 진행]

카카오디벨로퍼스에 로그인하세요. 계정이 없을 경우, 회원 가입을 한 후 다음 단계를 진행하세요.
로그인 후, 화면 오른쪽 상단에서 앱 → 앱 생성을 클릭하세요.
아래 각 항목에 추가할 내용을 확인하여 앱을 추가하세요.
- 앱 아이콘: 앱 아이콘으로 사용할 이미지를 추가합니다. 권장하는 이미지의 사이즈는 128 px * 128 px이며 최대 250 KB 크기의 파일을 등록할 수 있습니다. 지원하는 파일 포맷은 JPG, GIF, PNG입니다.
- 앱 이름: 내 앱(서비스)의 이름을 설정합니다. * 필수 입력 사항
- 회사명: 사업자명을 입력합니다. 사업자 정보와 동일한 이름을 사용해야 합니다. * 필수 입력 사항
  
  주의: 앱(서비스) 이름은 공백 포함 30자까지 입력할 수 있습니다.
- 카테고리: 서비스의 카테고리를 선택합니다. * 필수 입력 사항
- 앱 대표 도메인: 서비스의 대표 도메인을 입력합니다.
각 항목을 입력하고, 운영 정책에서 제한하는 사항에 해당하지 않은지 확인 후, 저장을 눌러 앱을 생성하세요.

생성된 앱은 앱에서 확인할 수 있습니다.

2. 키 해시 생성하기 링크 복사

SDK를 사용하려면 앱 인증을 위해 키 해시가 필요합니다. 키 해시는 안드로이드 스튜디오의 터미널에서 keytool을 사용하여 생성합니다.

안드로이드 스튜디오 열고 상단 메뉴에서 View → Terminal을 클릭합니다.
아래 명령어를 입력하여 키 해시를 생성합니다. 키 저장소의 비밀번호는 android입니다.

keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64
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
keytool -exportcert -alias androiddebugkey -keystore %USERPROFILE%\.android\debug.keystore -storepass android -keypass android | openssl sha1 -binary | openssl base64

코드가 숨겨졌습니다.

3. 생성된 키 해시 값은 다음 단계에서 서비스 정보 등록 시 입력합니다.

3. 서비스 정보 등록하기 링크 복사

[카카오디벨로퍼스에서 진행]

SDK 초기화에는 네이티브 앱 키가 필요하며, 사용 전 서비스 정보를 카카오디벨로퍼스에 등록해야 합니다.

앱 → 앱 키를 발급할 앱 선택 → 앱 → 플랫폼 키을 클릭하세요.
네이티브 앱 키 추가 또는 생성된 기본 키를 선택하세요.
필요한 서비스 정보 항목을 등록하세요.

네이티브 앱 키: 발급된 키 값과 상태를 확인하고 복사할 수 있습니다.
키 이름: 키를 식별하기 위한 이름을 지정합니다. * 필수 입력 사항
패키지명: Android 앱의 고유 식별자로, AndroidManifest.xml의 package 속성에서 확인할 수 있습니다.
(Android) 스토어 URL: 앱 미설치 시 이동할 Play Store URL을 등록합니다. 패키지명을 입력하면 기본 URL이 자동 설정됩니다.
(Android) 키 해시: Android 앱 서명 키의 식별자로, SDK 사용을 위해 필수로 등록해야 합니다. 키 해시 생성하기 단계에서 생성한 해시 값을 입력합니다.
스킴: 해당 키에 발급된 앱 스킴 정보를 확인할 수 있습니다.
추가 정보: 키의 활성화 상태와 생성일, 수정일 정보를 확인할 수 있습니다.

4. 네이티브 앱 키 확인하기 링크 복사

[카카오디벨로퍼스에서 진행]

앱 → 앱 키를 발급할 앱 선택 → 앱 → 플랫폼 키을 클릭하세요.
네이티브 앱 키 값을 복사하여 사용하세요.

자세한 내용은 카카오디벨로퍼스의 앱 설정을 참고하세요.

프로젝트 시작하기 링크 복사

Android 길찾기 UI SDK는 gradle 기반으로 만들어져 안드로이드 스튜디오 IDE에서 최적화된 환경을 제공합니다. 따라서 이 문서에서는 안드로이드 스튜디오 IDE에서 Android 길찾기 UI SDK를 사용하는 방법을 안내합니다.

안드로이드 스튜디오를 설치하지 않았다면 안드로이드 스튜디오 다운로드하기를 눌러 다운로드해 주세요.

Eclipse에서는 Android 길찾기 UI SDK를 어떻게 사용하나요?

Kakao SDK 소스를 통한 Eclipse 개발 환경 지원은 더 이상 공식적으로 지원하지 않습니다. Eclipse에서 Android 길찾기 UI SDK를 사용하려면 Gradle을 사용해야 합니다.

1. 신규 프로젝트 생성하기 링크 복사

아래의 절차에 따라 프로젝트를 생성하세요.

해당 내용은 안드로이드 스튜디오 버전 4.3.0을 기준으로 작성되었습니다. 사용하는 버전에 따라 화면 및 세부 내용은 문서 내 설명과 다를 수 있습니다.

안드로이드 스튜디오를 실행한 후 Projects → New Project를 클릭합니다.
Templates에서 Phone and Tablet → Empty Activity를 선택한 후 Next를 클릭합니다.
프로젝트의 이름, 저장 장소 등을 설정합니다. Language와 Minimum SDK는 요구 사항 항목을 참고하여 설정합니다. 설정이 완료되면 Finish를 클릭합니다.

성공적으로 프로젝트가 생성되면 아래와 같이 나타납니다.

2. 프레임워크 추가하기 링크 복사

Android 길찾기 UI SDK 1.6.0 버전부터 Maven을 통해 레파지토리를 설정할 수 있습니다. 1.6.0 이전 버전을 사용한다면 1.6.0 미만 버전 사용 시를 참고하세요.

Gradle 설정하기 링크 복사

프로젝트의 Gradle 설정을 통해 Android 길찾기 UI SDK를 간편하게 연동할 수 있습니다.

Android Studio의 버전에 따라 Gradle의 설정이 달라집니다. 아래 표에서 버전을 확인한 다음 각 버전에 맞는 파일에 Maven 레파지토리(Repository)를 설정하세요.

표 1 Android Studio 버전에 따른 레파지토리 설정 경로

버전	파일 경로
Arctic Fox - 2020.3.1 이하 버전	build.gradle
Bumblebee - 2021.1.1 이상 버전	settings.gradle

// build.gradle(Project) 파일에 다음과 같이 Android 길찾기 UI SDK 레파지토리 설정

allprojects {
    repositories {
	      google()
	      jcenter()
        maven { url "https://devrepo.kakaomobility.com/repository/kakao-mobility-android-knsdk-public/"}
        maven { url "https://www.jitpack.io" } 
	  }
}
// build.gradle(Project) 파일에 다음과 같이 Android 길찾기 UI SDK 레파지토리 설정

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

// settings.gradle(Project) 파일에 다음과 같이 Android 길찾기 UI SDK 레파지토리 설정

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" } 
	  }
}
// settings.gradle(Project) 파일에 다음과 같이 Android 길찾기 UI SDK 레파지토리 설정

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" } 
	  }
}

코드가 숨겨졌습니다.

ABI 필터 설정하기 링크 복사

Realm 라이브러리는 여러 CPU 아키텍처를 지원하기 위해 다양한 ABI(Application Binary Interface) 버전을 포함합니다. 이는 안드로이드 앱 패키지(APK, Android application package)의 크기를 증가시킬 수 있습니다. ABI 필터를 사용하면 특정 CPU 타입의 라이브러리만 빌드에 포함시켜 APK의 용량을 줄일 수 있습니다. build.gradle에서 ABI 필터를 설정하세요.

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

코드가 숨겨졌습니다.

모듈 설정하기 링크 복사

프로젝트 gradle의 설정이 완료되면, build.gradle(Module)에서 Android 길찾기 UI SDK 모듈의 의존성(Dependencies)을 설정하세요.

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

코드가 숨겨졌습니다.

3. 권한 설정하기 링크 복사

인터넷 연결 권한 링크 복사

Android 길찾기 UI SDK에서 인터넷을 사용하기 위해 인터넷 연결 권한을 설정해야 합니다. 인터넷 사용을 허용하기 위해서 uses-permission 속성에 android.permission.INTERNET을 지정합니다.

경로: app → manifests → AndroidManifest.xml

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

// 인터넷 연결 권한 설정
<uses-permission android:name="android.permission.INTERNET" />
<?xml version="1.0" encoding="utf-8"?>

// 인터넷 연결 권한 설정
<uses-permission android:name="android.permission.INTERNET" />

코드가 숨겨졌습니다.

위치 정보 접근 권한 링크 복사

사용자의 위치 정보를 가져오기 위해 위치 정보 접근 권한을 설정해야 합니다. Android에서는 두 가지 위치 정보 접근 권한을 제공하며 선택한 권한에 따라 위치의 정확도가 달라집니다. 필요한 정확도에 따라 아래의 접근 권한 중 하나를 선택하여 요청하세요.

android.permission.ACCESS_COARSE_LOCATION: Wi-Fi 또는 모바일 데이터를 바탕으로 기기의 위치 파악합니다.
android.permission.ACCESS_FINE_LOCATION: 위성 위치 확인 시스템(GPS), Wi-Fi, 모바일 데이터를 바탕으로 기기의 위치 파악합니다.

경로: app → manifests → AndroidManifest.xml

// 위치 정보 접근 권한 설정(둘 중 한 가지만 선택하여 사용)
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> 
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> 
// 위치 정보 접근 권한 설정(둘 중 한 가지만 선택하여 사용)
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> 
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

코드가 숨겨졌습니다.

4. 앱 화면 구성하기 링크 복사

activity_main.xml 파일은 앱의 화면 구조를 정의하는 xml 파일입니다. 다음 예제를 참고하여 xml 파일을 설정합니다.

경로: app → res → layout → activity_main.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>
<?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. Main Activity 파일 설정하기 링크 복사

Android 길찾기 UI SDK를 구동하기 위한 초기 설정을 진행해야 합니다. 콘텍스트 등록 및 파일 등의 저장 경로를 설정하세요.

경로: app → java → com.프로젝트명 → activity → MainActivity.kt

class MainActivity : AppCompatActivity() {
	override fun onCreate() {
		super.onCreate()
		KNSDK.apply {
		// 콘텍스트 등록 및 DB, 파일 등의 저장 경로 설정
		install(instance, "$filesDir/[your_path]")
		}
	}
}
class MainActivity : AppCompatActivity() {
	override fun onCreate() {
		super.onCreate()
		KNSDK.apply {
		// 콘텍스트 등록 및 DB, 파일 등의 저장 경로 설정
		install(instance, "$filesDir/[your_path]")
		}
	}
}

코드가 숨겨졌습니다.

6. 초기화하기 링크 복사

Android 길찾기 UI SDK를 사용하려면 네이티브 앱 키를 사용하여 초기화해야 합니다.

사용할 수 있는 키 값에 대한 정보는 아래와 같습니다.

AppKey: String Android 길찾기 UI SDK를 사용하기 위해 필요한 네이티브 앱 키로 카카오디벨로퍼스에서 발급받을 수 있습니다. 이를 통해 SDK를 초기화하고 길찾기 기능을 사용할 수 있습니다.
UserKey: String 사용자를 구분하기 위한 키로 임의의 값을 할당하여 사용하며, 사용 환경에 맞게 자유롭게 설정할 수 있습니다. 예를 들어, 기존에 사용하고 있는 회원 번호를 키 값으로 지정하여 사용할 수 있습니다.

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

코드가 숨겨졌습니다.

사용자 맞춤 설정하기