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)으로 전달받는 인터페이스로서 다음의 메서드를 제공합니다.
메서드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
onPartialResult | String | 필수 |
음성 인식 상태가 인식 중일 때 중간 결과를 반환 - 중간 결과는 여러 번 전달됨 |
onResult | String | 필수 |
음성 인식 상태가 인식 중일 때 최종 결과를 반환 - 반환 후 STATE_PROCESSING으로 상태가 변경됨 |
onStateChanged | Integer | 필수 |
음성 인식 상태 변화에 대한 변경 사항을 전달 |
코드예제onStateChanged 메서드
public void 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로 음성 인식 관련 기능을 제어하는 인터페이스이며, 다음의 메서드를 제공합니다.
메서드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
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()
메서드 호출 시, 파라미터 값으로 전달됩니다.
메서드 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
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 담당자에게 문의하시기 바랍니다.