Interactive Canvas API 참조

Interactive Canvas API는 웹 앱에서 interactiveCanvas 객체를 사용하여 대화형 작업과 상호작용하는 데 사용하는 자바스크립트 라이브러리입니다.

참고: interactiveCanvas 객체는 window 객체에 연결됩니다. 프런트엔드 프레임워크를 사용하여 웹 앱을 개발하는 경우 window에 액세스하여 API를 설정할 수 있는지 확인해야 합니다.

Interactive Canvas에 관한 자세한 내용은 Interactive Canvas 문서를 참고하세요.

방법

경고: 일부 Interactive Canvas API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 API를 테스트할 수 있지만 이러한 기능을 사용하는 작업을 알파, 베타 또는 프로덕션 채널에 배포하지 마세요. 이러한 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

준비됨

ready(callbacks) returns undefined

콜백을 등록하기 위해 로드된 Interactive Canvas 웹 앱에서 호출합니다.

매개변수
callbacks	InteractiveCanvasCallbacks 메서드 콜백이 포함된 객체입니다.

참고: 페이지가 로드되는 즉시 웹 앱에서 ready API를 호출해야 합니다. 그렇지 않으면 작업이 종료됩니다.

SendTextQuery

sendTextQuery(textQuery) returns Promise<state>

대화형 작업으로 텍스트 쿼리를 보냅니다.

매개변수
textQuery	string 대화형 작업에 전송할 쿼리입니다.
state	string 다음 중 하나는 사용해야 합니다. READY: 플랫폼에서 요청을 수락할 수 있습니다. BLOCKED: 진행 중인 쿼리가 있으며 새 쿼리가 삭제됩니다. UNKNOWN: 현재 쿼리 상태를 확인할 수 없습니다.

주의: textQuery는 640자(영문 기준) 이하여야 합니다.

getHeaderHeightPx

getHeaderHeightPx() returns Promise<height>

디스플레이 상단의 헤더 높이를 결정합니다.

매개변수
height	number 픽셀 단위의 높이입니다.

outputTts

outputTts(text, openMic) returns undefined;

SSML 텍스트를 재생합니다.

매개변수
text	string 재생할 SSML 지원 문자열입니다.
openMic	boolean TTS 재생 후 마이크 열기 여부입니다.

createIntentHandler

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

createIntentHandler(intentId, callback) returns IntentHandler

NLU 맞춤 인텐트의 인텐트 핸들러를 만듭니다.

매개변수
intentId	string 작업 빌더에 정의된 인텐트 이름입니다.
callback	function(MatchedIntent) 인텐트가 일치될 때 실행할 함수입니다.
IntentHandler	object expect()를 사용하여 등록할 수 있는 인텐트 핸들러 객체입니다.

IntentHandler

인텐트 핸들러를 나타내는 객체입니다. expect() 또는 prompt()를 사용하여 등록할 수 있습니다.

일치 의도

일치된 인텐트의 데이터가 포함된 객체입니다.

방법
getIntentArg(parameterName)	function(string) 일치하는 인텐트의 인텐트 매개변수를 가져오는 메서드

CreateNumberSlot

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

createNumberSlot(callback, hints?) returns Slot<number>

유형 번호의 슬롯을 만듭니다.

매개변수
callback	function(FilledSlot) 슬롯이 채워질 때 실행될 함수입니다.
hints	Hints 사용자가 슬롯을 채울 때 말할 수 있는 짧은 단어입니다. hints는 NLU 시스템에서 채울 슬롯을 결정하는 데 도움이 됩니다.
Slot	object prompt()를 사용하여 등록할 수 있는 슬롯 객체

텍스트 슬롯 만들기

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

createTextSlot(callback, hints?) returns Slot<string>

유형 문자열의 슬롯을 만듭니다.

매개변수
callback	function(FilledSlot) 슬롯이 채워질 때 실행될 함수입니다.
hints	Hints 사용자가 슬롯을 채울 때 말할 수 있는 짧은 단어입니다. hints는 NLU 시스템에서 채울 슬롯을 결정하는 데 도움이 됩니다.
Slot	object prompt()를 사용하여 등록할 수 있는 슬롯 객체

확인 슬롯

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

createConfirmationSlot(callback, hints?) returns Slot<boolean>

불리언 유형의 슬롯을 만듭니다.

