카카오내비

카카오내비 API는 카카오내비 서비스에서 제공하는 API를 말하며, 다음과 같은 기능을 제공합니다.

  • 목적지 공유
    카카오내비 앱을 호출하여 목적지를 공유합니댜.
  • 목적지 길안내
    카카오내비 앱을 호출하여 목적지까지 길안내를 실행합니다.

Kakao Navi SDK 설치

카카오 내비 연동 기능을 사용하기 위해서는 카카오에서 제공하는 Kakao Navi SDK가 필요합니다.

Kakao Navi SDK는 ARMv7, ARMv7s, ARM64를 지원하며 iOS 8.0 버전 이상이 필요합니다. 자세한 사양은 iOS Support Matrix를 참고 하세요.

다운로드

iOS용 최신 Kakao SDK를 직접 다운로드 하시려면 최신 SDK 다운로드를 클릭해 주세요.

그외 제공되는 Kakao SDK의 자세한 정보는 SDK 다운로드에서 확인하실 수 있습니다.

압축풀기

위에서 다운로드한 파일의 압축을 풉니다.

unzip kakao-ios-sdk-x.x.x.zip

압축을 풀면 카카오에서 제공하는 각종 SDK의 .framework 파일들과 샘플(samples) 폴더를 볼 수 있습니다.

sdk-ios-framework-unzip

개발프로젝트 설정

Kakao SDK를 개발툴에 설정하는 방법을 설명합니다.

Kakao Navi SDK import

다운로드 받은 KakaoNavi.framework, KakaoCommon.framework 폴더를 Project의 Frameworks Group 에 drag & drop 합니다.

drag_sdk

drag_sdk

Link Binary With Libraries에 SDK framework 가 올바르게 추가되어 있는지 확인합니다. link_binary_with_binaries_confirm

이로서 기본적인 프로젝트 설정은 완료되었습니다. 아래는 이 프로젝트에서 사용할 애플리케이션을 생성하고 사용하는 방법을 설명합니다.

앱 생성

내 앱 생성

내 애플리케이션 > 앱 만들기를 통해 애플리케이션(이하 '앱')을 생성합니다.

앱을 처음 생성한다면 로그인 후 아래와 같은 화면이 나타납니다. dev_002.png

이미 앱을 하나 이상 만들었다면 아래와 같은 화면이 나타납니다. dev_003.png

앱 이름을 입력하고 만들기 버튼을 클릭하면 앱 생성이 완료되고 앱 키가 할당됩니다. iOS SDK를 사용할 때에는 네이티브 앱 키를 사용합니다. 설정을 클릭하여 설정을 이어 갑니다. dev_004.png

플랫폼 추가 > iOS 선택후 번들ID를 입력합니다. 여기서 입력한 번들ID는 XCode Project의 Bundle Identifier 값과 일치하여야 합니다. 이 내용은 아래에 이어지는 '프로젝트에 내 앱 설정' 에서 한번 더 설명하고 있습니다. dev_013_ios.png

프로젝트에 내 앱 설정

카카오 개발자 웹사이트에 등록된 해당 앱의 네이티브 앱 키를 프로젝트 plist 파일에 등록을 합니다. "KAKAO_APP_KEY"라는 이름으로 Key를 추가하고, Type은 String, Value는 해당 앱의 네이티브 앱 키 값으로 등록합니다. App Key 등록

LSApplicationQueriesSchemes 설정 (iOS 9.0 이상)

카카오내비 앱을 실행하기 위한 URL Scheme을 LSApplicationQueriesSchemes에 등록합니다. info.plist 파일에 다음과 같이 “kakaonavi-sdk” 항목을 추가합니다. LSApplicationQueriesSchemes에 카카오내비 URL scheme 등록

웹 길안내 설정

카카오내비 앱이 설치되지 않은 상태로 목적지 공유나 길안내 실행 시 HTML5로 구현된 웹 길안내 페이지로 연동됩니다. 아래에 웹 길안내와 관련된 설정 방법을 설명합니다.

iOS 10 이상부터는 사용자의 위치정보에 접근하기 위하여 이용목적 설명을 info.plist 파일에 추가해야 합니다. SDK에서 제공하는 WebView가 위치정보를 사용할 수 있도록 다음과 같이 "Privacy - Location When In Use Usage Description" 항목을 추가합니다. 위치정보 이용목적 설정

