이 문서는 Kakao SDK for iOS(이하 iOS SDK)를 사용한 카카오내비 기능 구현 방법을 소개합니다.
카카오내비 기능은 카카오내비 모듈인 KakaoSDKNavi
가 제공합니다.
카카오내비 기능을 사용하려면 카카오 로그인, 카카오내비 모듈을 모두 설치해야 합니다. 모듈 설치 방법은 설치를 참고합니다.
모듈 설치 후 카카오 로그인과 API를 사용하려면 다음과 같이 import
합니다.
import KakaoSDKNavi
카카오내비 API는 길 안내의 navigateUrl()
와 목적지 공유의 shareUrl()
두 가지 주요 기능을 제공합니다.
navigateUrl()
또는 shareUrl()
는 카카오내비 앱으로 목적지 공유 및 길 안내 기능을 실행하는 URL
을 반환합니다. 카카오내비 앱이 설치되어 있을 경우에는 앱을 호출하고, 그렇지 않을 경우에는 기본 브라우저로 설치 페이지를 엽니다.
카카오내비 앱 실행을 위해 Info.plist 파일에 URI Scheme 설정을 추가합니다. 다음과 같이 LSApplicationQueriesSchemes
에 'kakaonavi-sdk' 값을 추가합니다.
카카오내비 API 호출 시 필요한 파라미터들은 목적지 정보인 NaviLocation
과 검색 조건을 정의한 NaviOption
객체에 담아 전달합니다.
특정 장소를 표현하는 NaviLocation
클래스는 다음과 같이 구성돼 있습니다.
Name | Type | Description |
---|---|---|
name | String |
장소 이름 "우리 집", "회사" 등 |
rpFlag | String |
도착 링크 현재 미지원 |
x | Int64 |
경도 좌표 |
y | Int64 |
위도 좌표 |
길을 찾는 조건을 설정하는 NaviOption
클래스는 다음과 같이 구성돼 있습니다.
Name | Type | Description |
---|---|---|
coordType | CoordType |
사용할 좌표계 |
vehicleType | VehicleType |
차종(기본값: 카카오내비 앱에 설정된 차종) |
rpOption | RpOption |
경로 최적화 기준 |
routeInfo | Boolean |
전체 경로 정보 보기 사용 여부 |
startX | Int64 |
시작 위치의 경도 좌표 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정 |
startY | Int64 |
시작 위치의 위도 좌표 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정 |
startAngle | Int |
시작 차량 각도 0~359 사이의 값 비고: 경로 검색 시 참고 정보이며, 길 안내 출발지는 사용자 현재 위치로 고정 |
returnUri | URL |
길 안내의 전체 경로 보기 종료 시 호출될 URI |
NaviOption
의 모든 구성 요소는 선택적으로 지정 가능합니다. 하지만 중요한 구성 요소를 지정하지 않으면 카카오내비가 조건에 맞춰 장소와 길을 찾지 못하므로, 중요한 검색 조건들은 반드시 지정해야 합니다.
다음은 구성 요소별 클래스 정보입니다. Enum
클래스인 구성 요소는 지정된 값 중 하나만 사용할 수 있습니다.
Name | Description |
---|---|
WGS84 | World Geodetic System 84 좌표계 |
KATEC | Katec 좌표계 서버 기본값 |
Name | Description |
---|---|
1 | First, 1종 승용차/소형승합차/소형화물차 |
2 | Second, 2종 중형승합차/중형화물차 |
3 | Third, 3종 대형승합차/2축 대형화물차 |
4 | Fourth, 4종 3축 대형화물차 |
5 | Fifth. 5종 4축이상 특수화물차 |
6 | Sixth, 6종 경차 |
7 | TwoWheel, 이륜차 |
Name | Description |
---|---|
1 | Fast, 가장 빠른 경로(Fastest route) |
2 | Free, 무료 도로(Free route) |
3 | Shortest, 가장 짧은 경로(Shortest route) |
4 | NoAuto, 자동차 전용 도로 제외(Exclude motorway) |
5 | Wide, 큰길 우선(Wide road first) |
6 | Highway, 고속도로 우선(Highway first) |
8 | Normal, 일반 도로 우선(Normal road first) |
100 | Recommended, 추천 경로(Recommended route) 기본 값으로 사용 |
사전 설정 | 레퍼런스 |
---|---|
플랫폼 등록 | navigateUrl() |
길 안내는 사용자의 현재 위치로부터 지정한 목적지까지의 경로를 카카오내비로 안내하는 기능입니다. NaviApi
의 navigateUrl()
을 호출해 URL
을 반환 받아 열도록 구현합니다.
navigateUrl()
호출 시 목적지 정보를 담은 NaviLocation, 검색 조건을 담은 NaviOption 객체를 전달해야 합니다. NaviOption
에는 원하는 검색 조건만 지정하여 요청할 수 있습니다.
startX
, startY
, startAngle
파라미터를 사용해 경로 검색 시 참고할 출발 지점을 지정할 수 있습니다. 그러나 길 안내 시에는 사용자의 현재 위치로부터 목적지까지의 안내만을 제공하며, 별도의 출발 지점을 지정할 수는 없습니다.
경유지 목록 설정이 가능합니다. 각 경유지 정보를 NaviLocation
객체에 담고, 요청 시 viaList
파라미터로 경유지 NaviLocation
의 리스트(List)를 전달합니다.
다음은 길 안내 예제입니다.
let destination = NaviLocation(name: "카카오판교오피스", x: "321286", y: "533707")
let viaList = [NaviLocation(name: "판교역 1번출구", x: "321525", y: "532951")]
guard let navigateUrl = NaviApi.shared.navigateUrl(destination: destination, viaList: viaList) else {
return
}
if UIApplication.shared.canOpenURL(navigateUrl) {
UIApplication.shared.open(navigateUrl, options: [:], completionHandler: nil)
} else {
UIApplication.shared.open(NaviApi.webNaviInstallUrl, options: [:], completionHandler: nil)
}
다음은 카카오내비 실행 후 길 안내를 시작한 화면입니다.
iOS SDK 2.8.4부터 카카오내비 앱 미설치 시 웹에서 길 안내를 실행하는 기능을 더 이상 제공하지 않습니다. 카카오내비 앱이 설치돼 있지 않은 경우에는 설치 페이지로 이동합니다. 이전 버전에서 제공하는 웹 길 안내 기능 또한 추후 제공 종료될 예정이므로, 최신 버전 업데이트를 권장합니다.
사전 설정 | 레퍼런스 |
---|---|
플랫폼 등록 | shareUrl() |
목적지 공유하기는 카카오내비에서 지정한 목적지 정보를 공유할 수 있는 화면을 보여주는 기능입니다. NaviApi
의 shareUrl()
을 호출해 URL
을 반환 받아 열도록 구현합니다.
shareUrl()
호출 시 목적지 정보를 담은 NaviLocation, 검색 조건을 담은 NaviOption 객체를 전달해야 합니다. NaviOption
에는 원하는 검색 조건만 지정하여 요청할 수 있습니다.
startX
, startY
, startAngle
파라미터를 사용해 경로 검색 시 참고할 출발 지점을 지정할 수 있습니다. 그러나 길 안내 시에는 사용자의 현재 위치로부터 목적지까지의 안내만을 제공하며, 별도의 출발 지점을 지정할 수는 없습니다.
경유지 목록 설정이 가능합니다. 각 경유지 정보를 NaviLocation
객체에 담고, 요청 시 viaList
파라미터로 경유지 NaviLocation
의 리스트(List)를 전달합니다.
let destination = NaviLocation(name: "카카오판교오피스", x: "321286", y: "533707")
guard let shareUrl = NaviApi.shared.shareUrl(destination: destination) else {
return
}
if UIApplication.shared.canOpenURL(shareUrl) {
UIApplication.shared.open(shareUrl, options: [:], completionHandler: nil)
}
else {
UIApplication.shared.open(NaviApi.webNaviInstallUrl, options: [:], completionHandler: nil)
}
다음은 카카오내비에서 목적지 공유하기를 실행한 화면입니다.
카카오내비의 Legacy Kakao SDK for iOS(이하 Legacy iOS SDK) 개발 가이드는 아래 바로가기에서 확인할 수 있습니다. 추후 Legacy iOS SDK에 대한 지원이 중단될 수 있으므로, 가급적 빠른 시일 내에 최신 버전 iOS SDK로 변경할 것을 권장합니다.