Kakao i Agent SDK::Android::API 레퍼런스

페이지 이동경로

Kakao i Agent SDK API

Kakao i Agent SDK의 API별 레퍼런스는 다음과 같습니다.

KakaoI

KakaoI는 카카오 i 서비스의 음성 인식을 제공하는 클래스로, SDK 초기화 및 모듈 설정, 음성 인식 초기화 등의 기능을 수행합니다.

KakaoI API
메서드 타입 설명
with KakaoI.Builder Context와 Phase에 대한 정보를 받아 Kakao i Agent SDK를 초기화함
checkAccount void 카카오 i 서비스의 유저 상태, 가입여부 및 약관 동의 여부 확인
- OnCheckCallback: checkAccount의 결과에 따라 후속 처리할 콜백 인터페이스
setEnabled void 음성 인식 기능을 사용하기 전 setEnabled를 통해 헤이카카오를 활성화해야 kakaoIListeningBinder의 음성 인식 기능을 사용할 수 있음
startListen KakaoIListeningBinder 음성 인식에 대해 제어할 수 있는 KakaoIListeningBinder를 생성하고 반환
newEventFactory Service(Implemented) EventRequest를 정의한 API를 가진 Service 인터페이스를 인자로 받아 구현 후 반환
sendEvent void VSC로 전송할 Request에 대한 정보를 담고 있는 RequestBody를 전달받아 KakaoIClient에게 Request를 요청
startSettingActivity void 설정 Activity를 실행하는 메서드
- ErrorHandler: 설정 Activity 실행 중 오류가 발생할 경우 후속 처리를 위한 Handler

KakaoI.StateListener

KakaoI.StateListener 클래스는 음성 인식을 처리할 때, 카카오 i 음성 인식 서비스로부터 변경된 음성 인식 상태 값을 콜백(Callback)으로 전달받는 인터페이스로서 다음의 메서드를 제공합니다.

KakaoI.StateListener
메서드 타입 필수 여부 설명
onPartialResult String 필수 음성 인식 상태가 인식 중일 때 중간 결과를 반환
- 중간 결과는 여러 번 전달됨
onResult String 필수 음성 인식 상태가 인식 중일 때 최종 결과를 반환
- 반환 후 STATE_PROCESSING으로 상태가 변경됨
onStateChanged Integer 필수 음성 인식 상태 변화에 대한 변경 사항을 전달

코드예제onStateChanged 메서드

public void onStateChanged(int state)

onStateChanged(int state)
파라미터 타입 설명
state STATE_DEACTIVATED = 1 꺼져 있는 상태
STATE_IDLE = 2 웨이크업 대기 상태
STATE_RECOGNIZING = 3 음성 인식 중인 상태
STATE_PROCESSING = 4 음성 인식 후 처리 결과를 받기까지의 상태

Sample Code

다음은 KakaoI.StateListener 인터페이스를 구현해서 KakaoIListeningBinder에 Listener로 추가해주는 샘플 코드입니다.

코드예제KakaoI.StateListener

// KakaoI.startListen()으로 초기화를 한 후 사용합니다
private lateinit var kakaoIListeningBinder: KakaoIListeningBinder

fun addListener() {
				...
        kakaoIListeningBinder.addListener(object : KakaoI.StateListener {
            override fun onStateChanged(state: Int) {
                val STATE_DEACTIVATED = 1
                val STATE_IDLE = 2
                val STATE_RECOGNIZING = 3
                val STATE_PROCESSING = 4

                when (state) {
                    STATE_DEACTIVATED -> { ... }
                    STATE_IDLE -> { ... }
                    STATE_RECOGNIZING -> { ... }
                    STATE_PROCESSING -> { ... }
                    else -> { ... }
                }
            }

            override fun onPartialResult(result: String?) {
                // 음성 인식 중 중간 결과를 처리함
            }

            override fun onResult(result: String?) {
                // 음성 인식 후 최종 결과를 처리함
            }
        })
				...   
}

KakaoIListeningBinder

KakaoIListeningBinder 클래스는 음성 서비스를 사용하기 위한 Binder로 음성 인식 관련 기능을 제어하는 인터페이스이며, 다음의 메서드를 제공합니다.

KakaoIListeningBinder
메서드 타입 필수 여부 설명
startListen() void 선택 음성 인식 시작
addListener(KakaoI.StateListener listener) void 선택 KakaoIListeningBinder를 통해 인식된 음성 인식 상태를 알려줄 KakaoI.StateListener를 등록
removeListener(KakaoI.StateListener listener) void 선택 프로퍼티로 넘어간 Listener를 제거
stopListen() void 선택 음성 인식 종료
requestRecognition() void 선택 Wake-up word 없이 바로 음성 인식 시작
stopRecognition() void 선택 음성 인식 종료
- 이미 녹음된 데이터가 존재할 경우, 해당 데이터로 음성 인식이 될 수 있음
isRecognizing() Boolean 선택 음성 인식이 진행 중인지 판단
cancelDialog() void 선택 음성이 입력 중일 경우 음성 인식은 취소되며, 현재 진행 중인 음성 인식 컨텍스트가 있다면 음성 인식을 종료
cancelRecognition() void 선택 음성 인식 취소