시작하기

카카오내비 API를 사용하기 위해서는 관련 헤더파일을 추가해야합니다.

#import <KakaoNavi/KakaoNavi.h>

API 요청은 KNVNaviLauncher를 이용합니다. KNVNaviLauncher는 iOS URL Scheme을 이용하여 카카오내비 앱을 구동하거나 브라우저를 열어서 목적지 공유/길안내 기능을 실행합니다. 카카오내비 앱이 설치되어 있을 경우에는 앱을 호출하고 그렇지 않을 경우에는 기본 브라우저로 카카오내비의 웹버전을 엽니다.

카카오내비 API는 카카오내비 앱을 호출할 때, 제공되는 모든 파라미터들 채워넣을 수 있는 KNVParams 클래스의 객체를 사용합니다. 아래에는 이 API가 제공하는 다양한 파라미터들을 어떻게 구성할 수 있는지 설명하겠습니다.

파라미터 구성

KNVParams클래스는 목적지가 필수 입력 사항입니다. KNVLocation클래스를 이용하여 목적지를 생성하고 initWithDestination: 메소드 또는 paramsWithDestination: 메소드를 이용하여 생성합니다. 추가적으로 옵션을 설정하기 위해서는 생성된 params 객체에 KNVOptions객체를 추가하고 경유지는 KNVLocation의 배열을 생성하여 추가합니다. 아래에는 더 자세한 파라미터 설정 방법을 설명합니다.

KNVLocation

카카오내비 API에서 지도상의 특정 위치를 정의하는 class. 목적지 또는 경유지로 사용됩니다. 좌표계는 KATEC, WGS84가 사용되며 기본 값은 KATEC입니다. WGS84 좌표계를 사용하려면 KNVOptions객체를 활용하여 coordType을 KNVCoordTypeWGS84로 지정해야 합니다.

Name Type Description Default Usage
name NSString* 장소 이름 (필수) 공유/길인내
x NSNumber* 장소 x (경도, 필수) 공유/길인내
y NSNumber* 장소 y (위도, 필수) 공유/길인내
// Location 객체를 만든다.
KNVLocation *destination = [KNVLocation locationWithName:@"카카오판교오피스"
                                                       x:@(321286)
                                                       y:@(533707)];

KNVOptions

카카오내비 API의 선택 파라미터들을 정의하는 class. 이 클래스가 포함하는 모든 파라미터들은 선택적입니다. 목적지 공유에는 coordType만 쓰이고 나머지 파라미터들은 목적지 길안내에 쓰입니다.

Name Type Description Default Usage
coordType KNVCoordType 좌표 타입 katec 공유/길안내
vehicleType KNVVehicleType 차종 FIRST 길안내
rpoption KNVRpOption 경로 옵션 FASTEST 길안내
routeInfo BOOL 전체경로보기 여부 false 길안내
startX NSNumber* 시작좌표 x 길안내
startY NSNumber* 시작좌표 y 길안내
startAngle NSNumber* 시작 앵글 (0~359). 앵글을 설정하지 않을 경우 : -1 길안내
userId NSString* 길안내 유저 구분을 위한 USER ID (현재 택시에서 사용) 길안내
returnUri NSString* 길안내 종료(전체 경로보기시 종료) 후 호출 될 URI 길안내

KNVCoordType

좌표 타입을 정의한 Enum

Name Value Description
KNVCoordTypeKATEC 1 Katec 좌표계
KNVCoordTypeWGS84 2 World Geodetic System 84 좌표계

KNVVehicleType

차종을 정의한 Enum

Name Value Description
KNVVehicleTypeFirst 1 1종 (승용차/소형승합차/소형화물화)
KNVVehicleTypeSecond 2 2종 (중형승합차/중형화물차)
KNVVehicleTypeThird 3 3종 (대형승합차/2축 대형화물차)
KNVVehicleTypeFourth 4 4종 (3축 대형화물차)
KNVVehicleTypeFifth 5 5종 (4축이상 특수화물차)
KNVVehicleTypeSixth 6 6종 (경차)
KNVVehicleTypeTwoWheel 7 이륜차

KNVRpOption

경로 옵션을 정의한 Enum

