API 레퍼런스
Kakao i SDK for iOS(이하 SDK)는 메인 인터페이스와 Delegate를 통해 API를 제공합니다. SDK가 제공하는 Delegate를 구현하여 SDK 내부에서 발생한 이벤트 및 결과 데이터를 전달받을 수 있습니다.
표 API 레퍼런스구분 | 설명 |
---|---|
KakaoI | SDK의 메인 클래스로 해당 클래스를 통해 주요 기능을 제공 - KakaoI 클래스는 shared 싱글톤 객체를 통해 접근ex) KakaoI.shared.[호출하고자 하는 함수명] |
KakaoIDelegate | 클라이언트와 SDK의 주요 인터랙션을 담당하는 Delegate - iOS 플랫폼에서 SDK를 사용하는 모앱(클라이언트)은 반드시 구현 필요 |
KakaoAuthDelegate | 카카오 i 사용을 위한 인증 관련 Delegate - 액세스 토큰과 관련된 로직 - iOS 플랫폼에서 SDK를 사용하는 모앱(클라이언트)은 반드시 구현 필요 |
KIPhoneCallInterfaceDelegate | 전화 걸기 기능을 제공하는 Delegate - iOS 플랫폼에서 전화걸기 기능을 구현하는 모앱(클라이언트)은 반드시 구현 필요 |
KITemplateInterfaceDelegate | View Template(뷰 템플릿)을 통해 UI를 보여주는 기능을 제공하는 Delegate - iOS 플랫폼에서 SDK의 기본 View Template을 구현하는 모앱(클라이언트)은 반드시 구현 필요 |
Custom Type
Custom Type은 SDK 내에서 사용되는 사용자 정의 자료형입니다. 해당 자료형들은 API 통신 중 이용될 수 있습니다.
KIRecognitionType
음성 인식 타입 열거형입니다.
// 음성 인식 타입 열거형입니다.
@objc public enum KIRecognitionType: Int {
case voice
case music
}
필드 | 설명 |
---|---|
음성 인식 타입 열거형 | |
voice | 목소리를 인식하는 상태 |
music | 음악을 인식하는 상태 |
KIRecognizerState
음성 인식 상태 열거형입니다.
// 음성 인식 상태 열거형입니다.
@objc public enum KIRecognizerState: Int {
case idle
case awaken
case recognizing
case processing
}
필드 | 설명 |
---|---|
음성 인식 타입 열거형 | |
idle | 활성화되었으나 음성 인식은 하고 있지 않은 상태 |
awaken | 음성 인식이 시작되어, 서버에서 해당 음성 인식을 검증하는 상태 |
recognizing | 현재 음성 인식이 진행 중인 상태 |
processing | 인식된 음성을 처리 중인 상태 |
KIAudioPlayerInfo
음악 또는 오디오의 재생 상태 및 정보를 의미합니다.
// 음악 또는 오디오의 재생 상태 및 정보를 의미합니다.
@objc public class KIAudioPlayerInfo: NSObject {
public var playerItemId: String?
public var state: KIAudioPlayerState
public var hasNextTrack: Bool
public var metaData: KIAudioPlayerRenderInfo?
public var playChanngel: String
public var renderInfo: KIAudioPlayerRenderInfo? {
didSet {
KakaoI.shared.updateNowPlayingInfo()
}
}
}
필드 | 설명 |
---|---|
음악 또는 오디오의 재생 상태 및 정보(타입: NSObject) | |
playerItemId | playerItem을 식별하기 위한 식별자(타입: String?) |
state | 오디오 플레이어의 상태(타입: KIAudioPlayState) |
hasNextTrack | 다음 트랙의 존재 유무(타입: Bool) |
true : 다음 트랙이 존재할 경우 |
|
false : 다음 트랙이 존재하지 않는 경우 |
|
metaData | VSC(Voice Service Controller)에 대한 메타 데이터(타입: KIAudioPlayerRenderInfo?) |
playChannel | 오디오 재생 채널명(타입: String) |
renderInfo | 오디오 플레이 렌더링에 필요한 정보(타입: KIAudioPlayerRenderInfo?) |
KIAudioPlayState
Kakao i 서버의 오디오 상태 열거형입니다.
@objc public enum KIAudioPlayState: Int {
case idle
case playing
case paused
case finished
case stopped
internal var description: String {
switch self {
case .idle:
return "IDLE"
case .playing:
return "PLAYING"
case .paused:
return "PAUSED"
case .finished:
return "FINISHED"
case .stopped:
return "STOPPED"
}
}
}
필드 | 설명 |
---|---|
AudioPlayState에 대한 문자열 설명 | |
idle | 활성화되어있으나 작업하고 있지 않은 상태 |
playing | 오디오가 송출 중인 상태 |
paused | 일시 정지 상태 |
finished | 오디오 송출을 완료한 상태 |
stopped | 정지 상태 |
KIAudioPlayerRenderInfo
음악 또는 오디오 콘텐츠의 정보를 표시합니다.
// 음악 또는 오디오 콘텐츠의 정보입니다.
public class KIAudioPlayerRenderInfo: NSObject {
public let image: String?
public let title: String?
public let subtitle: String?
public let controllable: [String]?
public let source: String?
public var offset: NSNumber?
public let duration: NSNumber?
}
필드 | 설명 |
---|---|
음악 또는 오디오 콘텐츠의 정보를 표시(타입: NSObject) | |
image | 썸네일 이미지(타입: String?) |
title | 제목(타입: String?) |
subtitle | 부제목(타입: String?) |
controllable | 지원하는 컨트롤 목록(타입: [String]?) |
PLAY : 재생 |
|
STOP : 중지 |
|
PAUSE : 일시 정지 |
|
RESUME : 다시 재생 |
|
NEXT : 다음 콘텐츠 |
|
PREV : 이전 콘텐츠 |
|
source | 정산 로그 전송을 위한 출처(타입: String?) |
offset | 해당 콘텐츠의 현재 위치를 표시(타입: NSNumber?) |
duration | 곡의 길이(타입: NSNumber?) |
KakaoIDelegate
KakaoIDelegate
는 Kakao i Agent SDK의 주요 Delegate입니다. 카카오 i 음성 인식 서비스를 사용하는 모앱은 이 Delegate를 반드시 구현해야 합니다.
필드 | 필수 여부 | 설명 |
---|---|---|
kakaoIVoiceServiceReady() | 필수 |
다운스트림(Downstream)의 연결을 알림 - DownStream: SDK와 통신하는 서버와의 연결 채널 - SDK가 서버로부터 응답받을 준비가 완료됨 |
kakaoIVoiceServiceDisconnected() | 필수 |
다운스트림의 해제를 알림 - 다운스트림 해제 시, SDK가 서버로부터 응답받을 수 없음 |
kakaoIServiceUserLeft() | 필수 |
사용자가 카카오 i 음성 인식 서비스 탈퇴 시 알림 |
kakaoIServiceEnabled(enabled:) | 필수 |
Kakao i 음성 인식 서비스의 사용 설정 여부 변경 시 알림 |
enabled (필수 ): Bool- 카카오 i 음성 인식 서비스 활성화 여부 |
||
true : 활성화 상태 |
||
false : 비활성 상태 |
||
KakaoIAIID() → String? | 선택 |
AIID(AI Instance ID)를 가지고 있는 모앱은 AIID를 반환함 - AIID: 카카오 i 음성 인식 서비스를 사용하는 입/출력 장치의 Endpoint ID로서 각 인스턴스를 구별하는 식별자 |
kakaoISpeakReceiveText(text:) | 선택 |
답변 내에 텍스트가 들어있는 경우 전달 |
text (필수 ): String- 답변과 함께 전달된 텍스트 |
||
kakaoIUserVoiceRecognizing(string:) | 필수 |
사용자의 발화를 실시간으로 전달 |
string (필수 ): String- 사용자 발화를 실시간으로 인식한 문자열 |
||
kakaoIUserVoiceRecognized(string:) | 필수 |
최종으로 감지한 사용자 발화를 전달 |
string (필수 ): String- 사용자 발화를 최종적으로 인식한 문자열 |
||
kakaoITemplateRender(shouldDisplay RenderItemForBody:,bodyJson:) |
선택 |
TemplateRender Instruction으로 Kakao i Template의 사용 여부를 알림 - 뷰 템플릿을 통해 보여줄 데이터를 제공 - shouldDisplayRenderItemForBody 와 bodyJson 은 동일값이며 타입만 다름 |
shouldDisplayRenderItemForBody ( 필수 ):[String: Any]- JSON을 Dictionary 형태로 제공 |
||
bodyJson (필수 ): String- JSON을 String 형태로 제공 |
||
kakaoIRecognizerStateChanged(type: ,oldState:,newState:,wakenByWakeWord:) |
선택 |
음성 인식 상태 값이 변경되었을 때 호출 - 추가로 현재 인식 중인 소리의 타입을 제공 |
type (필수 ): KIRecognitionType- 현재 인식 중인 소리의 타입 |
||
oldState (필수 ): KIRecognizerState- 변경 이전의 음성 인식 상태 |
||
newState (필수 ): KIRecognizerState-변경 이후의 음성 인식 상태 |
||
awakenByWakeWord (필수 ): Bool- 호출명령어를 통한 상태 변화 여부 |
||
true : 호출명령어 인식 상태 |
||
false : 호출명령어 미인식 상태 |
||
kakaoIAudioPlayerInfoChanged(oldInfo:, newInfo:) |
필수 |
신규 오디오 재생 정보가 있거나 오디오 상태 변경 시 호출 |
oldInfo (선택 ): KIAudioPlayerInfo- 변경 이전의 오디오 재생 정보 |
||
newInfo (선택 ): KIAudioPlayerInfo- 변경 이후의 오디오 재생 정보 |
||
kakaoIAudioPlayFinished() | 선택 |
AudioPlayState가 Finished 상태이고 추가로 재생할 오디오가 큐(Queue)에 존재하지 않을 때 호출 |
kakaoISpeakStarted() | 선택 |
카카오 i 서버가 음성 출력 시작 시 호출 |
kakaoISpeakFinished() | 선택 |
카카오 i 서버가 음성 출력 종료 시 호출 |
kakaoIAudioPlayerCurrentTime Reported(currentTime:,duration:) |
선택 |
카카오 i 서버가 재생 중인 오디오의 현재 재생 시간을 일정 간격마다 알림 - 추가로 현재 재생 중인 오디오의 총 재생 시간도 함께 제공 |
currentTime (선택 ): Double- 오디오의 현재 진행 시간 |
||
duration (선택 ): Double- 오디오의 총 길이 |
||
kakaoIAverageAudioLevelChanged(level:) | 선택 |
음성 녹음 평균 레벨의 값을 0.1초 간격으로 알림 |
level (필수 ): Float- 음성 녹음 레벨 - level: 0~1 사이의 값 |
||
kakaoIAudioLevelChanged(level:) | 선택 |
음성 녹음 실시간 레벨의 값을 0.1초 간격으로 알림 |
level (필수 ): Float- 실시간 음성 녹음 레벨 - level: 0~1 사이의 값 |
||
kakaoILiveStreamingLoadingView(_ isShowing:) | 선택 |
라이브 스트리밍 중인 오디오 버퍼링의 시작/종료를 알림 |
isShowing(필수 ): Bool- 로딩 완료 여부 |
||
true : 로딩 완료 상태 |
||
false : 로딩 미완료 상태 |
||
kakaoIAccessTokenExpired() | 필수 |
액세스 토큰이 만료되었을 때 호출 - 클라이언트에서 필요 시 액세스 토큰 갱신 필요 |
kakaoIValidateAccessToken(completion:) | 선택 |
액세스 토큰 만료 여부 확인 - 앱이 Suspended 상태에서 백그라운드 상태로 깨어날 때 사용되며 포그라운드에서는 호출되지 않음 |
completion(필수 ): @escaping (_ expiresInMillis: NSNumber?,_error: Error?) → Void)- 세션 유효 기간을 전달, 에러 발생 시 함께 전달 |
||
expiresInMillis(필수 ): NSNumber?- 세션의 유효 기간 |
||
error(필수 ): Error? → Void- 에러 존재 시 전달 |
||
kakaoIUpdateRequired() | 필수 |
SDK 업데이트가 필요할 때 호출 |
kakaoIAgreementRequired() | 필수 |
SDK 약관이 변경 또는 추가되어 관련 동의가 필요 시 호출 |
kakaoIUserNotFound() | 필수 |
등록되지 않은 사용자로 판단이 될 때 호출 |
kakaoIInvalidAiid() | 필수 |
등록되지 않은 AIID로 판단이 될 때 호출 |
kakaoILoginRequested() | 선택 |
비로그인 모드를 지원하는 모앱에서 카카오 i 로그인 요청 |
KakaoI
KakaoI
클래스는 메인 인터페이스이며 싱글톤 객체(shared)를 제공합니다.
필드 | 설명 |
---|---|
delegate | KakaoIDelegate 객체(타입: KakaoIDelegate?) |
authDelegate | 인증 관련 Delegate 객체(타입:KakaoAuthDelegate?) |
recognizerState | 현재 음성 인식 상태(타입: KIRecognizerState) |
audioPlayerInfo | 음악 또는 오디오의 재생 상태(타입:KIAudioPlayerInfo) |
isConnected | 다운스트림의 연결 상태(타입: Bool) |
isRunning | 카카오 i 음성 인식 서비스의 활성 상태(타입: Bool) |
settingsViewController | 모앱에서 카카오 i 설정 화면을 보여줄 때 사용하는 UIViewController(타입: UIViewController) - static으로 제공됨 |
메서드 | 필수 여부 | 설명 |
---|---|---|
setEnabled(enabled:, completion:) | 선택 |
카카오 i 음성 인식 서비스의 사용 여부 설정 |
enabled (필수 ): Bool- SDK 활성 여부 |
||
true : SDK 활성 상태 |
||
false : SDK 비활성 상태 |
||
completion (선택 ): ((Bool)→Void)?- 활성 여부 결과를 전달하는 코드 블록 |
||
start(anonymous:, completion:) | 선택 |
카카오 i 음성 인식 서비스를 시작 - 인증 후 다운스트림을 연결하고 웨이크업 대기 상태로 진입 |
anonymous (필수 ): Bool- 익명 로그인 여부 |
||
true : 익명으로 로그인 |
||
false : 일반 로그인 |
||
completion: (필수 ):@escaping([Error]?) → Void - 서비스를 사용 안 함으로 설정하거나, 가입 여부 확인 시 에러가 발생한 경우 에러를 함께 리턴 |
||
clearProperties() | 선택 |
카카오 i 음성 인식 서비스의 환경 설정값을 초기화 |
shutdown(logout:, completion:) | 선택 |
카카오 i 음성 인식 서비스를 종료 |
logout (필수 ): Bool- 로그아웃 여부 |
||
true : 로그아웃과 함께 서비스를 종료 |
||
false (기본값): 로그아웃없이 서비스만 종료 |
||
completion: (선택 ): (() → Void)?셧다운 이후에 실행되는 코드 블록 |
||
clearNowPlayingInfo() | 선택 |
현재 재생 중인 오디오의 정보를 초기화 |
startRecognition() | 선택 |
웨이크업을 통하지 않고 바로 음성 인식을 실행 ex) 버튼을 통한 음성 인식 진행 |
stopRecognition() | 선택 |
음성 인식을 중단 |
clearCache() | 선택 |
캐시를 비울 때 사용 |
cancelDialog() | 선택 |
현재 진행 중인 다이얼로그 취소 - 대화 세션이 삭제되고 이 대화에 대한 추가 인스트럭션을 무시 |
cancelRecognition(isUserInteraction:) | 선택 |
인식 중이던 음성 세션을 닫고 취소 신호를 전송 |
isUserInteraction (필수 ): Bool- 사용자의 인터랙션으로 인한 취소 여부 |
||
true : 취소 상태 |
||
false : 취소되지 않은 상태 |
||
cancelRecognitionAndAudio() | 선택 |
인식 중인 음성 세션을 닫고 취소 신호를 전송 - 모든 소리 출력을 중단 |
isExpectSpeechPending() | 선택 |
현재 동작 이후 카카오 i 서버가 추가 음성 입력을 받을지 여부 알림 |
requestPauseWakeup() | 선택 |
웨이크업 사용을 중지 |
requestResumeWakeup() | 선택 |
웨이크업 사용을 재개 |
stopAllActions() | 선택 |
현재 실행 중인 음성 명령 및 오디오 출력 즉시 중지 |
willPlayAudio() | 선택 |
모앱(클라이어트)이 사운드 재생을 시작하고자 할 때 호출 |
didEndPlayAudio() | 선택 |
모앱(클라이어트)이 사운드 재생을 끝냈을 때 호출 |
KakaoAuthDelegate
카카오 i 사용을 위한 인증 관련 Delegate입니다.
표KakaoAuthDelegate메서드 | 필수 여부 | 설명 |
---|---|---|
KakaoIAcessToken() → String? | 필수 |
SDK로부터 액세스 토큰을 리턴(타입: String?) - 카카오 i 음성 인식 서비스를 시작 전에 액세스 토큰 갱신 권고 |
KakaoIAcessToken() → String? | 필수 |
SDK로부터 액세스 토큰을 리턴(타입: String?) - 카카오 i 음성 인식 서비스를 시작 전에 액세스 토큰 갱신 권고 |
KakaoIAppUserID() → Int? | 필수 |
SDK로부터 App User ID를 리턴(타입: Int?) |
KIPhoneCallInterfaceDelegate
전화 걸기 관련 기능을 사용하기 위해 구현이 필요한 Delegate입니다.
표KIPhoneCallInterfaceDelegate메서드 | 필수 여부 | 설명 |
---|---|---|
contactAccessDenied() | 필수 |
주소록 접근 권한이 없는 경우 호출됨 |
selectPhoneNumber(_ candidates:[(index: Int, name: String, phoneNumber: String?)]) |
필수 |
검색 결과 연락처를 터치한 경우 호출됨 |
candidates (필수 ): Object- 터치한 행의 연락처 관련 항목 - 연락처 후보군으로 다음 항목을 전달 |
||
index (필수 ): Int- 후보군의 인덱스 |
||
name (필수 ): String- 연락처에 등록된 후보군의 이름 |
||
phoneNumber (선택 ): String?- 연락처에 등록된 후보군의 번호 |
KITemplateInterfaceDelegate
UI Template(View Template) 기능을 사용하기 위해 구현이 필요한 Delegate입니다.
표KITemplateInterfaceDelegate메서드 | 필수 여부 | 설명 |
---|---|---|
templateRenderReceived(token:,template:, body:,bodyJson:) |
필수 |
화면에 표시할 렌더링 데이터 반환 |
token (선택 ): String?- SDK에서 사용하는 토큰 |
||
template (필수 ): KITemplateRenderObject- TemplateRenderObject 인스턴스 |
||
body (필수 ): [String: Any]- JSON을 Dictionary 형태로 제공 |
||
bodyJson (필수 ): String- JSON을 String 형태로 제공 |
||
templateCloseReceived(token:) | 필수 |
클라이언트가 표시 중인 템플릿을 닫도록 알림 |
token (선택 ): String?- SDK에서 사용하는 토큰 |