Implementing Route Guidance

Configuring settings before driving

Set the information required for driving, including the origin, waypoints, and destination, as well as vehicle information and preferred route options.

1. Setting the origin and destination

Set the origin and destination to create a driving route. The Directions SDK with UI expresses latitude and longitude using the KATEC coordinate system.

TIP

The address value is optional. If the address value differs from the latitude/longitude values, guidance is based on the latitude/longitude values.

// Set the origin
val start = KNPOI({name}, {longitude}, {latitude}, {address})

// Set the destination
val goal = KNPOI({name}, {longitude}, {latitude}, {address})

// Create a route
val trip = KNSDK.makeTripWithStart(start, goal, {wayPoints : MutableList<KNPOI>?})

2. Setting detailed information

For accurate route guidance, set the vehicle type, whether a Hi-pass device is installed, and road restriction information caused by traffic accidents or construction (traffic incident information).

// Set the vehicle information and whether to reflect traffic incident information
val routeConfig = KNRouteConfiguration(
  {KNCarType},    // Vehicle type
  {KNCarUsage},   // Vehicle usage
  {Boolean},      // Whether a Hi-pass device is installed
  {Boolean},      // Whether to reflect traffic incident information
  {Int},          // Overall width of the vehicle
  {Int},          // Overall height of the vehicle
  {Int},          // Overall length of the vehicle
  {Int})          // Weight of the vehicle
trip?.routeConfig = routeConfig

3. Setting route options

Select the item to prioritize during route guidance (KNRoutePriority) and the sections to avoid in the route guidance (KNRouteAvoidOption).

// Set route options
val curRoutePriority = {KNRoutePriority}    // Item to prioritize in route guidance
val curAvoidOptions = {KNRouteAvoidOption}  // Sections to avoid in the route

For example, if you want to guide the route as a recommended route while avoiding traffic incident sections and protected zones, assign the value as shown below.

// Set route options
curRoutePriority = KNRoutePriority.KNRoutePriority_Recommand.value
curAvoidOptions = KNRouteAvoidOption.KNRouteAvoidOption_RoadEvent.value or KNRouteAvoidOption.KNRouteAvoidOption_SZone.value

Starting route guidance

Create a KNTrip using KNSDK.makeTripWithStart.

/**
 * Creates a KNTrip.
 * @param aStart Origin
 * @param aGoal Destination
 * @param aVias List of waypoints
 * @param aCsId CS response identifier, currently not used
 * @param aCompletion Trip delivery block
 * @see KNPOI
 */
fun makeTripWithStart(
    aStart: KNPOI,
    aGoal: KNPOI,
    aVias: MutableList<KNPOI>?,
    aCsId: String? = null,
    aCompletion: ((aError: KNError?, aTrip: KNTrip?) -> Unit)
)

ex) 
KNSDK.makeTripWithStart(
    aStart = start,
    aGoal = aDestination,
    aVias = null
) { aError, aTrip ->
    if (aError == null) {
        // The created KNTrip
        val trip = aTrip

    } else {
        // Route request failed
    }
}

Use the created KNTrip to request a route with the selected options, and once the request succeeds, start route guidance.

When requesting a route, you can set delegate values directly to customize the service to your needs. These delegate values must be passed to naviView.

