사용 등록

KakaoMapsSDK를 사용하기 위해 등록하는 방법

사용등록을 위해 알아야 할 사항


KakaoMapsSDK를 사용하기 위해서는 KakaoDevelopers에 앱을 등록하고 KAKAO_APP_KEY 를 발급받아야 합니다. KakaoMapsSDK는 KakaoDevelopers를 통해서 API 사용량을 관리합니다.
KakaoMapsSDK는 제공할 지도의 종류 및 구성에 대한 내용을 별도의 서버를 통해 정의해 두고 있습니다. 이러한 정의는 App(이름때문에 혼동할 수 있으나 서버상에 있는 predefined config group 이라고 생각하시면 됩니다)과 ViewInfo 두 단계로 구성됩니다. App은 제공할 baseMap/overlay의 종류 및 각각의 세부 레이어 구성, ViewInfo, 이 App 설정을 사용할 수 있는 app id 목록을 정의합니다. ViewInfo는 속해 있는 App에 정의된 BaseMap/Overlay를 이용하여, 사용할 BaseMap 및 최소/최대 레벨, 렌더링 방법, 좌표체계, 사용가능한 overlay 목록을 정의합니다.
App 정의 구성
API는 이 서버를 통해 초기화시에 어떤 지도 데이터를 어디에서 어떻게 로딩하여 그릴지를 결정하게 됩니다. 이에 대한 접근은 초기화에 사용되는 ViewInfo의 appName 과 viewInfoName을 통해 이뤄집니다. 즉, 어떤 App 설정의 viewInfo를 사용할지 지정하게 됩니다. 일반적인 경우, appName 으로 “openmap”, viewInfoName으로 “map” 을 사용하면 됩니다. App설정 “openmap” 인 경우에는 사용하는 App ID에 제한이 없지만 나머지 app 설정들은 app 설정에 미리 등록된 app id로만 사용이 가능합니다. App설정이나 App ID 추가 등록이 필요한 경우 별도 문의하시면 됩니다.

KAKAO_APP_KEY 발급하기


KakaoMapsSDK 설치 후, KakaoMapsSDK를 사용할 KAKAO_APP_KEY를 등록해야 KakaoMapsSDK를 사용할 수 있습니다. 아래는 KAKAO_APP_KEY를 발급받고 앱에 등록하는 절차입니다.

앱 등록하기

  1. Kakao Developers로 이동합니다.
  2. [내 애플리케이션] -> [애플리케이션 추가하기]에서 API를 사용할 앱을 등록합니다.

네이티브 앱 키 발급 및 앱에 추가

  1. [내 애플리케이션] -> [앱 설정] -> [앱 키]에서 네이티브 앱 키를 발급받습니다.
  2. 네이티브 앱 키를 복사한 후, API를 사용할 앱의 Info.plist에 아래와 같은 필드를 추가합니다.

Info.plist 등록

  • KAKAO_APP_KEY : KakaoMapsSDK 사용을 위해서 필수로 입력해야 하는 필드입니다. 발급받은 네이티브 앱 키를 해당 필드에 등록합니다.
  • KAKAO_PHASE : 테스트를 위해 phase별로 등록한 앱은 앱의 phase 정보를 해당 필드에 등록합니다. alpha, beta, sandbox중 하나를 해당 필드에 등록합니다. 예를 들어, https://sandbox-developers.kakao.com의 경우 KAKAO_PHASE 필드에 sandbox 로 명시합니다. real인 경우, 공란으로 둡니다.

인증절차


KakaoMapsSDK를 사용하기 위해서는 인증 절차를 거쳐야 합니다. 인증은 Kakao Developers에 등록한 앱키를 기반으로 이루어집니다. 엔진을 시작하면 자동으로 인증 절차가 진행됩니다. 아래 그림은 인증 처리 과정을 도식화한 그림입니다.

인증절차

인증 처리 과정은 내부적으로 비동기적으로 진행되어 성공할 경우 계속해서 API를 사용할 수 있습니다. 만약 인증에 실패하게 되면 엔진이 강제로 정지되고 API를 사용할 수 없게 됩니다. 인증 결과에 따라 MapControllerDelegate의 delegate 함수가 호출되며, 성공시에는 별다른 작업이 필요없지만 실패했을 경우에는 API를 사용할 수 없게 되므로 이에 대한 적절한 추가 처리 작업이 필요할 수 있습니다. 인증이 실패할 경우에는 인증 실패에 대한 에러코드가 함께 전달됩니다. 아래 예제는 인증 절차를 설명한 예제입니다.

    override func viewDidLoad() {
        
        super.viewDidLoad()
        mapContainer = self.view as? KMViewContainer
        
        //KMController 생성.
        mapController = KMController(viewContainer: mapContainer!)!
        mapController!.delegate = self
        mapController?.initEngine() //엔진 초기화. 엔진 내부 객체 생성 및 초기화가 진행된다.
    }

    override func viewWillAppear(_ animated: Bool) {
        addObservers()
        if _auth {
            if mapController?.engineStarted == false {
                mapController?.startEngine()
            }
            
            if mapController?.rendering == false {
                mapController?.startRendering()
            }
        }
    }
    
    // MapControllerDelegate. 인증에 성공했을 경우 호출. 
    func authenticationSucceeded() {
        print("성공")
    }
    
    // MapControllerDelegate. 인증에 실패했을 경우 호출.
    // errorCode : 에러 코드
    // desc : 에러 디스크립션 
    func authenticationFailed(_ errorCode: Int, desc: String) {
        print("error code: \(errorCode)")
        print("\(desc)")

        // 추가 실패 처리 작업
    }

인증 실패 시의 에러코드는 아래와 같습니다.

Error Code Description
400 일반적인 오류. 주로 API에 필요한 필수 파라미터와 관련하여 서버가 클라이언트 오류를 감지해 요청을 처리하지 못한 상태
401 인증 오류. 해당 리소스에 유효한 인증 자격 증명이 없어 요청에 실패한 상태
403 권한 오류. 서버에 요청이 전달되었지만, 권한때문에 거절된 상태
429 쿼터 초과
499 서버와 통신 실패. 인터넷 연결 확인 필요

특별히 499 에러의 경우 인증서버와의 통신에서 문제가 생겨서 발생하는데, 네트워크 상태가 다시 정상으로 돌아왔다고 판단하여 재시도 할 수 있습니다. 이 때에는 KMController의 authenticate 함수를 직접 호출하여 인증을 다시 시도할 수 있습니다.