הפניה ל-API של בד הציור האינטראקטיבי

Interactive Canvas API היא ספריית JavaScript שבה משתמשים כדי ליצור ממשק. בפעולת השיחה באמצעות האובייקט interactiveCanvas באפליקציית האינטרנט.

הערה: האובייקט interactiveCanvas מצורף לאובייקט window. אם להשתמש ב-framework של ממשק קצה כדי לפתח את אפליקציית האינטרנט שלכם, עליכם לוודא שיש לכם גישה אל window כדי להגדיר את ה-API.

למידע נוסף על לוח הציור האינטראקטיבי, אפשר להיכנס ללוח הציור האינטראקטיבי. תיעוד.

שיטות

אזהרה: חלק ממשקי API אינטראקטיביים של לוח הציור נמצאים כרגע בתצוגה מקדימה למפתחים. אפשר לבדוק את ממשקי ה-API סימולטור, אבל לא לפרוס פעולה שמשתמשת בתכונות האלה בגרסת אלפא, בטא או בסביבת ייצור. הערוצים שלך. פעולות שנפרסו באמצעות התכונות האלה לא יפעלו אצל משתמש הקצה מכשירים.

למקומות

ready(callbacks) returns undefined

בוצעה קריאה על ידי אפליקציית האינטרנט Interactive Canvas אחרי שהיא נטענת כדי לרשום קריאה חוזרת (callback).

פרמטרים
callbacks	InteractiveCanvasCallbacks אובייקט שמכיל קריאות חוזרות (callback) של method.

הערה: עליך להפעיל את ה-API של ready באפליקציית האינטרנט ברגע שהדף נטען. אחרת, הפעולה תיסגר.

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

יצירה של מטפל Intent עבור NLU בהתאמה אישית עם כוונת רכישה.

פרמטרים
intentId	string שם Intent כפי שמוגדר ב-Actions Builder.
callback	function(MatchedIntent) פונקציה שתופעל כשיש התאמה ל-Intent.
IntentHandler	object אובייקט של Intent של Intent שאפשר לרשום באמצעות expect().

IntentHandler

אובייקט שמייצג handler של Intent. ניתן להירשם באמצעות expect() או prompt().

MatchedIntent

אובייקט שמכיל את הנתונים של כוונת רכישה תואמת.

שיטות
getIntentArg(parameterName)	function(string) שיטה לקבלת פרמטר Intent של כוונת רכישה תואמת.

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

רישום הציפייה מהלקוח. אפשר לקרוא להן במשבצות Intent ומעבדי Intent.

פרמטרים
expectation	IntentHandler|Slot ה-Intent או המשבצת של ה-Intent להרשמה.
HandlerRegistration	object ה-Intent או המשבצת של ה-Intent הרשום.

HandlerRegistration

אובייקט שמייצג handler רשום של Intent.

שיטות
deleteHandler()	function ביטול הרישום של ה-handler הצפוי של Intent.

clearExpectations

זהירות: ה-API הזה נמצא כרגע תצוגה מקדימה למפתחים. אפשר לבדוק את ה-API הזה בסימולטור, אבל לא לפרוס פעולה שמשתמשת בתכונה הזו בערוצי אלפא, בטא או בערוץ ייצור. פעולות שנפרסו באמצעות לא תפעל במכשירים של משתמשי קצה.

clearExpectations() returns undefined;

הפעולה הזו מסירה את כל הציפיות על ידי מחיקה של כל ה-Intents והמשבצות של Intent שנרשמו קודם לכן.

הצעה לפעולה

זהירות: ה-API הזה נמצא כרגע תצוגה מקדימה למפתחים. אפשר לבדוק את ה-API הזה בסימולטור, אבל לא לפרוס פעולה שמשתמשת בתכונה הזו בערוצי אלפא, בטא או בערוץ ייצור. פעולות שנפרסו באמצעות לא תפעל במכשירים של משתמשי קצה.

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

מציג למשתמש את מחרוזת ה-TTS שסופקה ורושם את הציפייה בלקוח. אפשר לקרוא להן במשבצות Intent ומעבדי Intent.

פרמטרים
tts	string מחרוזת ה-TTS שמשמשת כדי לבקש מהמשתמש את הציפיות שסופקה.
expectation	IntentHandler|Slot ה-Intent או המשבצת של ה-Intent להרשמה.
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

נשלחת ל-Assistant הודעה על כך שאפליקציית האינטרנט ללוח הציור עודכנה. setCanvasState לא מחזירה ערך. ניתן לגשת למטען הייעודי (Payload) של המדינה דרך conv.context.canvas.state.

זהירות: אורך ייצוג המחרוזת של האובייקט state חייב להיות באורך של עד 50,000 תווים או שווה ל-50,000 תווים. אם המחרוזת ארוכה מ-50,000 תווים לאורך זמן, תושמעת שגיאה.

פרמטרים
state	Object המצב המעודכן של אפליקציית לוח הציור כאובייקט JSON.

InteractiveCanvasCallbacks

הקריאות החוזרות האלה מאפשרות לכם להשיב למידע או לבקשות מפעולת השיחה, ואילו השיטות מאפשרות לשלוח מידע או בקשות לפעולה בשיחה.

onUpdate

onUpdate(data) returns Promise|undefined

מתבצעת קריאה כשנשלחת תשובה של Canvas מהפעולה בשיחה. טקסט TTS יתחיל כאשר שההבטחה שהוחזרה טופלה, או שתם הזמן הקצוב לתפוגה אחרי 10 שניות.

פרמטרים
data	Object הנתונים המעודכנים שנשלחו על ידי ה-webhook.

onTtsMark

onTtsMark(markName) returns undefined

קריאה חוזרת (callback) שמופעלת במהלך הפעלת TTS.

סימנים מיוחדים שמופעלים תמיד:

• START מציין את תחילת ה-TTS.
• END מציין את סוף ה-TTS.
• ERROR מציין שגיאה בהפעלת ה-TTS.

אפשר גם להגדיר סימנים מותאמים אישית באמצעות SSML והתג <mark>, כמו <mark name="custom"/>

הערה: סימני SSML לא מופעלים במקרים הבאים:

• לפני ששפת הטקסט מתחילה, המשתמש מקיש על המיקרופון או על לוח הציור האינטראקטיבי הלקוח מפעיל את sendTextQuery. ה-TTS מבוטל וכל סימון SSML ב- המערכת מתעלמת מה-TTS.
• במהלך המרת טקסט לדיבור, המשתמש מקיש על המיקרופון או שהלקוח של לוח הציור האינטראקטיבי מופעל. sendTextQuery יש הפרעה ב-TTS וכל SSML שנותר המערכת מתעלמת מסימנים ב-TTS.

פרמטרים
markName	string סימון השם שהופעל במהלך הפעלת TTS.

onInputStatusChanged

זהירות: ה-API הזה נמצא כרגע תצוגה מקדימה למפתחים. אפשר לבדוק את ה-API הזה בסימולטור, אבל לא לפרוס פעולה שמשתמשת בתכונה הזו בערוצי אלפא, בטא או בערוץ ייצור. פעולות שנפרסו באמצעות לא תפעל במכשירים של משתמשי קצה.

onInputStatusChanged(inputStatus) returns undefined

מודיע לאפליקציית לוח הציור שסטטוס הקלט של Assistant השתנה.

פרמטרים
inputStatus	Enum הסטטוס של עיבוד קלט טקסט או טקסט במכשיר. מאפשרת יהיו: LISTENING : המיקרופון פועל. IDLE : המיקרופון סגור. PROCESSING : Assistant מבצעת כרגע שאילתה (המיקרופון סגור).