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

페이지 이동경로

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
}
KIRecognitionType
필드 설명
음성 인식 타입 열거형
voice 목소리를 인식하는 상태
music 음악을 인식하는 상태

KIRecognizerState

음성 인식 상태 열거형입니다.

// 음성 인식 상태 열거형입니다.
@objc public enum KIRecognizerState: Int {
	case idle
	case awaken
	case recognizing
	case processing
}
KIRecognizerState
필드 설명
음성 인식 타입 열거형
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()
		}
	}
}
KIAudioPlayerInfo
필드 설명
음악 또는 오디오의 재생 상태 및 정보(타입: 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"
        }
    }
}
KIAudioPlayState
필드 설명
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?
}
KIAudioPlayerRenderInfo
필드 설명
음악 또는 오디오 콘텐츠의 정보를 표시(타입: 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를 반드시 구현해야 합니다.

KakaoIDelegate
필드 필수 여부 설명
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의 사용 여부를 알림
- 뷰 템플릿을 통해 보여줄 데이터를 제공
- shouldDisplayRenderItemForBodybodyJson은 동일값이며 타입만 다름
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)를 제공합니다.

KakaoI 주요 변수
필드 설명
delegate KakaoIDelegate 객체(타입: KakaoIDelegate?)
authDelegate 인증 관련 Delegate 객체(타입:KakaoAuthDelegate?)
recognizerState 현재 음성 인식 상태(타입: KIRecognizerState)
audioPlayerInfo 음악 또는 오디오의 재생 상태(타입:KIAudioPlayerInfo)
isConnected 다운스트림의 연결 상태(타입: Bool)
isRunning 카카오 i 음성 인식 서비스의 활성 상태(타입: Bool)
settingsViewController 모앱에서 카카오 i 설정 화면을 보여줄 때 사용하는 UIViewController(타입: UIViewController)
- static으로 제공됨
KakaoI 메서드
메서드 필수 여부 설명
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에서 사용하는 토큰
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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