Name Value Description
KNVRpOptionFast 1 빠른길
KNVRpOptionFree 2 무료도로
KNVRpOptionShortest 3 최단거리
KNVRpOptionNoAuto 4 자동차전용제외
KNVRpOptionWide 5 큰길우선
KNVRpOptionHighway 6 고속도로우선
KNVRpOptionNormal 8 일반도로우선

다음과 같이 KNVOptions 객체를 만듭니다.

KNVOptions *options = [KNVOptions options];
options.coordType = KNVCoordTypeWGS84;
options.vehicleType = KNVVehicleTypeFirst;
options.rpOption = KNVRpOptionShortest;

KNVParams

카카오내비 API 호출을 위한 모든 파라미터들을 담고 있는 class. destination은 목적지 공유와 길안내에 모두 필수적인 파라미터이고 viaList는 목적지 길안내에만 제공되는 선택적 파라미터입니다. 위에 설명된 파라미터들로 KNVParams 객체를 생성하고 API 호출 시에 넘겨주게 됩니다.

Name Type Description Usage
destination KNVLocation* 목적지 (필수) 공유/길안내
options KNVOptions* 옵션 (선택) 공유/길안내
viaList NSArray\<KNVLocation*>* 경유지 (선택, 세개까지 가능) 길안내
목적지와 옵션이 설정된 KNVParams 객체
KNVParams *params = [KNVParams paramsWithDestination:destination
                                             options:options];
경유지를 1개 포함하는 KNVParams 객체
KNVLocation *via1 = [KNVLocation locationWithName:@"판교역 1번출구"
                                                x:@(321525)
                                                y:@(532951)];
NSArray *viaList = [NSArray arrayWithObject:via1];
KNVParams *params = [KNVParams paramsWithDestination:destination
                                             options:options
                                             viaList:viaList];

목적지 공유

KNVNaviLauncher#shareDestinationWithParams: API를 호출합니다.

Name Type Description
params KNVParams* KNVParams객체
error NSError** 실행하는 도중 발생하는 에러

다음은 목적지 공유를 호출하는 예제입니다.

// 목적지 & 파라미터  생성
KNVLocation *destination = [KNVLocation locationWithName:@"카카오판교오피스"
                                                       x:@(321286)
                                                       y:@(533707)];
KNVParams *params = [KNVParams paramsWithDestination:destination];

// 목적지 공유 실행
NSError *error = nil;
[[KNVNaviLauncher sharedLauncher] shareDestinationWithParams:params error:&error];
if (error) {
    ...
}

WGS84 좌표를 사용하여 목적지 공유를 호출하는 예제입니다.

// 목적지 생성
KNVLocation *destination = [KNVLocation locationWithName:@"카카오판교오피스"
                                                       x:@(127.1087)
                                                       y:@(37.40206)];

// WGS84 좌표타입 옵션 설정
KNVOptions *options = [KNVOptions options];
options.coordType = KNVCoordTypeWGS84;

// 목적지 공유 실행
KNVParams *params = [KNVParams paramsWithDestination:destination options:options];
[[KNVNaviLauncher sharedLauncher] shareDestinationWithParams:params error:nil];

다음은 SDK를 통하여 목적지를 공유하였을 때 실행되는 카카오내비 화면입니다.

카카오내비 목적지 공유

목적지 길안내

KNVNaviLauncher#navigateWithParams: API를 호출합니다. 경유지를 세개까지 지정할 수 있습니다.

Name Type Description
params KNVParams* KNVParams 객체
error NSError** 실행하는 도중 발생하는 에러

다음은 목적지 길안내를 호출하는 예제입니다.

// 목적지 생성
KNVLocation *destination = [KNVLocation locationWithName:@"카카오판교오피스"
                                                       x:@(321286)
                                                       y:@(533707)];

// 경유지 생성
KNVLocation *via1 = [KNVLocation locationWithName:@"판교역 1번출구"
                                                x:@(321525)
                                                y:@(532951)];
NSArray *viaList = [NSArray arrayWithObject:via1];

// 파라미터 생성
KNVParams *params = [KNVParams paramsWithDestination:destination
                                             viaList:viaList];

// 길안내 실행
NSError *error = nil;
[[KNVNaviLauncher sharedLauncher] navigateWithParams:params error:&error];
if (error) {
    ...
}

다음은 SDK를 통하여 길안내를 실행하였을 때 안내가 시작된 화면입니다.

카카오내비 목적지 길안내


Last Modified : 2017-07-28