Interactive Canvas API 참조

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

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

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 Actions Builder에 정의된 인텐트 이름
callback	function(MatchedIntent) 인텐트가 일치할 때 실행할 함수입니다.
IntentHandler	object expect()를 사용하여 등록할 수 있는 인텐트 핸들러 객체입니다.

IntentHandler

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

MatchedIntent

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

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

createNumberSlot

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

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

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

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

createTextSlot

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

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

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

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

createConfirmationSlot

주의: 이 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()를 사용하여 등록할 수 있습니다.

FilledSlot<T>

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

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

옵션

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

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

힌트

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

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

expect

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

expect(expectation) returns HandlerRegistration

클라이언트에 예상을 등록합니다. 인텐트 핸들러 및 슬롯에서 호출할 수 있습니다.

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

HandlerRegistration

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

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

clearExpectations

주의: 이 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 매개변수 키입니다.

resetHomeParam

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

resetHomeParam() returns Promise<void>;

모든 사용자 매개변수를 삭제합니다.

setCanvasState

setCanvasState(state) returns undefined

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

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

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

InteractiveCanvasCallbacks

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

onUpdate

onUpdate(data) returns Promise|undefined

대화 작업에서 Canvas 응답이 전송될 때 호출됩니다. 반환된 프로미스가 해결되거나 10초 후 제한 시간이 초과되면 TTS가 시작됩니다.

매개변수
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

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

매개변수
inputStatus	Enum 기기의 음성 및/또는 텍스트 입력 처리 상태 다음 중 하나일 수 있습니다. LISTENING : 마이크가 열려 있습니다. IDLE : 마이크가 닫혔습니다. PROCESSING : 어시스턴트가 현재 쿼리를 실행 중입니다 (마이크가 닫혀 있음).