Quick Start Guide for iOS NavKit SDK

Introduction

This document describes the features of the iPhone® Operating System (iOS) NavKit Software Development Kit (SDK) application and demonstrates the usage of the major Apple® iOS Programming Interfaces (APIs) on the map.

Prerequisites

  • The user must be familiar with the Mac® Operating System, Xcode® development environment, and Objective-C® programming language.

  • The Xcode (version 10 or above) must be installed.

Note
The iPhone Operating System (iOS) NavKit SDK supports Apple iOS Programming Interfaces (APIs) with a minimum version of 8.0 and above. This SDK targets iOS APIs with version 12.4.

About API Key

The API key is used to track API requests of the project for usage and billing. API key often acts as a unique identifier and a secret token for authentication. The API key can be requested by filling in details and submitting the form at https://locationstudio.zendesk.com/hc/en-us/requests/new?ticket_form_id=360001758513.

Quick Start Steps

The following steps will help you to start using the iOS NavKit SDK.

Getting the SDK

To obtain the iOS SDK, perform the following steps.

  1. Go to https://git.location.studio/location.studio/iOSSDK.

  2. Register or sign in to your existing Comtech Location Studio® Git account.

  3. If you created a new account, access it by clicking the Confirm your account button, sent to the registered email ID.

  4. On home page under the Project tab, click on the download icon drop-down to save the iOS SDK zip package to your local drive. As an alternative, you can clone the repository to your local system using the following command.

After you have downloaded and extracted the zip package or cloned the repository, follow the steps described in the next sections to begin using the SDK.

Getting Started

Follow the next sections to test a Navigation session in a sample iOS application.

Note
The following steps are targeted for Xcode with version 10.3. It may vary for other versions of the Xcode.

Project Setup

The following steps explain the project setup required to create a Navigation session using the iOS NavKit SDK.

  1. Start Xcode.

  2. Start a new Xcode project.

  1. Select Simple View App project and click Next as shown below.

SingleView
Figure 1. Selecting Single View App
  1. In the Choose options for your new project screen, enter your desired values for Product Name, Organization Name and all other fields as shown in the following screenshot.

Note
The SDK supports both Objective-C and Swift™ programming languages. For this sample project, we are selecting Objective-C in the Language dropdown.
Configuring_Nav
Figure 2. Configuring the Project
Note

Other types of available projects can also be selected during the project setup, but this tutorial uses Single View App project for easy understanding.

Dependency Setup

This section describes the dependency set up for iOS NavKit SDK APIs. The SDK contains the following two libraries:

  • locationToolKitCommon.framework

  • NavigationKit.framework

The following steps are performed to complete the dependency set up.

  1. Import the locationToolKitCommon.framework as described in the following steps.

    • From the File menu, select Add Files to NavSampleApp… and select Add as shown.

FileMenu_Nav
Figure 3. File Menu
  • Select LocationToolKitCommon.framework and click Add as shown in the following screenshot.

  • On the same screen, select the check box, Copy items if needed, highlighted on the bottom of the screen.

Select Navkit Framework
Figure 4. Selecting NavigationKit Framework
  1. Repeat the activities in Step 1 to import the NavigationKit.framework package.

  2. Locate NavigationKit.framework in the Frameworks folder as shown in the above screenshot.

  3. Drag the NavigationKit.bundle from the Resources folder to the Resources group in your project.

NavBundle
Figure 5. NavigationKit.bundle in the Resources Folder
  1. Under the Build Phases tab, select the drop-down, Link Binary With Libraries and add the frameworks listed below.

    • CoreTelephony.framework

    • libC++.1.tbd

    • libz.1.2.5.tbd

The frameworks to be added are highlighted in the following screenshot.

LinkBinary_Nav
Figure 6. Adding Frameworks

Adding Permissions to Info.plist File

The following step is performed to add Navigation to the ViewController.

Open ViewController.m and add the following code snippet before @interface ViewController ().

#import <LocationToolKitCommon/LTKContext.h>
#import <NavigationKit/LNKNavigation.h>

The following permissions must be declared inside the Info.plist file. These permissions are needed for network requests and for loading the navigation. You need to declare these permissions before using the NavKit classes.

<key>NSAppTransportSecurity</key> <dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
<key>NSLocationWhenInUseUsageDescription</key> <string>Used for the
map.</string>
<key>UIBackgroundModes</key> <array>
<string>location</string> </array>

