본문 바로가기 메뉴 바로가기

Kakao i Agent SDK::iOS::개발 프로세스::SDK 초기화

페이지 이동경로

SDK 초기화하기

iOS 버전의 Kakao i Agent SDK를 사용하기 위해 SDK를 초기화합니다. SDK 초기화 단계에는 Phase 설정과 인터페이스 및 Delegate 설정이 필요합니다.

Phase 설정

info.plist에 KAKAO_PHASE 값을 추가하여 Phase를 설정합니다. 사용 가능 Phase는 sandbox, stage, real 입니다. KAKAO_PHASE 값의 Prefix 대조로 sandbox와 stage를 구분하며, 조건이 맞지 않을 경우에는 real로 동작합니다.

Phase는 Property List 또는 Info.plist에서 설정할 수 있습니다.

안내
개발 Phase는 사전에 Kakao i 담당자와 논의해야 합니다. 자세한 설명은 개발 Phase 정의하기 를 참고하시기 바랍니다.

Property List에서 추가하기

Info > Property List에서 String 타입 키(Key)인 KAKAO_PHASE를 추가하고, 해당 키의 Value로 $(CONFIGURATION)을 추가합니다.

Phase 설정 그림Phase 설정

info.plist 파일을 수정하여 설정하기

Property List에서 Phase를 수정하지 않고, 다음의 예제를 참고하여 Info.plist 파일을 직접 수정하여 Phase를 적용하는 것도 가능합니다.

<key>KAKAO_PHASE</key>
<string>$(CONFIGURATION)</string>

인터페이스 및 Delegate 설정하기

SDK를 초기화하기 위해 application(_:didFinishLaunchingWithOptions:) 메서드에서 하기 순서에 따라 KakaoI.shared 객체를 제어합니다.

안내
Kakao i Agent SDK의 초기화 및 개발 환경은 Kakao Developers 사이트의 구현 방식을 기반으로 합니다.

  1. SDK를 사용하기 위해 필요한 인터페이스를 등록하고 Delegate를 선언합니다. 코드예제SDK 초기화 

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    KakaoI.shared.delegate = self
    KakaoI.shared.authDelegate = self
    KakaoI.shared.printDebugLog = true

    KakaoI.shared.register(interface: KIPhoneCallInterface.shared)
	KIPhoneCallInterface.shared.delegate = self

    KakaoI.shared.register(interface: KITemplateInterface.shared)
    KITemplateInterface.shared.delegate = self

 	/*
	// @todo: SDK를 활성화하는 메서드를 호출합니다.
	KakaoI.shared.setEnabled(enabled: true, completion: nil)
	*/
    return true
}

    표Kakao i Agent SDK 모듈
구분 메서드 필수 여부 설명
KakaoI.shared delegate 필수 Kakao i Agent SDK의 Delegate
- 카카오 i 음성 인식 서비스를 사용하는 앱은 반드시 구현 필요
authDelegate 필수 Kakao SDK의 access token, refresh token, app user id를 리턴하는 Delegate
printDebugLog 선택 Kakao i Agent SDK의 디버깅 속성값
true: 디버깅 사용
false: 디버깅 미사용
setEnabled(enabled: true) 필수 카카오 i 음성인식 사용 여부 설정
true(기본값): 사용
false: 미사용
register(interface: KIPhoneCallInterface.shared) 필수 전화 걸기 인터페이스를 사용 시 등록
KIPhoneCallInterface.shared delegate 필수 전화 걸기 관련 기능을 사용하기 위한 Delegate
register(interface: KITemplateInterface.shared) 선택 View Template 인터페이스를 사용 시 등록
KITemplateInterface.shared delegate 선택 View Template 기능을 사용하기 위한 Delegate
안내
iOS 버전의 Kakao i Agent SDK에서 제공하는 Delegate에 대한 자세한 설명은 API 레퍼런스 문서를 참고하시기 바랍니다.

  1. SDK에 기본 탑재된 View Template을 사용하기 위해서는 KITemplate 인터페이스의 Delegate를 설정해야 합니다.

    • 만약 다른 View Template을 구현하는 경우, KITemplateInterfaceDelegate 프로토콜에 선언된 메서드를 확장해서 사용합니다. 메서드 확장에 대한 자세한 설명은 음성 인식 결과 화면 출력 를 참고하시기 바랍니다.
    KakaoI.shared.register(interface: KITemplateInterface.shared)
KITemplateInterface.shared.delegate = self

로그인별 동작 처리

최종 사용자가 카카오 i 음성 인식 서비스를 사용하기 위해서는 기본적으로 카카오 계정을 통해 헤이카카오 서비스에 가입해야 합니다. 하지만 헤이카카오 서비스에 가입하지 않고 카카오 i 음성 인식 서비스를 사용하는 사용자들을 위해, Kakao i Agent SDK iOS에서는 v2.1.3.842(2022년 01월)부터 헤이카카오 비로그인 방식을 지원하고 있습니다. 고객사는 헤이카카오 로그인 방식만 단독 구현할 수는 있지만, 비로그인 방식을 사용할 경우에는 반드시 헤이카카오 로그인 기능과 함께 구현해야 합니다.