// Request a route
trip.routeWithPriority(curRoutePriority, curAvoidOptions) { error, _ ->
  if (error != null) {
    // Route request failed
  } else {
    // Route request succeeded
    GlobalApplication.knsdk.sharedGuidance()?.apply {
      // Register each guidance delegate
      guideStateDelegate = this@KNNaviActivity
      locationGuideDelegate = this@KNNaviActivity
      routeGuideDelegate = this@KNNaviActivity
      safetyGuideDelegate = this@KNNaviActivity
      voiceGuideDelegate = this@KNNaviActivity
      citsGuideDelegate = this@KNNaviActivity

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

Use the delegates below to integrate with naviView.

DANGER

If you do not integrate each delegate you have set up with naviView, the driving screen will not display correctly. Be sure to integrate them before use.

// KNGuidance_GuideStateDelegate

// Called when route guidance starts
override fun guidanceGuideStarted(guidance: KNGuidance) {
    naviView.guidanceGuideStarted(guidance)
}

// Called when the route changes. Delivered on rerouting due to traffic changes or route deviation, and on user-initiated rerouting
override fun guidanceCheckingRouteChange(guidance: KNGuidance) {
    naviView.guidanceCheckingRouteChange(guidance)
}

// Called when the newly received route is identical to the previously guided route
override fun guidanceRouteUnchanged(guidance: KNGuidance) {
    naviView.guidanceRouteUnchanged(guidance)
}

// Called when an error occurs in the route
override fun guidanceRouteUnchangedWithError(guidnace: KNGuidance, error: KNError) {
    naviView.guidanceRouteUnchangedWithError(guidnace, error)
}

// Called when requesting a new route after deviating from the route
override fun guidanceOutOfRoute(guidance: KNGuidance) {
    naviView.guidanceOutOfRoute(guidance)
}

// Called when the newly received route differs from the previously guided route. When there are multiple routes, the first route is used as the driving route and the rest are set as alternative routes
override fun guidanceRouteChanged(guidance: KNGuidance) {
    naviView.guidanceRouteChanged(guidance)
}

// Called when route guidance ends
override fun guidanceGuideEnded(guidance: KNGuidance) {
    naviView.guidanceGuideEnded(guidance)
}

// Called when the route changes due to other factors while driving
override fun guidanceDidUpdateRoutes(guidance: KNGuidance, routes: List<KNRoute>, multiRouteInfo: KNMultiRouteInfo?) {
    naviView.guidanceDidUpdateRoutes(guidance, routes, multiRouteInfo)
}


// KNGuidance_LocationGuideDelegate

// Called when the location information changes. Delivered when one or more items of `locationGuide` change.
override fun guidanceDidUpdateLocation(guidance: KNGuidance, locationGuide: KNGuide_Location) {
    naviView.guidanceDidUpdateLocation(guidance, locationGuide)
}


// KNGuidance_RouteGuideDelegate

// Called when the route guidance information is updated. Delivered when one or more items of `routeGuide` change.
override fun guidanceDidUpdateRouteGuide(guidance: KNGuidance, routeGuide: KNGuide_Route) {
    naviView.guidanceDidUpdateRouteGuide(guidance, routeGuide)
}


// KNGuidance_SafetyGuideDelegate

// Called when the safe driving information is updated. Delivered when one or more items of `safetyGuide` change.
override fun guidanceDidUpdateSafetyGuide(guidance: KNGuidance, safetyGuide: KNGuide_Safety?) {
    naviView.guidanceDidUpdateSafetyGuide(guidance, safetyGuide)
}

// Called when the surrounding safe driving information is updated
override fun guidanceDidUpdateAroundSafeties(guidance: KNGuidance, safeties: List<KNSafety>?) {
    naviView.guidanceDidUpdateAroundSafeties(guidance, safeties)
}


// KNGuidance_VoiceGuideDelegate

// Whether to use voice guidance
override fun shouldPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice, newData: MutableList<ByteArray>): Boolean {
    return naviView.shouldPlayVoiceGuide(guidance, voiceGuide, newData)
}

// Voice guidance starts
override fun willPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice) {
    naviView.willPlayVoiceGuide(guidance, voiceGuide)
}

// Voice guidance ends
override fun didFinishPlayVoiceGuide(guidance: KNGuidance, voiceGuide: KNGuide_Voice) {
    naviView.didFinishPlayVoiceGuide(guidance, voiceGuide)
}


// KNGuidance_CitsGuideDelegate

// Called when the C-ITS information changes
override fun didUpdateCitsGuide(guidance: KNGuidance, citsGuide: KNGuide_Cits) {
    naviView.didUpdateCitsGuide(guidance, citsGuide)
}

Ending route guidance

When driving to the destination is complete, naviViewGuideEnded() delivers a callback for the end of driving.

KNNaviView.guideStateDelegate = this