The network and location permissions which must be enabled are highlighted in the following screenshot.

Permissions
Figure 7. Permissions in Info.plist File

Creating a Navigation Session

The following sections describe the process to create a Navigation session.

Creating the LTKContext Object

For using the Location ToolKit (LTK) services, you must create a LTKContext object, a singleton instance of services through which you can configure the API Key, language, country, and so on as shown in the following code snippet. To get started, this code snippet is added to the ViewControllers’s viewDidLoad() method.

LTKContext* ltkContext = [[LTKContext alloc]
init:@"PUT_YOUR_API_KEY_HERE"
language:@"en-US"
countryCode:@"US"
mdn:nil
productName: @"default"
pushMessageGUID:nil];

Replace “PUT_YOUR_API_KEY_HERE”, with the API key received from Comtech, in the above code snippet.

Creating the LNKRouteOptions Object

The class LNKRouteOptions specifies the various settings which control the generated route. It provides the route configurations like route type, transportation mode, avoid and so on.

The available options are:

  • Route type - Easiest/Fastest/Shortest

  • Transportation - Bicycle/Car/Pedestrian/Truck

  • Avoid - Highway/Toll/Hov/Ferry

Note
Avoid contains either one or a combination of any of the available options.

The following code snippet shows the route configurations set using the LNKRouteOptions class.

LNKRouteOptions* routeOptions = [[LNKRouteOptions alloc]init];
routeOptions.avoid = aVoid.value;
routeOptions.routeType = routeType.value;
routeOptions.transportationMode = vehicleType.value;
routeOptions.pronunciationStyle = @"";

Creating the Navigation Preferences

The LNKPreferences class provides various navigation configurations like guidance, announcements in phonetic format, traffic alerts, measurement units and so on.

The following code snippet shows the configurations set using this class.

LNKPreferences* preferences = [[LNKPreferences alloc]init];
preferences.speedThresholdForGpsHeading = [validGpsHeading.name doubleValue];
preferences.recalcCriteria = LDL_Tight;
preferences.positionUpdateRate = 10;
preferences.laneGuidanceEnabled = YES;
preferences.naturalGuidanceEnabled = YES;
preferences.offRouteIgnoreCount = offRouteSensitivity.value;
preferences.trafficAnnouncementEnabled = (trafficOption.value != 0);
preferences.useTraffic = trafficOption.value;
preferences.measurement = measurmentOption.value;
preferences.multipleRoutesEnabled = multipleRoute.value;
preferences.enhanceNavigationStartupEnabled = enhancedRoute.value;
preferences.enhanceNavigationStartupTimeout = enhancedRouteTimeout.value;
preferences.local = language.name;

Starting a Navigation Session

LNKNavigation class is the entry point of Navigation session. Creating a LNKNavigation instance creates a Navigation session. To create a Navigation session, you need to provide LTKContext, destination place, route options, and navigation preferences as shown in the following code snippet.

// Create a sample destination location
LTKPlace* destination =  [[LTKPlace alloc] init];
destination.latitude = 40.654757;
destination.longitude = -117.77774;


// Get navigation session
LNKNavigation*navigation = [LNKNavigation getNavigation : ltkContext destination : destination routeOptions : routeOptions preferences : preference ];

Navigation Delegates

iOS NavKit SDK provides various Navigation Delegates to track navigaton events. Following list has major Navigation Delegates.

  • LNKSessionDelegate: Has various methods to notify route received, route error, route progress, offroute and so on.

  • LNKNavigationUpdateDelegate: Notifies the events like remaining trip distance, remaining distance, and next maneuver.

  • LNKTrafficDelegate: Notifies the events during traffic, like traffic alerts.

  • LNKAnnouncementDelegate: Notifies the next announcement events.

[navigation addSessionDelegate:self];
[navigation addNavigationUpdateDelegate:self];
[navigation addAnnouncementDelegate:self];


#pragma - LNKSessionDelegate
/*! Informs the client that new route requested

 @param reason why new route is requested.
 */
- (void) routeRequested : (LNKRouteRequestReason) reason
{
    NSLog(@"Route Requested........");
}

/*! Provides the route generation progress
 */