로그인별 동작 처리는 헤이카카오 로그인 기능만 구현할 경우와 헤이카카오 로그인과 비로그인 기능을 함께 구현하는 경우로 구분됩니다.

로그인 기능만 구현

카카오 i SDK에는 자체적으로 헤이카카오 서비스 가입 프로세스가 구현되어 있습니다. 따라서 헤이카카오 로그인 방식만 구현할 경우에는 별도의 작업이 필요하지 않으며 계정 상태 체크 단계로 넘어가시기 바랍니다.

로그인/비로그인 기능 함께 구현

안내
현재(2022년 1월) 기준으로 헤이카카오 비로그인 기능은 카카오맵에 한해 지원합니다.

  1. 헤이카카오 로그인 방식과 헤이카카오 비로그인 방식을 함께 적용하는 경우에는 AccountManager를 통해 로그인/비로그인 동작 처리를 구현해야 합니다. AccountManager를 사용 시 AccountState( .unavailable, .kakaoAccount, .anonymous)에서 사용자의 로그인 계정 유형을 조회할 수 있습니다. 

    class AccountManager {

    enum AccountState {
	    case unavailable  // 헤이카카오에 로그인을 하지 않은 초기화 상태
    	case kakaoAccount // 카카오 로그인을 이용하여 헤이카카오에 로그인을 한 상태
        case anonymous    // 헤이카카오 비로그인 기능을 이용하여 헤이카카오에 로그인을 한 상태
	}

    표로그인 상태 조회
    AuthType 기능 구분 Kakao 로그인 여부 Kakao i 로그인 여부
    .unavailable 헤이카카오에 로그인을 하지 않은 초기화 상태 비로그인 상태 비로그인 상태
    .kakaoAccount 카카오 로그인을 이용하여 헤이카카오에 로그인을 한 상태 로그인 상태 로그인 상태
    .unavailable 헤이카카오에 로그인을 하지 않은 초기화 상태 비로그인 상태 로그인 상태
    코드예제헤이카카오 로그인/비로그인 여부 확인 
switch AccountManager.shared.state {
    case .unavailable:
    	// 초기 상태
    case .kakaoAccount:
    	// 헤이카카오 로그인 상태
    case .anonymous:
    	// 헤이카카오 비로그인 상태
    default:
}

안내

  • 사용자가 헤이카카오 비로그인 기능 사용 중 카카오 로그인을 통해 헤이카카오 서비스를 가입을 하는 경우, 비로그인 기능을 사용하는 동안 생성된 정보들은 더 이상 사용되지 않습니다.
  • 카카오 로그인 기능을 사용하는 도중에 카카오 로그아웃 또는 헤이카카오 서비스에 탈퇴 시, 비로그인 상태로 전환됩니다.

  1. 헤이카카오 비로그인 기능을 사용하는 프로젝트에 AccountManager 메서드를 사용하여 카카오 i 초기화 시점에 헤이카카오 비로그인 사용 여부를 설정합니다.

    • Access Token, Refresh Token, AppUser ID 등 가입 정보를 확인하는 로직입니다. 각 단계는 Operation으로 구성되어 있으며, 차례대로 실행됩니다. 중간에 하나라도 Error가 발생하면 전체가 취소되며, 바로 completion을 통해 오류 내용을 알 수 있습니다.

    • 모바일 앱의 AppUser ID는 Kakao SDK에서 제공하는 Access Token Info에서 확인 가능하며, 자세한 설명은 Kakao Developers > 토큰 존재 여부 확인하기 문서를 참고하시기 바랍니다.

      AccountManager.shared.readyAuth(completion: ([Error]?) -> Void)
AccountManager.shared.anonymousAuth(completion: ([Error]?) -> Void)
    표비로그인 사용 여부 설정
메서드 설명
AccountManager.shared.readyAuth 헤이카카오 로그인 기능 사용 설정
AccountManager.shared.anonymousAuth 헤이카카오 비로그인 기능 사용 설정

코드예제헤이카카오 로그인/비로그인에 따른 분기 처리 

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    /**
     * 앞서 진행된 SDK 초기화 코드
     */

    if 비로그인 {
    	// @todo: kakao i를 시작하는 start 메서드를 호출합니다.
    } else {
        // @todo: 계정 상태 체크 단계로 넘어가서 후속 작업을 진행합니다.
	}

	return true
}

  1. 헤이카카오 비로그인이 SDK 초기화 시점에 활성화가 되면, 카카오 i 음성 인식 서비스를 시작하는 메서드를 호출합니다.

    • 앞서 설명한 Delegate 객체가 반드시 연결되어 있어야 합니다.
    • completion은 사용자가 카카오 i를 사용 안 함 으로 설정했거나, 가입 정보를 체크하는 과정에서 Error가 발생했을 때, Error와 함께 반환됩니다.
    KakaoI.shared.start(anonymous: true) { }
    표헤이카카오 비로그인 사용 여부 설정
    메서드 설명
    Astart(anonymous: Bool = false, completion: @escaping ([Error]?) → Void) 헤이카카오 비로그인 기능 사용 여부 설정
    true: 기능을 사용
    false(기본값):
    기능을 사용하지 않음
    안내
    헤이카카오 비로그인 기능을 사용하기 위해서는 사전 작업 완료 후 카카오 i 담당자에게 해당 기능의 사용 여부를 공지해야 합니다.
    코드예제비로그인 시 SDK 초기화(종합) 
        AccountManager.shared.anonymousAuth { _ in
        KakaoI.shared.setEnabled(enabled: true) { [weak self] _ in
            KakaoI.shared.start(anonymous: true) { errors in
            //@todo: kakao i 시작이 완료되면 수행할 작업을 작성합니다.
            }
        }
    }

