일반사항 - GiGAGenie-ServiceSDK/UserGuide GitHub Wiki

공통 사항

모든 API는 callback 방식으로 호출 결과를 전달한다. 다음과 같이 호출한다.

  • gigagenie.[영역].[함수](함수파라미터, callback)으로 호출한다.
  • [영역] 은 API 를 Grouping 하는 단위로 이후 namespace 로 설명한다.
  • callback 함수는 다음과 같이 정의 된다.
    • function callback(result_cd,result_msg,extra)
      • result_cd: 결과 코드, 숫자
      • result_msg: 결과 메시지, 문자
      • extra : 호출 결과로 전달되는 데이터들(Javascript Object)
        • 각각의 API 에 따라서 전달되는 데이터가 다르다.
        • 예: getSelectedIndex 의 경우 extra 에 selected 라는 숫자 값이 설정되어 전달된다.

NameSpace

API는 Javascript Object 로 제공된다. Javascript Object를 가져오기 위해서는 HTML 에 다음을 Embed해야 한다.

   <script type="text/javascript" src="https://svcapi.gigagenie.ai/sdk/v1.0/js/gigagenie.js">
  • HTML에 embed 하면 gigagenie 객체를 이용 가능하다.
    • 함수 호출은 gigagenie.[영역].[함수명](파라미터) 로 실행한다.
    • 호출 예: gigagenie.voice.getVoiceText("안녕 기가지니",null,callback)

Container App 에서 3rd Party 앱 실행

GiGA Genie 에서 사용자가 3rd Party 앱을 이용하고자 할 경우 다음의 절차로 3rd Party 앱을 실행(3rd Party URL 로 Container App 에서 브라우징)한다.

2.3

사용자는 “기가지니 [발화]” 를 이용해서 3rd Party App 을 실행한다. 음성인식 이후 발화는 3rd Party 앱 실행을 위한 발화인지 확인(해석)되며 실행 대상 AppID 를 확인한다. 유효한 AppID 일 경우 해당 AppID 에 등록된 3rd Party 웹의 baseURL + ActionPath 를 Container App 에서 로딩, 화면에 출력하는 형태로 실행 된다. 이때, 발화에서 생성한 파라미터를 GET Parameter 방식으로 전달한다.

웹 URL 구성 방법

'Container App 에서 3rd Party 앱 실행' 에서 설명한 것처럼 3rd Party 웹 로딩은 baseURL + ActionPath 를 조합한 URL 을 로딩한다. 그리고 HTML 태그 상에서 링크(href), 소스(src)는 baseURL 기준으로 해석된다. 다음은 3rd Party 가 등록한 appid 의 예이다.

2.4

'Container App 에서 3rd Party 앱 실행' 의 발화 확인 시 대상 appid 가 TEST0001 이고 Action 이 QueryTest1 이면 ContainerApp 은 baseURL+ActionPath 조합인 https://test.com/app/test1.jsp 를 로드하며 GET Parameter 로 발화 확인된 파라미터를 전달한다. 따라서 발화 개발 시에 파라미터를 받도록 하였으면 https://test.com/app/test1.jsp?key=value&amp;key=value 형태로 전달 받도록 URL 을 구성해야 한다.

링크, 소스 태그의 경로 설정 방법

Container App 에서 3rd Party 웹서버로 접근할 때, 링크(href), 소스(src) 태그의 경우 절대 경로를 사용해야 한다. Container App 에서는 3rd Party 웹서버에 접근 할 때, baseURL 을 기준으로 링크, 소스를 Access 하기 때문에, 상대 경로를 사용하면 해당 리소스가 접근이 안될 수 있다.

  • 잘못된 설정 예: baseurl 이 http://example.com 이고 해당 action URL 이 /gigagenie/index.html 일 경우 index.html 에 다음의 코드가 들어갔을 경우 해당 URL 을 참조할 수 없게 된다.

      <link href="../css/style.css" rel="stylesheet">
  <script src="../js/jquery-min.js"></script>

  • 바람직한 설정 예 : 상기 링크, 소스 태그를 baseurl 로부터의 절대 경로로 지정해야 한다.

     <link href="/css/style.css" rel="stylesheet">
 <script src="/js/jquery-min.js"></script>

음성 이벤트의 동작 방식

