벤더 인터페이스 연동

벤더 인터페이스(Vendor Interface)란 Kakao i agent Virtual Service(KVS)에서 제공하는 인터페이스 이외에 클라이언트가 독자적으로 추가 구현할 수 있는 인터페이스입니다. 카카오 i 인터페이스의 기본 구성 요소인 Event, Instruction, State를 이용하여 KVS가 아닌 독자적인 Skill을 구성하고 다양한 기능들을 확장할 수 있습니다.

안내
벤더 인터페이스의 명명 방법, 설계 방법 및 Skill 구성 등의 자세한 설명은 Service Agent Interface 문서를 참고하시기 바랍니다.

표카카오 i 인터페이스 구성

프로토콜	필수 여부	설명
Event	`선택`	클라이언트에서 KVS로 보내지는 일련의 명령들
Instruction	`필수`	KVS에서 클라이언트로 보내지는 일련의 명령들
State	`필수`	클라이언트 구현체의 현재 상태를 서버에 고지하기 위해 마련된 장치 - Interface에 매우 종속적이며, Event 전송 시 매번 전송됨

클래스 구성

벤더 인터페이스를 Kakao i Agent SDK에 등록하기 위해 @Division, @Handle, @StateProvider 어노테이션(Annotation)을 클래스에 구성합니다. 어노테이션 구성 방법은 다음과 같습니다.

표어노테이션 구성

어노테이션	설명
@Division	정의된 벤더 인터페이스의 이름과 버전 정보를 명시 - 이름: 벤더 인터페이스의 Name Space - 버전: Skill 서버와 Capability 제어 시 사용되는 정보
@Handle	벤더 인터페이스의 이름과 버전명을 제외한 인스트럭션 이름을 명시 - 메서드 바디에 비지니스 로직을 구현함으로써, SDK에서 Skill 서버에서 보낸 인스트럭션 수신 시 해당 어노테이션이 달린 메서드가 실행되어 인스트럭션이 처리됨 - 메서드 프로퍼티에 String을 넣을 경우 JSON String을 받을 수 있고, 모델 객체를 넣을 경우 JSON String을 해당 모델로 파싱하여 전달받을 수 있음
@StateProvide	벤더 인터페이스의 이름과 버전 정보를 제외한 상태 이름을 명시 - Event가 Skill 서버로 전달 시 현재 클라이언트의 상태도 함께 전달됨 - 전달되어야 할 모델을 리턴하고, 해당 모델은 com.kakao.i.message.Body를 상속받은 객체이며, Gson을 통해 JSON String으로 변환됨

Sample Code

다음은 인스트럭션 Vendor.Company.Group.CustomAction과 Vendor.Company.Group.ScreenState의 사용 예제입니다.

코드예제Vendor.Company.Group

Kotlin

		@Division(value = "Vendor.Company.Group", version = "1.0")
    class MyComponent1 {
        @Handle("CustomAction")
        fun handleCustomAction(action: CustomAction) {
            ...
        }

       @StateProvide("ScreenState")
       open fun provideScreenState(): ScreenStateBody {
           return ScreenStateBody()
       }
    }

클래스 등록

다음 예제 코드를 참고하여 SDK 초기화 시, 벤더 인터페이스 클래스를 module의 provideInstructionHandlers에 오버라이드합니다. 벤더 인터페이스가 한 개 이상일 경우에는 리스트로 구성하여 작성합니다.

코드예제클래스 등록

Kotlin

KakaoI.with(this)
             .module(object : Module() {

                 ...

                 override fun provideInstructionHandlers(context: Context): List<Any> {
                     return listOf(
                         MyComponent1()
                     )
                 }
             })
             .init()

Event 등록

Event는 Kakao i Agent SDK가 카카오 i 서버로 메시지를 전달하는 인터페이스로서, Event 등록 시 @EventRequest가 사용됩니다. Event 구성할 때 사용되는 어노테이션은 다음과 같습니다.

표어노테이션 구성

어노테이션	설명
@EventRequest	Request에 들어갈 `namespace`와 `name`을 지정
@BodyParam	Event Body에 들어갈 파라미터를 설정

다음 Event 구성을 참고하여 namespace와 name에 파라미터를 입력합니다. 코드예제@EventRequest

Kotlin

interface API {
   @EventRequest(namespace = "Vendor.Company.Group", name = "EmotionChanged")
   RequestBody newEmotionChanged(@BodyParam("emotion") String emotion);
}

EventFactory 생성을 위해 KakaoI.newEventFactory() 메서드를 호출합니다.

코드예제KakaoI.newEventFactory()
Kotlin
```
companion object {
       val API_FACTORY = KakaoI.newEventFactory(API::class.java)!!
   }
```
KakaoI.sendEvent() 메서드를 호출하여 Event를 전송합니다.

코드예제KakaoI.sendEvent()
Kotlin
```
KakaoI.sendEvent(API_FACTORY.newEmotionChanged("Happy"))
```

kakaoIdocumentation

Kakao i Agent SDK::Android::벤더 인터페이스 연동

페이지 이동경로

벤더 인터페이스 연동

클래스 구성

Sample Code

클래스 등록

Event 등록