Configuring settings before driving

Set the information required before 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 for iOS expresses latitude and longitude using the KATEC coordinate system. When requesting a route, you can add settings to customize the request.

If you create a KNRouteConfiguration and assign it to the KNTrip, the route is requested based on that information. You can configure the following items.

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
KNPOI *start = [[KNPOI alloc] initWithName:name x:longitude y:latitude address:address];
// Set the destination
KNPOI *goal = [[KNPOI alloc] initWithName:name x:longitude y:latitude address:address];
// Create a route
KNTrip *trip = [KNSDK.sharedInstance makeTripWithStart:start goal:goal vias:vias];

2. Creating a route

Create a route to the destination through the makeTripWithStart function of KNSDK.

[[KNSDK sharedInstance] makeTripWithStart:start goal:goal vias:vias completion:^(KNError * aError, KNTrip * aTrip) {
    if(aError)
    {
        // Failed to create the route
    }
    else
    {
        // Route created successfully
    }
}];

3. Setting detailed information

For more accurate route guidance, set the vehicle type, whether a Hi-pass device is installed, and whether to apply road restriction information caused by traffic accidents or construction (hereafter, traffic incident information). You can set the detailed information through the KNRouteConfiguration class.

KNRouteConfiguration *routeConfig = [[KNRouteConfiguration alloc] initWithCarType:carType usage:usage useHipass:useHipass ignoreTrafficControl:ignoreTrafficControl];
[trip setRouteConfig:routeConfig];

4. Setting route options

Select the route you want from the various route options available to the destination. You can set the route option through the KNRoutePriority (KO) enumeration. Choose one of its values.

// Set route options
KNRoutePriority routePriority = routePriority;

5. Setting route avoidance options

Select the sections you want to avoid on the way to the destination. You can set the avoidance options through the KNRouteAvoidOption (KO) enumeration. Its values are bit flags (0x0001, 0x0002, 0x0004, …), so you can combine more than one with the bitwise OR operator.

// Set route options
KNRouteAvoidOption routeAvoidOption = routeAvoidOption;

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

// Recommended route guidance, avoiding traffic incident sections and protected zones for vulnerable road users
routePriority = KNRoutePriority_Recommand;
routeAvoidOption = KNRouteAvoidOption_RoadEvent | KNRouteAvoidOption_SZone;

Starting route guidance

Based on the selected options, request a route through the routeWithPriority function, 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
[aTrip routeWithPriority:routePriority avoidOptions:routeAvoidOption completion:^(KNError * _Nullable aError, NSArray<KNRoute *> * _Nullable aRoutes) {
	if(aError)
	{
	// Route request failed
	}
	else
	{ 
	// Route request succeeded
	KNGuidance *guidance = [[KNSDK  sharedInstance] sharedGuidance];

	// Register each guidance delegate
	guidance.guideStateDelegate = self;
	guidance.routeGuideDelegate = self;
	guidance.voiceGuideDelegate = self;
	guidance.safetyGuideDelegate = self;
	guidance.locationGuideDelegate = self;
	guidance.citsGuideDelegate = self;
		
	// Create the driving UI
	KNNaviView *naviView = [[KNNaviView alloc] initWithGuidance:guidance trip:nil routeOption:routePriority avoidOption:routeAvoidOption];
	naviView.frame = self.bounds;
	naviView.guideStateDelegate = self;
	naviView.stateDelegate = self;
	[naviView sndVolume:volume];
	[self addSubview:naviView];
	}
}];

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
- (void)guidanceGuideStarted:(KNGuidance *)aGuidance {
    [naviView guidanceGuideStarted:aGuidance];
}
 
// Called when the route changes. Delivered on rerouting due to traffic changes or route deviation, and on user-initiated rerouting
- (void)guidanceCheckingRouteChange:(KNGuidance *)aGuidance {
    [naviView guidanceCheckingRouteChange:aGuidance];
}
 
// Called when requesting a new route after deviating from the route
- (void)guidanceOutOfRoute:(KNGuidance *)aGuidance {
    [naviView guidanceOutOfRoute:aGuidance];
}
 
// Called when the newly received route is identical to the previously guided route
- (void)guidanceRouteUnchanged:(KNGuidance *)aGuidance {
    [naviView guidanceRouteUnchanged:aGuidance];   
}
 
// Called when an error occurs in the route
- (void)guidance:(KNGuidance *)aGuidance routeUnchangedWithError:(KNError *)aError {
    [naviView guidance:aGuidance routeUnchangedWithError:aError];
}
 
// 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
- (void)guidanceRouteChanged:(KNGuidance *)aGuidance {
    [naviView guidanceRouteChanged:aGuidance];
}
 
// Called when route guidance ends
- (void)guidanceGuideEnded:(KNGuidance *)aGuidance {
    [naviView guidanceGuideEnded:aGuidance isShowDriveResultDialog:YES];
};
 
// Called when the route changes due to other factors while driving
- (void)guidance:(KNGuidance *)aGuidance didUpdateRoutes:(NSArray<KNRoute *> *)aRoutes multiRouteInfo:(KNMultiRouteInfo * _Nullable)aMultiRouteInfo {
    [naviView guidance:aGuidance didUpdateRoutes:aRoutes multiRouteInfo:aMultiRouteInfo];
}


