Before you begin

Requirements

Check the programming language used by the iOS Directions SDK with UI and the minimum requirements.

TIP

Swift support is planned for a future release.

• Programming language: Objective-C
• iOS 15 or later
• iOS Deployment Target 15 or later

Registering an app and checking the native app key

DANGER

To use the iOS Directions SDK with UI, you must register an app and obtain a native app key for SDK initialization.

1. Registering an app

[On Kakao Developers]

1. Log in to Kakao Developers. If you do not have an account, sign up and then proceed to the next steps.

2. After logging in, click App → Create app at the top right of the screen.

3. Check the content to add for each item below and add your app.

   
   

• App icon: Add an image to use as the app icon. The recommended image size is 128x128 px, and you can upload a file of up to 250 KB. Supported file formats are JPG, GIF, and PNG.

• App name: Set the name of your app (service). * Required

• Company name: Enter the business name. You must use the same name as your business information. * Required

DANGER

Note: The app (service) name can be up to 30 characters, including spaces.

• Category: Select the category of your service. * Required

• App primary domain: Enter the primary domain of your service.

4. Enter each item, verify that it does not violate any restrictions in the operating policy, and click Save to create the app. You can view the created app under App.

2. Registering service information

[On Kakao Developers]

SDK initialization requires a native app key, and you must register the service information on Kakao Developers before use.

1. Click App → select the app to issue an app key for → App → Platform key.

2. Select Add key to add a native app key, or select the default key that was created.

3. Register the required service information items.

   
   

• Native app key: Check the issued key value and its status, and copy it.
• Key name: Specify a name to identify the key. * Required
• (iOS) Bundle ID: The unique identifier of the iOS app, which you can find in Xcode under Target → General → Identity.
• (iOS) Store URL: Register the App Store URL to open when the app is not installed. You can add a URL for iPhone and iPad separately.
• Scheme: Check the app scheme information issued for the key.
• Additional information: Check the key's activation status, creation date, and modification date.

3. Checking the native app key

[On Kakao Developers]

1. Click App → select the app to issue an app key for → App → Platform key.
2. Copy and use the native app key value.
   

TIP

For details, see App settings on Kakao Developers.

Starting a project

1. Creating a new project

Follow the steps below to create a project.

TIP

This document is based on Xcode version 13. The screens and details may differ from the descriptions in this document depending on the version you use.

1. Launch Xcode and click Create a new Xcode project.

2. Select the Application you want, then click Next.

3. Set the name of the project. Once the settings are complete, click Next.

   TIP

   Set Language to Objective-C.

4. Select the path to save the project, then click Create.

2. Adding the framework

From iOS Directions SDK with UI version 1.6.0, you can configure the repository using CocoaPods, and from version 1.6.7, Swift Package Manager is also supported. Add the framework using the method that suits the SDK version you are using.

[Repository configuration methods by iOS Directions SDK with UI version]

• Version 1.6.7 or later: Swift Package Manager
• Version 1.6.0 or later: CocoaPods

Configuring the repository with CocoaPods

Add the framework of the iOS Directions SDK with UI using CocoaPods. CocoaPods is written in the Ruby programming language, so you can install and use it on a MacBook right away.

1. Launch Terminal and enter the command below to install Ruby.

$ brew install ruby

2. Enter the command below to install CocoaPods.

$ sudo gem install cocoapods

3. Specify the path of the project folder you want to work in.

$ cd /Users/KakaoNavi

4. Enter the command below to create a Podfile.

$ pod init

The Podfile is added as follows.

5. Open the created Podfile in a text editor, edit it as follows, and save it.

  # Uncomment the next line to define a global platform for your project
  # platform :ios, '12.0'

  source '<https://github.com/CocoaPods/Specs.git>'

  target 'KakaoNavi' do
    # Comment the next line if you don't want to use dynamic frameworks
    use_frameworks!

    # Pods for KakaoNavi
    pod 'KNSDK-UI'
  end

6. Enter the commands below to install the framework.

$ pod cache clean --all
$ pod install --repo-update

Configuring the repository with Swift Package Manager

Add the framework of the iOS Directions SDK with UI using Swift Package Manager.

