카카오모빌리티 디벨로퍼스 문서 카카오내비 길찾기 SDK with UI 주행 설정하기

주행 전 설정하기 링크 복사

출발지, 경유지 및 목적지 설정과 차량 정보, 원하는 경로 옵션 등 주행 전에 필요한 정보를 설정합니다.

1. 출발지 및 목적지 설정하기 링크 복사

출발지와 목적지를 설정하여 주행 경로를 생성합니다. Android 길찾기 UI SDK는 카텍(KATEC) 좌표계를 사용하여 위도와 경도를 표시합니다.

주소 값은 선택 사항이며 위도/경도 값과 주소 값이 다를 경우 위도/경도 값을 우선으로 안내합니다.

// 출발지 설정    
val start = KNPOI({name}, {longitude}, {latitude}, {address})

// 목적지 설정
val goal = KNPOI({name}, {longitude}, {latitude}, {address})

// 경로 생성
val trip = KNSDK.makeTripWithStart(start, goal, {wayPoints : MutableList<KNPOI>?})

// 출발지 설정    
val start = KNPOI({name}, {longitude}, {latitude}, {address})

// 목적지 설정
val goal = KNPOI({name}, {longitude}, {latitude}, {address})

// 경로 생성
val trip = KNSDK.makeTripWithStart(start, goal, {wayPoints : MutableList<KNPOI>?})
코드가 숨겨졌습니다.

2. 상세 정보 설정하기 링크 복사

보다 정확한 길 안내를 위해 차량의 종류, 하이패스 장착 여부, 교통사고 또는 공사 등으로 인한 도로 통행 제한 정보(이하 유고 정보) 반영 여부 등을 설정합니다.

// 차량 정보 및 유고 정보 반영 여부 설정
val routeConfig = KNRouteConfiguration(
  {KNCarType},    // 차량의 종류
  {KNCarUsage}    // 차량의 용도
  {Boolean},      // 하이패스 장착 여부
  {Boolean},      // 유고 정보 반영 여부
  {Int},          // 차량의 전폭
  {Int},          // 차량의 전고
  {Int},          // 차량의 전장
  {Int})          // 차량의 중량
trip?.routeConfig = routeConfig

// 차량 정보 및 유고 정보 반영 여부 설정
val routeConfig = KNRouteConfiguration(
  {KNCarType},    // 차량의 종류
  {KNCarUsage}    // 차량의 용도
  {Boolean},      // 하이패스 장착 여부
  {Boolean},      // 유고 정보 반영 여부
  {Int},          // 차량의 전폭
  {Int},          // 차량의 전고
  {Int},          // 차량의 전장
  {Int})          // 차량의 중량
trip?.routeConfig = routeConfig
코드가 숨겨졌습니다.

3. 경로 옵션 설정하기 링크 복사

경로 안내 시 우선적으로 고려하는 항목(KNRoutePriority)과 경로 안내에서 회피하고 싶은 구간(KNRouteAvoidOption)을 선택합니다.

// 경로 옵션 설정
val curRoutePriority = {KNRoutePriority}    // 경로 안내에서 우선적 고려 항목
val curAvoidOptions = {KNRouteAvoidOption}  // 경로 회피 구간

// 경로 옵션 설정
val curRoutePriority = {KNRoutePriority}    // 경로 안내에서 우선적 고려 항목
val curAvoidOptions = {KNRouteAvoidOption}  // 경로 회피 구간
코드가 숨겨졌습니다.

예를 들어, 추천 경로로 경로를 안내하되 유고 정보 구간과 교통 약자 보호 구역을 경로에서 회피하고 싶다면, 아래와 같이 value값을 할당하면 됩니다.

// 경로 옵션 설정
curRoutePriority = KNRoutePriority.KNRoutePriority_Recommand.value
curAvoidOptions = KNRouteAvoidOption.KNRouteAvoidOption_RoadEvent.value or KNRouteAvoidOption.KNRouteAvoidOption_SZone.value

// 경로 옵션 설정
curRoutePriority = KNRoutePriority.KNRoutePriority_Recommand.value
curAvoidOptions = KNRouteAvoidOption.KNRouteAvoidOption_RoadEvent.value or KNRouteAvoidOption.KNRouteAvoidOption_SZone.value
코드가 숨겨졌습니다.

길 안내하기 링크 복사

선택한 옵션들을 바탕으로 경로를 요청하고 요청 성공 시 길 안내를 시작합니다.

경로 요청 시 사용자가 직접 델리게이트 값을 입력하여 자신의 서비스에 맞게 맞춤 설정할 수 있습니다. 입력한 델리게이트 값은 naviView로 전달해야 합니다.

// 경로 요청
trip.routeWithPriority(curRoutePriority, curAvoidOptions) { error, _ ->
  if (error != null) {
    handleError(trip, aError)
    // 경로 요청 실패
  } else {
    // 경로 요청 성공
    GlobalApplication.knsdk.sharedGuidance()?.apply {
      // 각 가이던스 델리게이트 등록
      guideStateDelegate = this@KNNaviActivity
      locationGuideDelegate = this@KNNaviActivity
      routeGuideDelegate = this@KNNaviActivity
      safetyGuideDelegate = this@KNNaviActivity
      voiceGuideDelegate = this@KNNaviActivity
      citsGuideDelegate = this@KNNaviActivity

      naviView.initWithGuidance(
        this,
        trip,
        curRoutePriority,
        curAvoidOptions
      )
    }
  }
}