음성 이벤트 수신은 다음의 Voice API 의 Callback 으로 전달하며, API 에 따라 동작 방식과 전달 데이터가 다르다.

  • 음성인식 API ( gigagenie.voice.getVoiceText )

    • 음성 인식 API 는 gigagenie.voice.getVoiceText 호출 이후 해당 함수에등록한 callback 에 음성인식 결과가 전달된다.

    • 동작 Flow :

      2.6.01

  • 음성명령수신 API (gigagenie.voice.onVoiceComand)

    • 음성 명령 수신 API 는 gigagenie.voice.onVoiceCommand 에 callback 함수를 등록하면 callback 에 명령 수신 결과를 전달한다.

    • 사용자의 인식 특정 발화(기가지니, 지니야, 친구야, 자기야) 이후 특정명령에 대한 발화(다음페이지, 이전페이지) 발생시 callback 에 관련 결과를전달한다.
    • 사용자 발화로 음성 인식이 개시한다.
    • 동작 Flow :

      2.6.02

  • 음성선택번호수신 API (gigagenie.voice.onSelectedIndex)

    • 음성선택번호 수신 API 는 gigagenie.voice.onSelectedIndex 에 callback 함수를 등록하면 callback 에 명령 수신 결과를 전달한다.

    • 사용자의 인식 특정 발화(기가지니, 지니야, 친구야, 자기야) 이후 번호를발화하면 callback 에 발화한 번호를 전달한다.
    • 사용자 발화로 음성 인식이 개시한다.
    • 동작 Flow :

      2.6.03

  • Action 수신 API (gigagenie.voice.onActionEvent)

    • Action 수신 API 는 gigagenie.voice.onActionEvent 에 callback 함수를등록하면 callback 에 명령 수신 결과를 전달한다.

    • 3rd Party 가 대화 SDK 에서 생성한 대화 모델에 포함되는 발화에 대해, 현재 해당 3rd Party App 을 실행 중 일 때 JavaScript Callback 함수를 호출한다.
      • 3rd Party App 이 현재 실행 중이지 않을 경우 등록한 baseURL + Path로 Container App 을 실행한다.

      • 현재 3rd Party App 이 실행 중이고, 3rd Party App 에서 onActionEventCallback 을 구현하지 않을 경우 해당 발화가 발생하면 등록한 baseURL + Path 로 이동한다.

      • 현재 실행중인 3rd Party App 과 발화로 실행되어야 하는 3rd Party App이 다를 경우 현재 실행중인 3rd Party App 을 중지하고 발화로실행되어야 할 3rd Party App 을 실행한다.
    • 사용자 발화로 음성 인식이 개시된다.
    • 동작 Flow :
      • 3rd Party App 이 현재 실행 중이고 Callback 함수를 설정한 경우

        2.6.04

      • 3rd Party App 이 현재 실행 중이고 Callback 함수를 설정하지 않은 경우

        2.6.05

      • 3rd Party App 이 실행중이지 않은 경우

        2.6.06

화면 해상도 설정

3rd Party 화면은 1920 x 1080 으로 표시된다. HTML에 아래 Meta Tag를 등록해야 정상적으로 보여진다.

   <meta name="viewport" content="height=1080, width=1920, user-scalable=no" />

URL 호출 시 Parameter로 전달되는 값

  • 화자식별 발화 정보

    • 음성명령 호출시, 화자 인식된 정보는 인식된 사용자의 ContainerID가 GET Parameter로 전달된다. GET Parameter는 voiceid 이다. 화자 식별이 등록되어 있지 않으면 “NONE”으로 화자 식별이 인식이 안된 경우 “UNKNOWN”이 전달된다.

  • 사용자 발화 문구

    • 음성명령 호출 시 사용자가 발화한 문구가 GET Parameter로 전달된다. Get Parameter는 uword 이다. 발화로 진입한 경우가 아니면 “NONE”이 전달된다.

API 권한 확인

결제 API 등 일부 API는 KT와 관련 제휴(CP 등록 등)를 맺은 AppId만 호출 가능하다. 권한이 없는 AppId에서 해당 API를 호출하면 result_cd는 401, result_msg는 “Unauthorized” 가 발생한다.

다음은 권한이 필요한 API와 권한 Group 이다.

2.9.01

TTS 시작-종료 관련