1. In Xcode, click through the path below.
   
   Path: KNSample under TARGETS → General → Frameworks, Libraries, and Embedded Content → +

2. Click Add Other... → Add Package Dependency.

3. Enter the GitHub address below in the input field at the top right, select the version you want under Dependency Rule, and click Add Package to install the framework.
   
   Address: https://github.com/kakaomob/KNSDK-UI.git

3. Importing the SDK

To use the iOS Directions SDK with UI in your iOS app, you must import the iOS Directions SDK with UI files as follows.

#import <KNSDK/KNSDK.h> // Authentication and route search SDK
#import <KNSDK/KNNaviView.h> // Navigation UI SDK

4. Configuring info.plist

Registering the app launch allowlist

To use the feature that launches apps through the iOS Directions SDK with UI, you must add settings to the Info.plist file. This setting is required by the OS policy for protecting user information. For details, see Privacy and Your App.

Click the info.plist file under the project and click + in Information Property List to add the key values of info.plist.

Table 1 info.plist

Key	Type
Privacy - Location When In Use Usage Description	String
App Transport Security Settings	Dictionary

The info.plist entries are added as follows.

Configuring App Transport Security (ATS)

To improve security when the app communicates with web services, you must configure App Transport Security (ATS). The details are as follows. Click + in App Transport Security Settings to add the key values and types for ATS and the domain.

Table 2 ATS

Key	Type	Value
Allow Arbitrary Loads	Boolean	YES
Exception Domains	Dictionary	(1 items)

Table 3 Exception Domains

Key	Type	Value
kakao.com	Dictionary	(4 items)

Table 4 Domain details

Key	Type	Value
NSExceptionAllowsInsecureHTTPLoads	Boolean	YES
NSExceptionRequiresForwardSecrecy	Boolean	NO
NSIncludesSubdomains	Boolean	YES
NSTemporaryExceptionMinimumTLSVersion	String	TLSv1.0

ATS is configured as follows.

5. Initializing

To use the iOS Directions SDK with UI, you must initialize it using the native app key.

TIP

If initialization fails, check the details about authentication errors in Troubleshooting.

Information about the key values you can use is as follows.

• AppKey: String The native app key required to use the iOS Directions SDK with UI, which you can obtain from Kakao Developers. With it, you can initialize the SDK and use Directions features.
• UserKey: String A key to identify a user. Assign an arbitrary value and set it freely to suit your environment. For example, you can use an existing member number as the key value.
• ClientVersion: The version name of the client that the iOS Directions SDK with UI is applied to.

[[KNSDK sharedInstance] initializeWithAppKey:AppKey clientVersion:ClientVersion userKey:UserKey completion:^(KNError *error) {
    if (error)
    {
        NSLog(@"KNSDK Init Failed(%@, %@)", error.code, error.msg);
    }
    else
    {
        NSLog(@"인증 성공"); // "Authentication succeeded"
    }
}];

6. Adding AVAudioSession

DANGER

If you do not add AVAudioSession, the voice guidance of the navigation may be interrupted.

AVAudioSession *session = [AVAudioSession sharedInstance];
NSError *error = nil;
[session setActive:NO error:&error];
AVAudioSessionCategoryOptions category = AVAudioSessionCategoryOptionMixWithOthers;
[[AVAudioSession sharedInstance] setMode:AVAudioSessionModeDefault error:nil];
[[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback withOptions:category error:&error];
[session setActive:YES error:&error];

Integrating Objective-C in a Swift project

By using a bridging header, you can integrate Objective-C in a Swift project and use the classes and functions provided by the iOS Directions SDK with UI.

1. In Xcode, click File → New → File....

2. Select Header File under iOS → Source, then click Next.

3. Set the header name, save location, and other options, then click Create.

4. The bridging header file is created as follows.

5. In Build Settings under TARGETS → Swift Compiler - General → Objective-C Bridging Header, enter the location of the header you added in step 3.

6. Set Packaging → Defines Module to YES.

7. Click the header file you created and add the following. The Swift project integration is complete.

#import <KNSDK/KNSDK.h> // Authentication and route search SDK
#import <KNSDK/KNNaviView.h> // Navigation UI SDK