Sample Code

다음은 KakaoIListeningBinder를 사용해서 음성 인식 관련 기능을 제어하는 샘플 코드입니다.

코드예제KakaoIListeningBinder

private lateinit var kakaoIListeningBinder: KakaoIListeningBinder

private fun startListen() {
    listeningBinder = KakaoI.startListen(this, kakaoIEventListener)
    listeningBinder?.addListener(kakaoIStateListener)
}

private fun cancelListen() {
    listeningBinder?.cancelRecognition()
}

private fun finishListen() {
    listeningBinder?.stopListen()
    listeningBinder = null
}

// Wake-up-word 없이 바로 음성 인식 시작
private fun requestRecognition() {
    listeningBinder?.requestRecognition()
}

// 음성 인식 종료(이미 녹음된 데이터가 존재할 경우, 해당 데이터로 음성 인식이 될 수도 있음)
private fun stopRecognition() {
    listeningBinder?.stopRecognition()
}

// 음성이 입력 중일 경우 음성 인식은 취소되며, 현재 진행 중인 음성 인식 컨텍스트가 있다면 음성 인식은 종료됩니다.
private fun cancelDialog() {
    listeningBinder?.cancelDialog()
}

KakaoIListenerBinder.EventListener

KakaoIListenerBinder.EventListener 클래스는 음성 서비스 연결 상황에서 발생할 수 있는 이벤트들을 처리하는 인터페이스이며, 다음의 메서드를 제공합니다.

  • 이 클래스는 KakaoI.startListen() 메서드 호출 시, 파라미터 값으로 전달됩니다.
KakaoIListenerBinder.EventListener
메서드 타입 필수 여부 설명
onStartListen() void 필수 음성 인식 시작 시 호출
onStopListen() void 필수 음성 인식 종료 시 호출
onAgreementRequired(KakaoI.IntentSupplier follwingIntentFunc) void 필수 약관 동의가 필요 시 내부 프로퍼티로 약관 동의 URI가 담긴 Intent가 포함됨
onAuthorizeFailed void 필수 인증 실패 시
onError(Exception) void 필수 오류 발생 시
onWithdrawal() void 필수 서비스 탈퇴 시
onMicUnavailable() void 필수 마이크가 사용 불가능 시

Sample Code

다음은 KakaoIListenerBinder.EventListener 인터페이스를 구현해서 KakaoIListeningBinder를 초기화해주는 샘플 코드입니다.

코드예제KakaoIListenerBinder.EventListener

private lateinit var kakaoIListeningBinder: KakaoIListeningBinder

fun startListen() {
        kakaoIListeningBinder =
            KakaoI.startListen(applicationContext, object : KakaoIListeningBinder.EventListener {
                override fun onStartListen() {
						        // 웨이크업 대기 상태 진입
                }

                override fun onWithdrawal() {
						        // 서비스 탈퇴됨
                }

                override fun onAuthorizeFailed() {
						        // 인증 실패
                }

                override fun onStopListen() {
						        // 웨이크업이 안되는 상태 진입 , Microphone 사용하지 않음
                }

                override fun onAgreementRequired(intentSupplier: KakaoI.IntentSupplier) {
						        // 추가 약관 동의가 필요한 상황
                }

                override fun onError(e: java.lang.Exception?) {
						        // 에러 상황
                }

                override fun onMicUnavailable() {
						        // Microphone 사용 불가 에러 상황
                }
            })
    }
}

Module

Module은 Kakao i Agent SDK에 필요한 클래스를 생성해서 전달하는 역할을 수행합니다. SDK에서 내부적으로 사용하는 대부분 클래스를 Module이 제공해주기 때문에 Module이 제공하는 클래스에 대해서 이해하는 것이 중요합니다. SDK를 초기화할 때 필요한 메서드를 재정의 한 모듈 객체를 파라미터로 전달할 수 있습니다.

Kakao i Agent SDK 모듈 초기화 함수
메서드 필수 여부 제공 모듈 설명
provideKakaoIAuth() 필수 카카오 계정 인증 정보를 전달 시 필요
providePackageInfo() 필수 카카오 i 서버로 패키지 정보를 전달 시 필요
provideTemplateHandler() 선택 카카오 i 서버에서 View Template에 대한 레이아웃 정보 전달 시 필요
provideInstructionHandler() 선택 고객사가 사용할 Instruction을 Kakao i Agent SDK에 전달 시 필요
안내
Module 기능을 개발의 맞춤형으로 수정하거나 더 많은 기능을 사용해야 하는 경우, 카카오 i 담당자에게 문의하시기 바랍니다.
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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