Quick Start Guide for iOS MapKit3D SDK

Introduction

This document describes the features of the iPhone® Operating System (iOS) MapKit3D 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.3 or above) must be installed.

Note
 The iOS MapKit3D SDK supports APIs with a minimum version of 8.0 and above. This SDK targets the 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 start using the iOS MapKit3D SDK.

Getting the SDK

To obtain the iOS MapKit3D 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 link, sent to the registered email ID.

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

git clone https://git.location.studio/location.studio/iOSSDK.git

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 add a basic map to 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 run the iOS MapKit3D SDK.

  1. Start Xcode.

  2. Start a new Xcode project.

  1. Select a Single View App project and click Next as in the following screenshot.

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 list.
Configuring
Figure 2. Choosing Options for the New 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.

Adding LTK Frameworks to Your Project

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

  • locationToolKitCommon.framework

  • Mapkit3D.framework

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

  • From the File menu, select Add Files to MapKit3DSampleApp… as shown in the following screenshot and then click Add.

FileNew
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.

ImportFramework
Figure 4. Importing .framework

  1. Repeat the activities in Step 1 to import the Mapkit3D.framework package.

Note
 Mapkit3D.framework contains a prepackaged set of resources for different map elements like avatar, compass, pin and so on.

  1. Locate MapKit3D.framework in the Frameworks folder.

  2. Drag the MapKit3D.bundle in the Resources folder to the Resources group in your project.

SelectBundle
Figure 5. MapKit3D.bundle in the Resources Folder

  1. Under 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.

Link Binary With Libraries
Figure 6. Adding Frameworks

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.

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.

Note
 This object instance must remain live while using the application. The LTKContext instance parameter contains the authorized credentials for the server you want to connect.

Adding Network Permissions

Add the following keys in the Info.Plist file for enabling the network permissions and loading the network requests.

<key>NSAppTransportSecurity</key> <dict>
<key>NSAllowsArbitraryLoads</key>
     <true/>
   </dict>

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

Enabling Network Permissions
Figure 7. Enabling Network Permissions

Adding MapView to ViewController

The following steps are performed to add MapView to the ViewController.

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

#import <LocationToolKitCommon/LTKContext.h>
#import <Mapkit3D/LMKMap3DView.h>

  1. Once the MapKit3D LMK3DMapView is added to the ViewController, add the following code snippet in -(void)viewDidLoad method.

LMKMap3DView* mapView = [[LMKMap3DView alloc]
initWithFrame: self.view.bounds withContex:
ltkContext];
// Before using the map view you must wait for the
initialization callback
[mapView setDelegate:self];
[self.view addSubview:mapView];

MapView Delegate

The method didMapViewInitialized acts as a callback method. Setting this delegate as shown in the following code snippet notifies when the map is created or MapView gets initialized.

- (void)didMapViewInitialized
{
NSLog(@"Map View Created");
}

Building and Running a Basic Map

The steps in Getting Started are sufficient to run and load the map. After building and running the sample app, you can see the map as shown in the following figure.

BasicMap
Figure 8. Basic Map

Optional - Adding Location Request permissions

The following location permissions are optional inside the Info.Plist file. It is not mandatory to have them enabled for the map to load.

<key>NSLocationWhenInUseUsageDescription</key> <string>Used for the map.</string>
<key>UIBackgroundModes</key> <array>
<string>location</string> </array>

The following screen highlights the location permissions which can be enabled in the Info.Plist file.

Note
 The location permissions are needed to get the current location of avatar.
LocationScreen
Figure 9. Info.plist File