TTS는 sendTTS 또는 getVoiceText에 의해서 시작되고 stopTTS 에 의해서 종료될 수 있다. 또는 3rd Party App 과 관계 없이 사용자가 “기가지니”와 같은 KWS(Key Word Spotting)의 질의 응답, 또는 전화가 왔을 경우 등에 따라 외부 요인에 따라 종료될 수 있다.

  • TTS 시작-중지-재시작 관련
    sendTTS 로 TTS 재생시 sendTTS를 호출하게 되면 기존 sendTTS의 callback에는 result_cd에 오류코드가 전달되고 기존 TTS는 정지한다. 그리고 새로 호출한 sendTTS의 내용에 의해 TTS가 재생된다. 이는 getVoiceText 에서 TTS를 재생할 때도 동일하게 적용된다. 즉 getVoiceText의 TTS 재생시 getVoiceText를 호출하면 기존 TTS는 정지되고 처음 호출한 getVoiceText의 콜백에는 result_cd에 오류코드가 전달된다. getVoiceText 호출 이후 sendTTS 호출, 또는 sendTTS 호출 이후 getVoiceText를 호출 하는 경우도 동일하다.
    getVoiceText 시 TTS가 재생되고 음성인식 대기 상태로 있는 경우 getVoiceText 또는 sendTTS를 다시 호출하면 음성인식이 중지되고 getVoiceText 또는 sendTTS가 시작된다.

  • 외부에 의한 TTS 중지
    sendTTS와 getVoiceText 로 TTS 재생시 KWS 가 발생하거나 전화가 오는 등, 외부에서 오디오를 사용해야 하는 경우 TTS 는 자동 중지된다. KWS의 경우 sendTTS, getVoiceText로 501 오류가 전달된다. 리모콘의 마이크 버튼을 누를 경우 또는 전화 오는 경우 sendTTS, getVoiceText로 503이 전달된다. 이 경우에 대한 복구는 onResume Event 콜벡을 받아서 복구해야 한다.

Mute/Unmute, App Pause/Resume Event 관련

기가지니 단말의 상황에 따라 Mute/Unmute, Pause/Resume Event가 발생한다.
  • Pause/Resume Event
    Pause/Resume Event는 3rd Party 서비스 제공 중에 3rd Party 서비스가 종료되지 않은 상황에서 다른 앱의 화면이 앞에 표시될 때 발생한다. Pause Event 발생시 TTS 는 중지되며 3rd Party Web 은 중지 상태가 된다. (동영상 등 웹뷰 타이머 정지)
    Resume Event 발생시 3rd Party Web은 활성화 되지만, 동영상 플레이 등을 복구해 주지 않는다. 3rd Party는 Resume Event발생시 onAppStatusChange의 콜백을 구현하여 복구를 시도해야 한다. 또한 Resume Event는 onAppStatusChange 콜백에 muteFlag를 전달한다. muteFlag가 true인 경우 3rd Party Web이 활성화 되었지만 라디오 재생, 음악 재생하고 있는 상태이다. muteFlag가 false의 경우 3rd Party Web이 활성화 되었으며 Background에 음성을 사용하고 있지 않은 상태이다.
    3rd Party Web은 Resume 에서 muteFalg가 true 일 경우에는 오디오를 재생하면 안된다. Resume 시 또는 Resume 이후에 mute 상태 해제가 되면unmute event가 발생한다.
  1. Keyword Spotting 발화(기가지니, 지니야 등), 발화로 라디오 실행(기가지니, 라디오 켜), 발화로 음악 재생, 통화 발생 시 Pause Event가 발생되며 onAppStatusChange 로 changeStatus=1 으로 리턴한다. 그리고 각각의 상황 종료시 Resume Event가 발생되며 onAppStatusChange 로 changeStatus=0 로 리턴한다. Resume Event는 현재 상황에 따라 muteFlag가 설정되어 전달된다.

  • Case1 : “기가지니” 으로 발화 할 때
    case1

  • Case2 : 타 서비스의 오버레이 팝업 없이 화면이 올라 올 때
    case2

  • Case3 : 타 서비스의 오버레이 팝업이 노출 후 Web으로 복귀 할 때
    case3

  • Case4: 타 서비스의 오버레이 팝업이 노출 후 서비스 전환
    case4

  • Mute/Unmute Event
    Mute/UnMute는 화면에 보여지는 안내 없이, Background 에서 서비스가 실행되어야 하는 경우 발생된다. 이 경우 3rd Party Web이 정지되지 않으며, Mute에는 Audio를 중지시키는 코드가, unmute는 이를 복구하는 코드가 들어가야 한다. (Mute 이벤트 API 참고)
    하위 호환성을 위해서 pause event 발생시 mute event를 보내고, resume 시에 muteflag가 true일 경우 unmute event를 보낸다.

Copyright ⓒ 2017-2023 kt corp. All rights reserved.

⚠️ **GitHub.com Fallback** ⚠️