// 경로 요청
trip.routeWithPriority(curRoutePriority, curAvoidOptions) { error, _ ->
  if (error != null) {
    handleError(trip, aError)
    // 경로 요청 실패
  } else {
    // 경로 요청 성공
    GlobalApplication.knsdk.sharedGuidance()?.apply {
      // 각 가이던스 델리게이트 등록
      guideStateDelegate = this@KNNaviActivity
      locationGuideDelegate = this@KNNaviActivity
      routeGuideDelegate = this@KNNaviActivity
      safetyGuideDelegate = this@KNNaviActivity
      voiceGuideDelegate = this@KNNaviActivity
      citsGuideDelegate = this@KNNaviActivity

      naviView.initWithGuidance(
        this,
        trip,
        curRoutePriority,
        curAvoidOptions
      )
    }
  }
}
코드가 숨겨졌습니다.

아래의 델리게이트 정보를 참고하여 naviView와 연동하세요.

정보를 입력한 각각의 델리게이트를 naviView와 연동하지 않을 시 주행 화면이 정상적으로 표시되지 않습니다. 반드시 연동하여 사용하세요.

// KNGuidance_GuideStateDelegate

// 길 안내 시작 시 호출
override fun guidanceGuideStarted(guidance: KNGuidance) {
    naviView.guidanceGuideStarted(guidance)
}

// 경로 변경 시 호출. 교통 변화 또는 경로 이탈로 인한 재탐색 및 사용자 재탐색 시 전달 
override fun guidanceCheckingRouteChange(guidance: KNGuidance) {
    naviView.guidanceCheckingRouteChange(guidance)
}

// 수신 받은 새 경로가 기존의 안내된 경로와 동일할 경우 호출
override fun guidanceRouteUnchanged(guidance: KNGuidance) {
    naviView.guidanceRouteUnchanged(guidance)
}

// 경로에 오류가 발생 시 호출
override fun guidanceRouteUnchangedWithError(guidnace: KNGuidance, error: KNError) {
    naviView.guidanceRouteUnchangedWithError(guidnace, error)
}

// 경로에서 이탈한 뒤 새로운 경로를 요청할 때 호출
override fun guidanceOutOfRoute(guidance: KNGuidance) {
    naviView.guidanceOutOfRoute(guidance)
}

// 수신 받은 새 경로가 기존의 안내된 경로와 다를 경우 호출. 여러 개의 경로가 있을 경우 첫 번째 경로를 주행 경로로 사용하고 나머지는 대안 경로로 설정됨
override fun guidanceRouteChanged(guidance: KNGuidance) {
    naviView.guidanceRouteChanged(guidance)
}

// 길 안내 종료 시 호출
override fun guidanceGuideEnded(guidance: KNGuidance) {
    naviView.guidanceGuideEnded(guidance)
}

// 주행 중 기타 요인들로 인해 경로가 변경되었을 때 호출
override fun guidanceDidUpdateRoutes(guidance: KNGuidance, routes: List<KNRoute>, multiRouteInfo: KNMultiRouteInfo?) {
    naviView.guidanceDidUpdateRoutes(guidance, routes, multiRouteInfo)
}


// KNGuidance_LocationGuideDelegate

// 위치 정보가 변경될 경우 호출. `locationGuide`의 항목이 1개 이상 변경 시 전달됨.
override fun guidanceDidUpdateLocation(guidance: KNGuidance, locationGuide: KNGuide_Location) {
    naviView.guidanceDidUpdateLocation(guidance, locationGuide)
}


// KNGuidance_RouteGuideDelegate

// 경로 안내 정보 업데이트 시 호출. `routeGuide`의 항목이 1개 이상 변경 시 전달됨.
override fun guidanceDidUpdateRouteGuide(guidance: KNGuidance, routeGuide: KNGuide_Route) {
    naviView.guidanceDidUpdateRouteGuide(guidance, routeGuide)
}


// KNGuidance_SafetyGuideDelegate

// 안전 운행 정보 업데이트 시 호출. `safetyGuide`의 항목이 1개 이상 변경 시 전달됨.
override fun guidanceDidUpdateSafetyGuide(guidance: KNGuidance, safetyGuide: KNGuide_Safety?) {
    naviView.guidanceDidUpdateSafetyGuide(guidance, safetyGuide)
}

// 주변의 안전 운행 정보 업데이트 시 호출
override fun guidanceDidUpdateAroundSafeties(guidance: KNGuidance, safeties: List<KNSafety>?) {
    naviView.guidanceDidUpdateAroundSafeties(guidance, safeties)
}


// KNGuidance_VoiceGuideDelegate

// 음성 안내 사용 여부
override fun shouldPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice, newData: MutableList<ByteArray>): Boolean {
    return naviView.shouldPlayVoiceGuide(guidance, voiceGuide, newData)
}