- (void) routeProgress : (NSUInteger) progress
{
    NSLog(@"Route Progress……..”);
}
/*! Indicates that an error happened and this navigation session is no longer valid.

 Need to recreate a new one to continue the navigation session.
 */
- (void) routeError : (LNKNavigateRouteError) error
{
    NSString* errorMessage = nil;
    BOOL needToStopNav = YES;
    switch (error) {
        case LRE_TimedOut:
            NSLog(@“Route timed out error”);
            break;
        case LRE_BadDestination:
           NSLog(@"Routing destination is not near a routable road”);
            break;
        case LRE_BadOrigin:
          NSLog(@"Origin no near a routable road”);
            break;
        case LRE_CannotRoute:
            NSLog(@"No route can be found between the origin and the destination”);
            break;
        case LRE_EmptyRoute:
            NSLog(@"Empty route”);
            break;
        case LRE_NetError:
            NSLog(@"We are having trouble communicating with its servers. Please try again.”);
            break;
        case LRE_NoMatch:
           NSLog(@Route not match”);
            break;
        case LRE_NoDetour:
            NSLog(@"No route detour”);
            break;
        case LRE_PedRouteTooLong:
            NSLog(@"Pedestrian route is too long. Please choose a closer destination.”);
            break;
        case LRE_OriginCountryUnsuppoted:
            NSLog(@“Origin Country Unsupported”);
            break;
        case LRE_DestinationCountryUnsupported:
            NSLog(@"Destination Country unsupported”);
            break;
        default:
            NSLog(@"UnknownError error”);
            break;
    }

}
/*! Informs the client that current navigation session ends. The client will not
 receive any route updates.

 This navigation session needs to be stopped by the client.
 */
- (void) routeFinished
{
    NSLog(@“Route Finished”);

}

To know more about delegates, see the NavKit iOS API Reference Guide.

Updating the Location

To update a Navigation location, you need to send each LTKLocation update to the created Navigation instance as shown in the following code snippet.

-(void) locationUpdated : (LTKLocation*) location
{
    [navigation updatePosition:location];
}

Building and Running the NavSample App

Using the preceding code snippets in Getting Started, you can test the initialization and creation of the navigation session in the sample app. On building and running the sample app, you can see the navigation session creation logs in the Console as shown in the following screenshot.

NavSession_Logs
Figure 8. Navigation Session Logs

Quick Start Guide for iOS NavKit SDK

Introduction

This document describes the features of the iPhone® Operating System (iOS) NavKit Software Development Kit (SDK) application and demonstrates the usage of the major Apple® iOS Programming Interfaces (APIs) on the map.

Prerequisites

  • The user must be familiar with the Mac® Operating System, Xcode® development environment, and Objective-C® programming language.

  • The Xcode (version 10 or above) must be installed.

Note
The iPhone Operating System (iOS) NavKit SDK supports Apple iOS Programming Interfaces (APIs) with a minimum version of 8.0 and above. This SDK targets iOS APIs with version 12.4.

About API Key

The API key is used to track API requests of the project for usage and billing. API key often acts as a unique identifier and a secret token for authentication. The API key can be requested by filling in details and submitting the form at https://locationstudio.zendesk.com/hc/en-us/requests/new?ticket_form_id=360001758513.

Quick Start Steps

The following steps will help you to start using the iOS NavKit SDK.

Getting the SDK

To obtain the iOS SDK, perform the following steps.

  1. Go to https://git.location.studio/location.studio/iOSSDK.

  2. Register or sign in to your existing Comtech Location Studio® Git account.

  3. If you created a new account, access it by clicking the Confirm your account button, sent to the registered email ID.

  4. On home page under the Project tab, click on the download icon drop-down to save the iOS SDK zip package to your local drive. As an alternative, you can clone the repository to your local system using the following command.

After you have downloaded and extracted the zip package or cloned the repository, follow the steps described in the next sections to begin using the SDK.

Getting Started

Follow the next sections to test a Navigation session in a sample iOS application.

Note
The following steps are targeted for Xcode with version 10.3. It may vary for other versions of the Xcode.

Project Setup

The following steps explain the project setup required to create a Navigation session using the iOS NavKit SDK.

  1. Start Xcode.

  2. Start a new Xcode project.

  1. Select Simple View App project and click Next as shown below.

SingleView
Figure 1. Selecting Single View App
  1. In the Choose options for your new project screen, enter your desired values for Product Name, Organization Name and all other fields as shown in the following screenshot.

Note
The SDK supports both Objective-C and Swift™ programming languages. For this sample project, we are selecting Objective-C in the Language dropdown.
Configuring_Nav
Figure 2. Configuring the Project
Note

Other types of available projects can also be selected during the project setup, but this tutorial uses Single View App project for easy understanding.

Dependency Setup

This section describes the dependency set up for iOS NavKit SDK APIs. The SDK contains the following two libraries:

  • locationToolKitCommon.framework

  • NavigationKit.framework

The following steps are performed to complete the dependency set up.

  1. Import the locationToolKitCommon.framework as described in the following steps.

    • From the File menu, select Add Files to NavSampleApp… and select Add as shown.

FileMenu_Nav
Figure 3. File Menu
  • Select LocationToolKitCommon.framework and click Add as shown in the following screenshot.

  • On the same screen, select the check box, Copy items if needed, highlighted on the bottom of the screen.

Select Navkit Framework
Figure 4. Selecting NavigationKit Framework
  1. Repeat the activities in Step 1 to import the NavigationKit.framework package.

  2. Locate NavigationKit.framework in the Frameworks folder as shown in the above screenshot.

  3. Drag the NavigationKit.bundle from the Resources folder to the Resources group in your project.

NavBundle
Figure 5. NavigationKit.bundle in the Resources Folder
  1. Under the Build Phases tab, select the drop-down, Link Binary With Libraries and add the frameworks listed below.

    • CoreTelephony.framework

    • libC++.1.tbd

    • libz.1.2.5.tbd

The frameworks to be added are highlighted in the following screenshot.

LinkBinary_Nav
Figure 6. Adding Frameworks

Adding Permissions to Info.plist File

The following step is performed to add Navigation to the ViewController.

Open ViewController.m and add the following code snippet before @interface ViewController ().

#import <LocationToolKitCommon/LTKContext.h>
#import <NavigationKit/LNKNavigation.h>

The following permissions must be declared inside the Info.plist file. These permissions are needed for network requests and for loading the navigation. You need to declare these permissions before using the NavKit classes.

<key>NSAppTransportSecurity</key> <dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
<key>NSLocationWhenInUseUsageDescription</key> <string>Used for the
map.</string>
<key>UIBackgroundModes</key> <array>
<string>location</string> </array>

The network and location permissions which must be enabled are highlighted in the following screenshot.

Permissions
Figure 7. Permissions in Info.plist File

Creating a Navigation Session

The following sections describe the process to create a Navigation session.

Creating the LTKContext Object

For using the Location ToolKit (LTK) services, you must create a LTKContext object, a singleton instance of services through which you can configure the API Key, language, country, and so on as shown in the following code snippet. To get started, this code snippet is added to the ViewControllers’s viewDidLoad() method.

LTKContext* ltkContext = [[LTKContext alloc]
init:@"PUT_YOUR_API_KEY_HERE"
language:@"en-US"
countryCode:@"US"
mdn:nil
productName: @"default"
pushMessageGUID:nil];

Replace “PUT_YOUR_API_KEY_HERE”, with the API key received from Comtech, in the above code snippet.

Creating the LNKRouteOptions Object

The class LNKRouteOptions specifies the various settings which control the generated route. It provides the route configurations like route type, transportation mode, avoid and so on.

The available options are:

  • Route type - Easiest/Fastest/Shortest

  • Transportation - Bicycle/Car/Pedestrian/Truck

  • Avoid - Highway/Toll/Hov/Ferry

Note
Avoid contains either one or a combination of any of the available options.

The following code snippet shows the route configurations set using the LNKRouteOptions class.

LNKRouteOptions* routeOptions = [[LNKRouteOptions alloc]init];
routeOptions.avoid = aVoid.value;
routeOptions.routeType = routeType.value;
routeOptions.transportationMode = vehicleType.value;
routeOptions.pronunciationStyle = @"";

Creating the Navigation Preferences

The LNKPreferences class provides various navigation configurations like guidance, announcements in phonetic format, traffic alerts, measurement units and so on.

The following code snippet shows the configurations set using this class.

LNKPreferences* preferences = [[LNKPreferences alloc]init];
preferences.speedThresholdForGpsHeading = [validGpsHeading.name doubleValue];
preferences.recalcCriteria = LDL_Tight;
preferences.positionUpdateRate = 10;
preferences.laneGuidanceEnabled = YES;
preferences.naturalGuidanceEnabled = YES;
preferences.offRouteIgnoreCount = offRouteSensitivity.value;
preferences.trafficAnnouncementEnabled = (trafficOption.value != 0);
preferences.useTraffic = trafficOption.value;
preferences.measurement = measurmentOption.value;
preferences.multipleRoutesEnabled = multipleRoute.value;
preferences.enhanceNavigationStartupEnabled = enhancedRoute.value;
preferences.enhanceNavigationStartupTimeout = enhancedRouteTimeout.value;
preferences.local = language.name;

Starting a Navigation Session

LNKNavigation class is the entry point of Navigation session. Creating a LNKNavigation instance creates a Navigation session. To create a Navigation session, you need to provide LTKContext, destination place, route options, and navigation preferences as shown in the following code snippet.

// Create a sample destination location
LTKPlace* destination =  [[LTKPlace alloc] init];
destination.latitude = 40.654757;
destination.longitude = -117.77774;


// Get navigation session
LNKNavigation*navigation = [LNKNavigation getNavigation : ltkContext destination : destination routeOptions : routeOptions preferences : preference ];

Navigation Delegates

iOS NavKit SDK provides various Navigation Delegates to track navigaton events. Following list has major Navigation Delegates.

  • LNKSessionDelegate: Has various methods to notify route received, route error, route progress, offroute and so on.

  • LNKNavigationUpdateDelegate: Notifies the events like remaining trip distance, remaining distance, and next maneuver.

  • LNKTrafficDelegate: Notifies the events during traffic, like traffic alerts.

  • LNKAnnouncementDelegate: Notifies the next announcement events.

[navigation addSessionDelegate:self];
[navigation addNavigationUpdateDelegate:self];
[navigation addAnnouncementDelegate:self];


#pragma - LNKSessionDelegate
/*! Informs the client that new route requested

 @param reason why new route is requested.
 */
- (void) routeRequested : (LNKRouteRequestReason) reason
{
    NSLog(@"Route Requested........");
}

/*! Provides the route generation progress
 */
- (void) routeProgress : (NSUInteger) progress
{
    NSLog(@"Route Progress……..”);
}
/*! Indicates that an error happened and this navigation session is no longer valid.

 Need to recreate a new one to continue the navigation session.
 */
- (void) routeError : (LNKNavigateRouteError) error
{
    NSString* errorMessage = nil;
    BOOL needToStopNav = YES;
    switch (error) {
        case LRE_TimedOut:
            NSLog(@“Route timed out error”);
            break;
        case LRE_BadDestination:
           NSLog(@"Routing destination is not near a routable road”);
            break;
        case LRE_BadOrigin:
          NSLog(@"Origin no near a routable road”);
            break;
        case LRE_CannotRoute:
            NSLog(@"No route can be found between the origin and the destination”);
            break;
        case LRE_EmptyRoute:
            NSLog(@"Empty route”);
            break;
        case LRE_NetError:
            NSLog(@"We are having trouble communicating with its servers. Please try again.”);
            break;
        case LRE_NoMatch:
           NSLog(@Route not match”);
            break;
        case LRE_NoDetour:
            NSLog(@"No route detour”);
            break;
        case LRE_PedRouteTooLong:
            NSLog(@"Pedestrian route is too long. Please choose a closer destination.”);
            break;
        case LRE_OriginCountryUnsuppoted:
            NSLog(@“Origin Country Unsupported”);
            break;
        case LRE_DestinationCountryUnsupported:
            NSLog(@"Destination Country unsupported”);
            break;
        default:
            NSLog(@"UnknownError error”);
            break;
    }

}
/*! Informs the client that current navigation session ends. The client will not
 receive any route updates.

 This navigation session needs to be stopped by the client.
 */
- (void) routeFinished
{
    NSLog(@“Route Finished”);

}

To know more about delegates, see the NavKit iOS API Reference Guide.

Updating the Location

To update a Navigation location, you need to send each LTKLocation update to the created Navigation instance as shown in the following code snippet.

-(void) locationUpdated : (LTKLocation*) location
{
    [navigation updatePosition:location];
}

Building and Running the NavSample App

Using the preceding code snippets in Getting Started, you can test the initialization and creation of the navigation session in the sample app. On building and running the sample app, you can see the navigation session creation logs in the Console as shown in the following screenshot.

NavSession_Logs
Figure 8. Navigation Session Logs