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

페이지 이동경로

벤더 인터페이스 연동

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

안내
벤더 인터페이스의 명명 방법, 설계 방법 및 Skill 구성 등의 자세한 내용은 Service Agent Interface 문서를 참고하시기 바랍니다.
Kakao 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.CustomActionVendor.Company.Group.ScreenState의 사용 예제입니다.

코드예제Vendor.Company.Group

		@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 초기화 시, 벤더 인터페이스 클래스를 moduleprovideInstructionHandlers에 오버라이드합니다.

  • 벤더 인터페이스가 1개 이상일 경우에는 리스트로 구성하여 작성합니다.

코드예제클래스 등록

KakaoI.with(this)
             .module(object : Module() {
 
                 ...
 
                 override fun provideInstructionHandlers(context: Context): List<Any> {
                     return listOf(
                         MyComponent1()
                     )
                 }
             })
             .init()

Event 등록

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

어노테이션 구성
어노테이션 설명
@EventRequest Request에 들어갈 namespacename을 지정
@BodyParam Event 바디에 들어갈 파라미터를 설정
  1. 다음 Event 구성을 참고하여 namespacename에 파라미터를 입력합니다.

    코드예제@EventRequest

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

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

    코드예제KakaoI.newEventFactory()

    companion object {
           val API_FACTORY = KakaoI.newEventFactory(API::class.java)!!
       }
    

  3. KakaoI.sendEvent() 메서드를 호출하여 Event를 전송합니다.

    코드예제KakaoI.sendEvent()

    KakaoI.sendEvent(API_FACTORY.newEmotionChanged("Happy"))
    

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.