매개변수
callback	function(FilledSlot) 슬롯이 채워질 때 실행될 함수입니다.
hints	Hints 사용자가 슬롯을 채울 때 말할 수 있는 짧은 단어입니다. hints는 NLU 시스템에서 채울 슬롯을 결정하는 데 도움이 됩니다.
Slot	object prompt()를 사용하여 등록할 수 있는 슬롯 객체

createOptionsSlot

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

createOptionsSlot(options, callback, hints?) returns Slot<string>

사전 정의된 옵션 목록에서 슬롯을 만듭니다.

매개변수
options	array<Option> 슬롯이 채워질 때 실행될 함수입니다.
callback	function(FilledSlot) 슬롯이 채워질 때 실행될 함수입니다.
hints	Hints 사용자가 슬롯을 채울 때 말할 수 있는 짧은 단어입니다. hints는 NLU 시스템에서 채울 슬롯을 결정하는 데 도움이 됩니다.
Slot	object prompt()를 사용하여 등록할 수 있는 슬롯 객체

슬롯

채워질 슬롯을 나타내는 객체입니다. expect() 또는 prompt()를 사용하여 등록할 수 있습니다.

채워진 슬롯<T>

채워진 슬롯을 나타내는 객체입니다.

매개변수
T	boolean|number|string 슬롯 유형입니다.

옵션

슬롯 유형 항목을 나타내는 객체입니다.

필드
key	string 슬롯 유형 항목의 고유 식별자입니다.
synonyms	array<string> 슬롯 옵션을 선택하는 데 사용되는 단어 목록입니다.

힌트

슬롯의 힌트를 나타내는 객체입니다.

필드
associatedWords	array<string> NLU 시스템이 채울 슬롯을 결정하는 데 사용되는 단어 목록입니다.

듣고 싶은

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

expect(expectation) returns HandlerRegistration

클라이언트에 기대치를 등록합니다. 인텐트 핸들러와 슬롯에서 호출할 수 있습니다.

매개변수
expectation	IntentHandler|Slot 등록할 인텐트 핸들러 또는 슬롯입니다.
HandlerRegistration	object 등록된 인텐트 핸들러 또는 슬롯입니다.

핸들러 등록

등록된 인텐트 핸들러를 나타내는 객체입니다.

방법
deleteHandler()	function 예상 인텐트 핸들러를 등록 취소합니다.

명확한 기대치

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

clearExpectations() returns undefined;

이전에 등록된 모든 인텐트 핸들러와 슬롯을 삭제하여 모든 기대치를 삭제합니다.

프롬프트

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

prompt(tts, expectation) returns Promise<Answer<T>>

제공된 TTS 문자열로 사용자에게 메시지를 표시하고 클라이언트에 기대치를 등록합니다. 인텐트 핸들러와 슬롯에서 호출할 수 있습니다.

매개변수
tts	string 사용자에게 지정된 기대치를 표시하는 데 사용되는 TTS 문자열입니다.
expectation	IntentHandler|Slot 등록할 인텐트 핸들러 또는 슬롯입니다.
Answer<T>	object 메시지에 대한 사용자 제공 답변입니다.

답변<T>

메시지에 대한 사용자 제공 답변을 나타내는 객체입니다.

필드
value	boolean|number|string 사용자 제공 답변의 값입니다.
status	string 답변 상태입니다. 다음 중 하나는 사용해야 합니다. ANSWERED: 사용자가 메시지에 답변했습니다. NO_MATCH: 사용자에게 답변을 요청받았으며 예상된 답변 또는 기타 예상 인텐트와 일치하지 않는 답변으로 응답했습니다. YIELD: 사용자가 메시지에 다른 의도로 응답했습니다.

triggerScene

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

triggerScene(sceneName) returns Promise<TriggerSceneStatus>

장면을 트리거합니다.

매개변수
sceneName	string 트리거할 장면의 이름입니다.
TriggerSceneStatus	string triggerScene() 호출의 상태입니다. 다음 중 하나는 사용해야 합니다. SUCCESS: 서버에서 요청을 처리했습니다. BLOCKED: 처리 중인 기존 쿼리에 의해 요청이 차단되었습니다. UNKNOWN: 요청 상태를 알 수 없습니다.

setUserParam

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

setUserParam(key, value) returns Promise<undefined>;

대화 간에 전달 및 유지되는 키-값 쌍을 설정합니다.

