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 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 시스템에서 채울 슬롯을 결정하는 데 도움이 되는 단어 목록입니다.

듣고 싶은

주의: 이 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 응답이 전송될 때 호출됩니다. 다음 경우에 TTS 시작 반환된 프로미스가 결정되었거나 10초 후 제한 시간이 초과되었는지 확인합니다.

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

onTtsMark

onTtsMark(markName) returns undefined

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

항상 트리거되는 특수 표시:

• START는 TTS의 시작을 나타냅니다.
• END는 TTS의 끝을 나타냅니다.
• ERROR는 TTS 재생 오류를 나타냅니다.

다음과 같이 SSML 및 <mark> 태그를 사용하여 커스텀 표시를 정의할 수도 있습니다. <mark name="custom"/>입니다.

참고: 다음과 같은 경우에는 SSML 표시가 호출되지 않습니다. <ph type="x-smartling-placeholder">

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

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

onInputStatusChanged

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

onInputStatusChanged(inputStatus) returns undefined

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

매개변수
inputStatus	Enum 기기에서의 음성 및/또는 텍스트 입력 처리 상태입니다. 캔 다음과 같아야 합니다. LISTENING : 마이크가 열려 있습니다. IDLE : 마이크가 닫혔습니다. PROCESSING : 어시스턴트가 현재 다음 명령어를 실행 중입니다. 쿼리합니다 (마이크가 닫힘).