계정 상태 체크

헤이카카오 서비스를 사용하기 위해서는 반드시 헤이카카오 로그인이 되어야 합니다. 헤이카카오 로그인 기능을 구현 시, 카카오 로그인 토큰을 이용하여 헤이카카오 서비스에 로그인합니다.
따라서 헤이카카오 서비스를 사용하기 전에 checkAccount() 메서드를 통해서 현재 계정의 상태를 체크해야 합니다.

안내
로그인과 계정 상태 체크가 완료되어야 카카오 i 음성 인식 서비스를 사용할 수 있습니다.
  1. KakaoI.checkAccount()를 호출합니다. 호출 시 @escaping 메서드의 completion으로 현재 카카오 계정 상태를 전달합니다.
KakaoI.shared.checkAccount(completion: (KIAccountState, KIAgreementController?) -> Void)
파라미터 설명
KIAccountState 현재 계정의 연결 상태
KIAgreementController 계정을 사용하기 위해 추가로 사용자 인터랙션이 필요할 경우 사용해야 하는 View Controller
- UIViewController.present를 이용하여 화면에 표시 가능

  1. Completion 콜백으로 받은 KIAccountState의 상태 값에 따라 처리 할 인터페이스를 구현합니다. 각 상태 값에 대한 설명을 참고하여, 필요 시 후속 진행 작업을 수행합니다.

    표KIAccountState 상태 값
    속성 설명 비로그인 상태일 때
    .approved 카카오 계정 상태가 정상이며, 사용자가 이미 헤이카카오에 가입이 되어 있는 상태 -
    .approvedAnonymous 사용자가 비로그인으로 접속한 상태 -
    termsAgreementRequired 카카오 계정은 정상이나, 헤이카카오에 약관이 추가되어 약관 추가동의가 필요한 상태 비로그인 시 호출되지 않음
    .signupRequired 사용자가 헤이카카오에 가입이 안 되어있거나 로그인이 필요한 상태 비로그인 시 호출되지 않음
    .authorizationFailed 카카오 계정 토큰이 유효하지 않은 상태 -
    .accessTokenExpired 카카오 계정 토큰이 만료되어 토큰 갱신이 필요한 상태 비로그인 시 내부적으로 토큰 갱신 처리
    .error 예상하지 못한 오류 -

Sample Code

다음은 checkAccount() 콜백 메서드를 사용한 예제입니다.

 KakaoI.shared.checkAccount { [weak self] state, controller in
    guard let self = self else { return }
    switch state {
    case .approved:
            /**
            * 사용자 상태 및 토큰 정보가 정상으로 사용 가능한 상태
            * start 메서드를 호출하고 Kakao i 음성 인식 서비스를 시작할 수 있습니다.
            */
    case .termsAgreementRequired:
            /**
            * 사용자가 추가로 동의해야 할 약관이 존재할 경우
            */
    case .authorizationFailed:
            /**
            * 액세스 토큰이 만료된 경우로, 액세스 토큰 갱신 후 재시도 필요
            */
    case .signupRequired:
            /**
            * 사용자가 Kakao i 음성 인식 서비스를 사용하고 있지 않은 상태로, Kakao i 가입이 요구되며 가입이 완료되면 signupCompletion이 전달됩니다.
            * 추가로 사용자와 인터랙션이 필요할 경우 콜백으로 받은 controller 값을 사용하고 UIViewController.present를 이용하여 화면에 띄우면 됩니다.
            */
    if let controller = controller {
        controller.signupCompletion = { [weak self] error in
            guard let self = self else { return }
            controller.dismiss(animated: true, completion: nil)
            if let error = error {
                let errorMessage = "\(error)"
                self.alert = self.makeErrorAlert(with: errorMessage)
            }
            else {
                KakaoI.shared.setEnabled(enabled: true) { _ in self.start() }
            }
        }
            self.viewControllerToPreceed = controller
        }
    case .error:
            /**
            * 정의되지 않은 오류가 발생함
            */
    default:
    }
}
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 contact.dkt@kakaocorp.com 으로 제보해주세요.