매개변수
key	string 매개변수 키입니다.
value	object|array|boolean|number|string 매개변수 값입니다.

getUserParam

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

getUserParam(key) returns Promise<object|array|boolean|number|string>;

지정된 키(매개변수가 있는 경우)와 호출 상태를 가져옵니다.

매개변수
key	string 매개변수 키입니다.

resetUserParam

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

resetUserParam() returns Promise<void>;

모든 사용자 매개변수를 지웁니다.

setHomeParam

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

setHomeParam(key, value) returns Promise<undefined>;

대화 간에 전달 및 유지되는 키-값 쌍을 설정합니다.

매개변수
key	string 매개변수 키입니다.
value	object|array|boolean|number|string 매개변수 값입니다.

getHomeParam

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

getHomeParam(key) returns Promise<object|array|boolean|number|string>;

지정된 키(매개변수가 있는 경우)와 호출 상태를 가져옵니다.

매개변수
key	string 매개변수 키입니다.

리셋홈파람

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

resetHomeParam() returns Promise<void>;

모든 사용자 매개변수를 지웁니다.

setCanvasState

setCanvasState(state) returns undefined

Canvas 웹 앱이 상태를 업데이트했음을 어시스턴트에 알립니다. setCanvasState 메서드는 값을 반환하지 않습니다. conv.context.canvas.state 속성을 통해 상태 페이로드에 액세스할 수 있습니다.

주의: state 객체의 문자열 표현 길이는 50,000자(영문 기준) 이하여야 합니다. 문자열의 길이가 50,000자를 초과하면 오류가 발생합니다.

매개변수
state	Object 캔버스 앱의 업데이트된 상태를 JSON 객체로 나타낸 것입니다.

InteractiveCanvasCallbacks

이러한 콜백은 대화형 작업의 정보나 요청에 응답하는 방법을 제공하는 반면, 메서드는 대화형 작업에 정보나 요청을 전송하는 방법을 제공합니다.

onUpdate

onUpdate(data) returns Promise|undefined

대화형 작업으로부터 Canvas 응답이 전송될 때 호출됩니다. 반환된 Promise가 확인되면 TTS가 시작되거나 10초 후에 시간이 초과됩니다.

매개변수
data	Object 웹훅에서 전송된 데이터가 업데이트되었습니다.

onTtsMark

onTtsMark(markName) returns undefined

TTS 재생 중에 호출되는 콜백입니다.

항상 트리거되는 특수 표시는 다음과 같습니다.

• START는 TTS의 시작을 나타냅니다.
• END는 TTS의 끝을 나타냅니다.
• ERROR는 TTS를 재생하는 중에 오류가 발생했음을 나타냅니다.

SSML과 <mark> 태그(예: <mark name="custom"/>)를 사용하여 맞춤 표시를 정의할 수도 있습니다.

참고: SSML 마크는 다음과 같은 경우 호출되지 않습니다.

• TTS가 시작되기 전에 사용자가 마이크를 탭하거나 Interactive Canvas 클라이언트가 sendTextQuery를 호출합니다. TTS가 취소되고 TTS의 모든 SSML 마크가 무시됩니다.
• TTS 중에 사용자가 마이크를 탭하거나 Interactive Canvas 클라이언트가 sendTextQuery를 호출합니다. TTS가 중단되고 TTS의 나머지 SSML 마크는 무시됩니다.

매개변수
markName	string TTS 재생 중에 호출되는 표시 이름입니다.

onInputStatusChanged

주의: 이 API는 현재 개발자 프리뷰 상태에 있습니다. 시뮬레이터에서 이 API를 테스트할 수 있지만 알파, 베타 또는 프로덕션 채널에 이 기능을 사용하는 작업을 배포하지 마세요. 이 기능을 사용하여 배포된 작업은 최종 사용자 기기에서 작동하지 않습니다.

onInputStatusChanged(inputStatus) returns undefined

Canvas 앱에 어시스턴트 입력 상태가 변경되었음을 알립니다.

매개변수
inputStatus	Enum 기기의 음성 및 텍스트 입력 처리 상태입니다. 예를 들면 다음과 같습니다. LISTENING : 마이크가 켜져 있습니다. IDLE : 마이크가 닫혀 있습니다. PROCESSING : 어시스턴트가 현재 쿼리를 실행 중입니다 (마이크가 닫힘).