// KNGuidance_LocationGuideDelegate

// Called when the location information changes. Delivered when one or more items of `aLocationGuide` change.
- (void)guidance:(KNGuidance * _Nonnull)aGuidance didUpdateLocation:(KNGuide_Location * _Nonnull)aLocationGuide {
    [naviView guidance:aGuidance didUpdateLocation:aLocationGuide];
}


// KNGuidance_RouteGuideDelegate
 
// Called when the route guidance information is updated. Delivered when one or more items of `aRouteGuide` change.
- (void)guidance:(KNGuidance * _Nonnull)aGuidance didUpdateRouteGuide:(KNGuide_Route * _Nonnull)aRouteGuide {
    [naviView guidance:aGuidance didUpdateRouteGuide:aRouteGuide];
}

// KNGuidance_SafetyGuideDelegate
 
// Called when the safe driving information is updated. Delivered when one or more items of `aSafetyGuide` change.
- (void)guidance:(KNGuidance * _Nonnull)aGuidance didUpdateSafetyGuide:(KNGuide_Safety * _Nonnull)aSafetyGuide {
    [naviView guidance:aGuidance didUpdateSafetyGuide:aSafetyGuide];
}
 
// Called when the surrounding safe driving information is updated
- (void)guidance:(KNGuidance * _Nonnull)aGuidance didUpdateAroundSafeties:(NSArray<__kindof KNSafety *> * _Nullable)aSafeties { 
    [naviView guidance:aGuidance didUpdateAroundSafeties:aSafeties];
}


// KNGuidance_VoiceGuideDelegate

// Whether to use voice guidance
- (BOOL)guidance:(KNGuidance * _Nonnull)aGuidance shouldPlayVoiceGuide:(KNGuide_Voice * _Nonnull)aVoiceGuide replaceSndData:(NSData **)aNewData{
    return [naviView guidance:aGuidance shouldPlayVoiceGuide:aVoiceGuide replaceSndData:aNewData];
}
 
// Voice guidance starts
- (void)guidance:(KNGuidance * _Nonnull)aGuidance willPlayVoiceGuide:(KNGuide_Voice * _Nonnull)aVoiceGuide {
    [naviView guidance:aGuidance willPlayVoiceGuide:aVoiceGuide];
}
 
// Voice guidance ends
- (void)guidance:(KNGuidance * _Nonnull)aGuidance didFinishPlayVoiceGuide:(KNGuide_Voice * _Nonnull)aVoiceGuide {
    [naviView guidance:aGuidance didFinishPlayVoiceGuide:aVoiceGuide];
}


// KNGuidance_CitsGuideDelegate
 
// Called when the C-ITS information changes
- (void)guidance:(KNGuidance * _Nonnull)aGuidance didUpdateCitsGuide:(KNGuide_Cits * _Nonnull)aCitsGuide {
    [naviView guidance:aGuidance didUpdateCitsGuide:aCitsGuide];   
}

Checking information along the route

You can check the information that arises on the requested route, such as turn sections (roundabouts and rotaries), protected zones, and traffic incident information.

[trip routeWithPriority:routePriority avoidOptions:routeAvoidOption completion:^(KNError * _Nullable aError, NSArray<KNRoute *> * _Nullable aRoutes) {
	if(aError)
	{
	// Route request failed
	}
	else
	{
	// Route request succeeded
	// List of major turn sections along the route
	NSArray<KNDirection > *mainDirectionList = [aRoute[0] mainDirectionList];				

	// List of protected zone sections along the route				
	NSArray<KNSafetyZone > *safetyZoneList = [aRoute[0] safetyZoneList];		

	// List of safe driving sections along the route				
	NSArray<KNSafety > *safetyList = [aRoute[0] safetyList];				

	// List of traffic incidents that occur along the route				
	NSArray<KNRoadEvent > *roadEventList = [aRoute[0] roadEventList];		

	// List of nearby information/services along the route. Currently only gas station information is provided				
	NSArray<KNAroundInfo > *aroundInfoList = [aRoute[0] aroundInfoList];
	}
}];

Checking protected zones along the route

You can check whether the requested route includes school zones, senior protection zones, disabled protection zones, and more.

Call containsSafetyZone to check whether a protected zone is included; the value is returned as a Bool.

[trip routeWithPriority:routePriority avoidOptions:routeAvoidOption completion:^(KNError * _Nullable aError, NSArray<KNRoute *> * _Nullable aRoutes) {
	if(aError)
	{
	// Route request failed
	}
	else
	{
	// Route request succeeded
	// School zone
	BOOL schoolZone = [aRoute[0].containsSafetyZone:KNSafetyZoneType_SchoolZone];
	// Senior protection zone
	BOOL silverZone = [aRoute[0].containsSafetyZone:KNSafetyZoneType_SilverZone];
	// Disabled protection zone
	BOOL handicappedZone = [aRoute[0].containsSafetyZone:KNSafetyZoneType_HandicappedZone];
	}
}];

Ending route guidance

When you end route guidance while guidance is running, or close the driving screen by tapping X during safe driving, the SDK sends a notification that route guidance has ended.

- (void)naviViewGuideEnded:(KNNaviView * _Nonnull)aNaviView;