// 음성 안내 시작
override fun willPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice) {
    naviView.willPlayVoiceGuide(guidance, voiceGuide)
}

// 음성 안내 종료
override fun didFinishPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice) {
    naviView.didFinishPlayVoiceGuide(guidance, voiceGuide)
}


// KNGuidance_CitsGuideDelegate

// CITS 정보 변경 시 호출
override fun didUpdateCitsGuide(guidance: KNGuidance, citsGuide: KNGuide_Cits) {
    naviView.didUpdateCitsGuide(guidance, citsGuide)
}


// KNGuidance_GuideStateDelegate

// 길 안내 시작 시 호출
override fun guidanceGuideStarted(guidance: KNGuidance) {
    naviView.guidanceGuideStarted(guidance)
}

// 경로 변경 시 호출. 교통 변화 또는 경로 이탈로 인한 재탐색 및 사용자 재탐색 시 전달 
override fun guidanceCheckingRouteChange(guidance: KNGuidance) {
    naviView.guidanceCheckingRouteChange(guidance)
}

// 수신 받은 새 경로가 기존의 안내된 경로와 동일할 경우 호출
override fun guidanceRouteUnchanged(guidance: KNGuidance) {
    naviView.guidanceRouteUnchanged(guidance)
}

// 경로에 오류가 발생 시 호출
override fun guidanceRouteUnchangedWithError(guidnace: KNGuidance, error: KNError) {
    naviView.guidanceRouteUnchangedWithError(guidnace, error)
}

// 경로에서 이탈한 뒤 새로운 경로를 요청할 때 호출
override fun guidanceOutOfRoute(guidance: KNGuidance) {
    naviView.guidanceOutOfRoute(guidance)
}

// 수신 받은 새 경로가 기존의 안내된 경로와 다를 경우 호출. 여러 개의 경로가 있을 경우 첫 번째 경로를 주행 경로로 사용하고 나머지는 대안 경로로 설정됨
override fun guidanceRouteChanged(guidance: KNGuidance) {
    naviView.guidanceRouteChanged(guidance)
}

// 길 안내 종료 시 호출
override fun guidanceGuideEnded(guidance: KNGuidance) {
    naviView.guidanceGuideEnded(guidance)
}

// 주행 중 기타 요인들로 인해 경로가 변경되었을 때 호출
override fun guidanceDidUpdateRoutes(guidance: KNGuidance, routes: List<KNRoute>, multiRouteInfo: KNMultiRouteInfo?) {
    naviView.guidanceDidUpdateRoutes(guidance, routes, multiRouteInfo)
}


// KNGuidance_LocationGuideDelegate

// 위치 정보가 변경될 경우 호출. `locationGuide`의 항목이 1개 이상 변경 시 전달됨.
override fun guidanceDidUpdateLocation(guidance: KNGuidance, locationGuide: KNGuide_Location) {
    naviView.guidanceDidUpdateLocation(guidance, locationGuide)
}


// KNGuidance_RouteGuideDelegate

// 경로 안내 정보 업데이트 시 호출. `routeGuide`의 항목이 1개 이상 변경 시 전달됨.
override fun guidanceDidUpdateRouteGuide(guidance: KNGuidance, routeGuide: KNGuide_Route) {
    naviView.guidanceDidUpdateRouteGuide(guidance, routeGuide)
}


// KNGuidance_SafetyGuideDelegate

// 안전 운행 정보 업데이트 시 호출. `safetyGuide`의 항목이 1개 이상 변경 시 전달됨.
override fun guidanceDidUpdateSafetyGuide(guidance: KNGuidance, safetyGuide: KNGuide_Safety?) {
    naviView.guidanceDidUpdateSafetyGuide(guidance, safetyGuide)
}

// 주변의 안전 운행 정보 업데이트 시 호출
override fun guidanceDidUpdateAroundSafeties(guidance: KNGuidance, safeties: List<KNSafety>?) {
    naviView.guidanceDidUpdateAroundSafeties(guidance, safeties)
}


// KNGuidance_VoiceGuideDelegate

// 음성 안내 사용 여부
override fun shouldPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice, newData: MutableList<ByteArray>): Boolean {
    return naviView.shouldPlayVoiceGuide(guidance, voiceGuide, newData)
}

// 음성 안내 시작
override fun willPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice) {
    naviView.willPlayVoiceGuide(guidance, voiceGuide)
}

// 음성 안내 종료
override fun didFinishPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice) {
    naviView.didFinishPlayVoiceGuide(guidance, voiceGuide)
}


// KNGuidance_CitsGuideDelegate

// CITS 정보 변경 시 호출
override fun didUpdateCitsGuide(guidance: KNGuidance, citsGuide: KNGuide_Cits) {
    naviView.didUpdateCitsGuide(guidance, citsGuide)
}
코드가 숨겨졌습니다.

길 안내 종료하기 링크 복사

목적지까지의 주행이 완료되면 naviViewGuideEnded()를 통해 주행 종료에 대한 콜백을 전달합니다.

KNNaviView.guideStateDelegate = this

KNNaviView.guideStateDelegate = this
코드가 숨겨졌습니다.