התכונה 'פעולות שיחה' הוצאה משימוש ב-13 ביוני 2023. כאן תוכלו לקרוא מידע נוסף על ההוצאה משימוש של 'פעולות שיחה'.

דף זה תורגם על ידי Cloud Translation API.

המשך הבנייה באמצעות מילוי הזמנות של הלקוח או השרת

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

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

כל ממשקי ה-API שמפורטים בקטע פיתוח עם מילוי הזמנות מצד הלקוח
כל ממשקי ה-API שמפורטים בקטע פיתוח עם מילוי הזמנות בצד השרת

הערה: אם מדובר במילוי הזמנה בצד הלקוח, מומלץ להפעיל תגובה לפעולה מאתר אחר (webhook) רק בתכונות שלא זמינות ב-Canvas, כמו קישור חשבונות.
הקריאה החוזרת (callback) של onTtsMark()

אם בוחרים באפשרות של מודל מילוי הזמנות בשרת, אפשר להשתמש באפשרויות הבאות בפעולה:

כל ממשקי ה-API שמפורטים בקטע פיתוח עם מילוי הזמנות בצד השרת
התקשרות חזרה

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

שם ה-API	יש תמיכה במודל מילוי ההזמנות של השרת?	האם יש תמיכה במודל מילוי ההזמנה של הלקוח?
`sendTextQuery()`	כן	נתמכת אבל לא מומלצת (למידע נוסף, כדאי לעיין ב-sendtextQuery())
`outputTts()`	כן	כן
`triggerScene()`	לא	כן
`createIntentHandler(), expect(), clearExpectations(), prompt()`	לא	כן
`createNumberSlot(),createTextSlot, createConfirmationSlot, createOptionsSlot()`	לא	כן
`setHomeParam(), getHomeParam(), setUserParam(), getUserParam()`	לא	כן

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

פיתוח מכירות בעזרת מילוי הזמנות בצד הלקוח

אפשר להטמיע את ממשקי ה-API הבאים של לוח הציור האינטראקטיבי בלוגיקה של אפליקציית האינטרנט:

`outputTts()`

ה-API הזה מאפשר להפיק פלט של המרת טקסט לדיבור (TTS) במכשיר בלי לשלוח הנחיה סטטית מ-Actions Builder או להפעיל תגובה לפעולה מאתר אחר (webhook). אם לא נדרשת לוגיקה בצד השרת שמשויכת ל-TTS, אפשר להשתמש ב-outputTts() בצד הלקוח כדי לדלג על נסיעה לשרת ולספק למשתמשים תגובה מהירה יותר.

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

לא כדאי לקרוא ל-outputTts() בתחילת הסשן. במקום זאת, אפשר להשתמש בהמרת טקסט לדיבור בצד השרת, לפני השיחה הראשונה של הפעולה.
אין לבצע הפעלות של outputTts() ברצף בלי לבצע פעולה של המשתמש.

קטע הקוד הבא מראה איך להשתמש ב-outputTts() כדי להפיק פלט טקסט לדיבור בצד הלקוח:

interactiveCanvas.outputTts(
      '<speak>This is an example response.</speak>', true);

אפשר גם להשתמש ב-outputTts() בשילוב עם onTtsMark() כדי להוסיף סמני SSML לרצף הטקסט. השימוש ב-onTtsMark() מסנכרן את האנימציה של אפליקציית האינטרנט או את מצב המשחק בנקודות ספציפיות במחרוזת SSML TTS, כפי שמוצג בקטע הקוד הבא:

interactiveCanvas.outputTts(
      '<speak>Speak as <mark name="number" /> number <break time="700ms"/>' +
      '<say-as interpret-as="cardinal">12345</say-as> <break time="300ms"/> ' +
      'Speak as <mark name="digits" /> digits <break time="700ms"/>' +
      '<say-as interpret-as="characters">12345</say-as></speak>', true);

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

טיפול במילוי הבקשה של הלקוח

במודל מילוי הבקשה של השרת בלוח שיתופי אינטראקטיבי, צריך לטפל בכל ה-Intents באמצעות תגובה לפעולה מאתר אחר (webhook), וכך להאריך את זמן האחזור בפעולה. במקום להפעיל תגובה לפעולה מאתר אחר (webhook), אתם יכולים לטפל במקרים של מימוש כוונות בתוך אפליקציית האינטרנט.

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

createIntentHandler(): שיטה שמאפשרת להגדיר רכיבי handler של Intents בקוד של אפליקציית האינטרנט עבור אובייקטים מסוג Intent בהתאמה אישית שמוגדרים ב-Actions Builder.
expect(): שיטה שמפעילה או רושמת את ה-handler של ה-Intent, כדי שמשתמש יוכל להתאים ל-Intent.
clearExpectations(): שיטה שמבהירה את הציפיות לכל האובייקטים מסוג Intent שמופעלים כרגע, כדי שלא תהיה אפשרות להתאים את הכוונות, גם אם משתמש אומר ביטוי שתואם לכוונה.
deleteHandler(): שיטה שמשביתה רכיבי handler ספציפיים של Intent, כך שלא תהיה אפשרות להתאים את ה-Intents האלה.

באמצעות ממשקי ה-API האלה, תוכלו להפעיל או להשבית באופן סלקטיבי אובייקטים של Intent למצבים שונים של פעולת לוח הציור האינטראקטיבי. כדי להפעיל את ה-Intents האלה, צריך להשתמש ב-expect() ברכיבי handler של Intent.

הפעלת רכיבי handler של Intent

הפעלת מטפל Intent היא תהליך דו-שלבי. קודם כול, צריך להגדיר את הכוונה ב-Actions Builder. בשלב הבא, כדי שה-Intent יהיה תואם, צריך להפעיל את expect() ב-handler של ה-Intent.

כדי להגדיר ולהפעיל handler של Intent בצד הלקוח:

פותחים את הפרויקט במסוף Actions ומוסיפים קהל בהתאמה אישית עם כוונת רכישה.
בוחרים באפשרות כן בשדה האם זו כוונה גלובלית?

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

צריך להגדיר את ה-handler של ה-Intent בלוגיקה של אפליקציית האינטרנט, כפי שמוצג בקטע הקוד הבא:

/**
* Define handler for intent.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    console.log("Intent match handler to reserve a table was triggered!");
  });

/**
* Define handler for intent with an argument.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    const numberOfPeople = matchedIntent.getIntentArg('numberOfPeople');
    console.log(`Intent match handler to reserve a table for ${number of people} was triggered!`);
  });

מפעילים את השיטה expect() כדי לרשום את ה-handler של ה-Intent, כפי שמוצג בקטע הקוד הבא:

/**
* Define handler for intent and expect() it.
*/
const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
  matchedIntent => {
    console.log("Intent match handler to reserve a table was triggered!");
  });
var handler = interactiveCanvas.expect(bookTableIntent);

השבתה של רכיבי handler של Intent

אחרי שתגדירו גורם handler של Intent, תוכלו להפעיל או להשבית את Intent לפי הצורך בפעולה. כשמבצעים קריאה ל-expect() כדי להפעיל כוונה, הוא מחזיר אובייקט עם method deleteHandler(), שאפשר להשתמש בו כדי להשבית את ה-handler החדש שנוצר. ההגדרה של ה-handler של ה-Intent נשמרת גם אם ה-Intent לא פעיל כרגע, כך שתוכלו להפעיל מחדש את ה-Intent במקרה הצורך.

כדי להשבית handler של Intent, צריך להפעיל את deleteHandler() ב-handler של ה-Intent, כפי שמוצג בקטע הקוד הבא:

    /**
    * Define handler for intent and expect() it.
    */
    const bookTableIntent = interactiveCanvas.createIntentHandler('reserveTable',
      matchedIntent => {
        console.log("Intent match handler to reserve a table was triggered!");
      });
    var handler = interactiveCanvas.expect(bookTableIntent);
    
    // Delete the handler for `bookTableIntent`.
    handler.deleteHandler();

אפשר לבצע קריאה ל-expect() כדי להוסיף מחדש handler מושבת של Intent, כפי שמוצג בקטע הקוד הבא:

    // Re-add the `bookTableIntent` handler.
    handler = interactiveCanvas.expect(bookTableIntent);

כדי להשבית אובייקטים מסוג Intent בכמות גדולה, אפשר להשתמש ב-method clearExpectations(), שמשבית את כל האובייקטים מסוג Intent שפועלים כרגע. קטע הקוד הבא מראה איך לבטל את הציפיות של כל הגורמים המטפלים ב-Intent:

interactiveCanvas.clearExpectations();

טיפול במילוי המשבצת של הלקוח

במקום להוסיף מילוי משבצות לסצנה ב-Actions Builder, אפשר לטפל במילוי של יחידות קיבולת (Slot) ישירות באפליקציית האינטרנט.

כדי לטפל במילוי של יחידות קיבולת (Slot) בצד הלקוח, קודם צריך ליצור יחידת קיבולת (Slot) באמצעות אחד מממשקי ה-API הבאים:

createNumberSlot(callback, hints): שיטה שמאפשרת להגדיר משבצת של מספר בקוד של אפליקציית האינטרנט. משמש לבקשת מספר של המשתמש.
createTextSlot(callback, hints): שיטה שמאפשרת להגדיר משבצת טקסט בקוד של אפליקציית האינטרנט. משמש לבקשת מילה למשתמש.
createConfirmationSlot(callback, hints): שיטה שמאפשרת להגדיר משבצת אישור בקוד של אפליקציית האינטרנט. משמש לבקשת אישור של המשתמש (כן/לא).
createOptionsSlot(options, callback, hints): שיטה שמאפשרת להגדיר מיקום של אפשרויות בקוד של אפליקציית האינטרנט. משמש להצגת בקשה למשתמשים לבחור מתוך רשימה של אפשרויות מוגדרות מראש.

כשיוצרים יחידת קיבולת (Slot), אפשר להגדיר את triggerHints. אלו מילות מפתח שמשפרות את המערכת להבנת שפה טבעית (NLU) בפעולה שלכם. מילות המפתח צריכות להיות מילים קצרות שהמשתמש עשוי לומר בעת מילוי משבצת הזמן. לדוגמה, מילת המפתח triggerHints במשבצת מספר יכולה להיות years. כשמשתמש משיב לשאלה לגבי הגיל שלו בשיחה עם התשובה "אני בן שלושים", יש סיכוי גבוה יותר שהפעולה תזהה שהמשתמש ממלא את המשבצת כמו שצריך.

אחרי שיוצרים יחידת קיבולת (Slot), אפשר לבקש מהמשתמש להזין יחידת קיבולת באמצעות ה-API של prompt:

prompt(tts, slot): שיטה שתפיק פלט של TTS למשתמשים ותתבקש למלא משבצת צפויה.

הקריאה ל-prompt() מחזירה התחייבות עם הסטטוס והערך של יחידת הקיבולת (Slot) שמולאה.

יצירת משבצת מספר

משבצת מספר מאפשרת לבקש למשתמש מספר במהלך השיחה. מידע נוסף על מילוי יחידות קיבולת (Slot) זמין בקטע מילוי חריץ במאמרי העזרה של Actions Builder.

כדי לבקש מהמשתמש למלא משבצת מספר בצד הלקוח, מבצעים את השלבים הבאים:

צריך לבצע קריאה ל-method createNumberSlot() כדי ליצור משבצת מספר בלוגיקה של אפליקציית האינטרנט:

/**
 * Create number slot.
 */
const triggerHints = { associatedWords: ['guess number', 'number'] };
const slot = interactiveCanvas.createNumberSlot(
  number => {
    console.log(`Number guessed: ${number}.`);
  }, triggerHints);

מפעילים את השיטה prompt() כדי לבקש מהמשתמש את יחידת הקיבולת (Slot) ומטפלים בערך של יחידת הקיבולת (Slot) מההבטחה שהוחזרה, כפי שמוצג בקטע הקוד הבא:

const promptPromise = interactiveCanvas.prompt(
  { text: 'What number am I thinking of between 1 and 10?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: 5, status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

יצירת משבצת טקסט

משבצת טקסט מאפשרת לבקש למשתמש מילה במהלך השיחה. מידע נוסף על מילוי יחידות קיבולת (Slot) זמין בקטע מילוי חריץ במאמרי העזרה של Actions Builder.

כדי לבקש מהמשתמש למלא משבצת טקסט בצד הלקוח, מבצעים את הפעולות הבאות:

צריך לבצע קריאה ל-method createTextSlot() כדי ליצור משבצת טקסט בלוגיקה של אפליקציית האינטרנט:

/**
 * Create text slot.
 */
const triggerHints = { associatedWords: ['favorite color', 'color'] };
const slot = interactiveCanvas.createTextSlot(
  text => {
    console.log(`Favorite color: ${text}.`);
  }, triggerHints);

const promptPromise = interactiveCanvas.prompt(
  { text: 'What is your favorite color?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: "red", status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

יצירת משבצת אישור

משבצת אישור מאפשרת לבקש אישור מהמשתמש (המשתמש יכול לענות "כן" ו "לא" כדי למלא את החריץ). מידע נוסף על מילוי יחידות קיבולת (Slot) זמין בקטע מילוי חריץ במאמרי העזרה של Actions Builder.

כדי לבקש מהמשתמש למלא משבצת אישור בצד הלקוח:

צריך להפעיל את השיטה createConfirmationSlot() כדי ליצור משבצת אישור בלוגיקה של אפליקציית האינטרנט:

/**
 * Create confirmation slot (boolean).
 */
const triggerHints = { associatedWords: ['user confirmation', 'confirmation'] };
const slot = interactiveCanvas.createConfirmationSlot(
  yesOrNo => {
    console.log(`Confirmation: ${yesOrNo}`);
  }, triggerHints);

const promptPromise = interactiveCanvas.prompt(
  { text: 'Do you agree to the Terms of Service?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: true, status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

יצירה של משבצת אפשרויות

משבצת אפשרויות מאפשרת לבקש מהמשתמש לבחור מתוך רשימה של אפשרויות מוגדרות מראש. מידע נוסף על מילוי יחידות קיבולת (Slot) זמין בקטע מילוי חריץ במאמרי העזרה של Actions Builder.

כדי לבקש מהמשתמש למלא משבצת אפשרויות בצד הלקוח, מבצעים את השלבים הבאים:

צריך לבצע קריאה ל-method createOptionsSlot() כדי ליצור משבצת אפשרויות בלוגיקה של אפליקציית האינטרנט:

/**
 * Create options slot (list selection).
 */
const triggerHints = { associatedWords: ['select fruit', 'choose fruit'] };
// Define selectable options
const options = [{
  key: 'apple',
  synonyms: ['apple', 'large apple', 'gala apple'],
}, {
  key: 'banana',
  synonyms: ['banana', 'green banana', 'plantain'],
}];
const slot = interactiveCanvas.createOptionsSlot(
  options,
  selectedOption => {
    console.log(`You have selected ${selectedOption} as your fruit.`);
  }, triggerHints);

const promptPromise = interactiveCanvas.prompt(
  { text: 'Would you like a banana or an apple?' }, slot);

promptPromise.then(
  answer => {
    if (answer.status == interactiveCanvas.AnswerStatus.ANSWERED) {
      // answer === {value: 'apple', status: ANSWERED}
      // Do something with answer.value
    } else {
      console.error('Promise returned unsuccessful status ' + answer.status);
    }
  });

`triggerScene()`

בעזרת ה-API של triggerScene() אפשר לעבור לסצנה אחרת בפעולת ההדפסה האינטראקטיבית על ידי מילוי ההזמנה בצד הלקוח. באמצעות triggerScene() אפשר גם לעבור ממילוי הזמנה בצד הלקוח למילוי הזמנות בצד השרת, כשהמשתמש צריך לגשת לסצנת מערכת ב-Actions Builder שמחייבת תגובה לפעולה מאתר אחר (webhook). לדוגמה, אתם יכולים לקרוא ל-triggerScene() כשמשתמש צריך לקשר את החשבון שלו או לקבל התראות. לאחר מכן, אפשר לחזור למילוי הבקשה בצד הלקוח באמצעות הודעת Canvas.

קטע הקוד הבא מראה איך להטמיע את triggerScene() בפעולה:

interactiveCanvas.triggerScene('SceneName').then((status) => {
  console.log("sent the request to trigger scene.");
}).catch(e => {
  console.log("Failed to trigger a scene.");
})

אחסון בבית ובמשתמש אצל הלקוח

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

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

אחסון בבית בצד הלקוח

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

כדי להפעיל את הפעולה כדי שתתמוך באחסון ביתי, צריך לבצע את השלבים הבאים:

במסוף Actions, נכנסים אל פריסה > פרטי ספרייה > מידע נוסף.
מסמנים את התיבה כן עבור האם הפעולות משתמשות בנפח האחסון בבית?

כדי לכתוב ערך לאחסון של הבית באפליקציית האינטרנט, צריך לבצע קריאה ל-method setHomeParam(), כפי שמוצג בקטע הקוד הבא:

interactiveCanvas.setHomeParam('familySize',  10).then(
      result => {
        console.log('Set home param success');
      },
      fail => {
        console.error(err);
      });

כדי לקרוא ערך מאחסון לבית באפליקציית האינטרנט, צריך לבצע קריאה ל-method getHomeParam(), כפי שמוצג בקטע הקוד הבא:

interactiveCanvas.getHomeParam('familySize').then(
      value => {
        console.log(JSON.stringify(result));
      },
      err => {
        console.error(err);
      }
  );

כדי לנקות את כל האחסון הקיים בבית, צריך לבצע קריאה ל-method resetHomeParam(), כפי שמוצג בקטע הקוד הבא:

interactiveCanvas.resetHomeParam();

אחסון בצד הלקוח

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

כדי לכתוב ערך לאחסון של המשתמש באפליקציית האינטרנט, צריך לבצע קריאה ל-method setUserParam(), כפי שמוצג בקטע הקוד הבא:

interactiveCanvas.setUserParam('color',  'blue').then(
      result => {
        console.log('Set user param success');
      },
      err => {
        console.error(err);
      });

כדי לקרוא ערך מאחסון המשתמש באפליקציית האינטרנט, צריך לבצע קריאה ל-method getUserParam(), כפי שמוצג בקטע הקוד הבא:

interactiveCanvas.getUserParam('color').then(
      value => {
        console.log(JSON.stringify(result));
      },
      err => {
        console.error(err);
      }
  );

כדי לפנות את כל נפח האחסון הקיים של המשתמש, צריך לבצע קריאה ל-method resetUserParam(), כפי שמוצג בקטע הקוד הבא:

interactiveCanvas.resetUserParam();

`setCanvasState()`

השיטה setCanvasState() מאפשרת לשלוח נתוני מצב מאפליקציית האינטרנט האינטראקטיבית של Canvas למילוי הבקשה, ומודיעה ל-Assistant שמצב האפליקציה עודכן. אפליקציית האינטרנט שולחת את המצב המעודכן שלה כאובייקט JSON.

התקשרות אל setCanvasState() לא מפעילה כוונה. אחרי ההפעלה של setCanvasState(), אם sendTextQuery() מופעלת או ששאילתת המשתמש תואמת לכוונה בשיחה, הנתונים שהוגדרו עם setCanvasState() בתור השיחה הקודמת יהיו זמינים בפניות הבאות של השיחה.

בקטע הקוד הבא, אפליקציית האינטרנט משתמשת ב-setCanvasState() כדי להגדיר את הנתונים של מצב לוח הציור:

JavaScript

this.action.canvas.setCanvasState({ score: 150 })

הפניה למצב לוח הציור של התגובה לפעולה מאתר אחר (webhook)

אתם יכולים להפנות לערכים של מצב לוח הציור שנשמר בקוד מילוי ההזמנה. כדי להפנות לערך, משתמשים בתחביר conv.context.canvas.state.KEY, כאשר KEY הוא המפתח שניתן כשהגדרתם את הערך של מצב לוח הציור.

לדוגמה, אם בעבר שמרתם ערך גבוה של משחק במצב לוח הציור בתור הפרמטר score, צריך להפנות לערך הזה באמצעות conv.context.canvas.state.score כדי לגשת לערך הזה במילוי הבקשה:

Node.js

app.handle('webhook-name', conv => {
    console.log(conv.context.canvas.state.score);
})

הפניה למצב לוח הציור בהנחיות

אפשר להפנות לערכים של מצבי לוח הציור המאוחסנים בהנחיה. כדי להפנות לערך, משתמשים בתחביר $canvas.state.KEY, כאשר KEY הוא המפתח שניתן כשהגדרתם את הערך של מצב לוח הציור.

לדוגמה, אם בעבר שמרתם ערך גבוה של משחק במצב לוח הציור בתור הפרמטר score, תצטרכו להפנות לערך הזה באמצעות $canvas.state.score כדי לגשת לערך הזה בהודעה:

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Your high score is $canvas.state.score."
      }]
    }
  }]
}

מצב לוח הציור של ההפניה בתנאים

אפשר גם להפנות לערכים של מצב לוח הציור שנשמר בתנאים. כדי להפנות לערך הזה צריך להשתמש בתחביר canvas.state.KEY, שבו הערך KEY הוא המפתח שסופק כשהגדרתם את הערך של מצב לוח הציור.

לדוגמה, אם בעבר שמרתם ערך גבוה של משחק במצב לוח הציור בתור הפרמטר score, ואתם רוצים להשוות אותו לערך 999 בתנאי, תוכלו להפנות לערך ששמור בתנאי בעזרת canvas.state.score. ביטוי התנאי נראה כך:

תחביר של תנאים

canvas.state.score >= 999

`sendTextQuery()`

השיטה sendTextQuery() שולחת שאילתות טקסט אל 'פעולות שיחה' כדי לבצע התאמה פרוגרמטית ל-Intent. בדוגמה הזו נעשה שימוש ב-sendTextQuery() כדי להפעיל מחדש את המשחק המסתובב במשולש כשהמשתמש לוחץ על לחצן. כשהמשתמש לוחץ על הלחצן 'הפעלת המשחק מחדש', sendTextQuery() שולח שאילתת טקסט שתואמת ל-Intent של Restart game, ומחזיר הבטחה. התוצאה של ההבטחה הזו היא SUCCESS אם הכוונה מופעלת, ו-BLOCKED אם היא לא מופעלת. קטע הקוד הבא תואם ל-Intent ומטפל במקרי ההצלחה והכשל של ההבטחה:

JavaScript

…
/**
* Handle game restarts
*/
async handleRestartGame() {
    console.log(`Request in flight`);
    this.button.texture = this.button.textureButtonDisabled;
    this.sprite.spin = false;
    const res = await this.action.canvas.sendTextQuery('Restart game');
    if (res.toUpperCase() !== 'SUCCESS') {
        console.log(`Request in flight: ${res}`);
        return;
    }
    console.log(`Request in flight: ${res}`);
    this.button.texture = this.button.textureButtonDisabled;
    this.sprite.spin = false;
}
…

אם ההבטחה מסתיימת ב-SUCCESS, handler של תגובה לפעולה מאתר אחר (webhook) Restart game שולח את התגובה Canvas לאפליקציית האינטרנט שלכם:

JavaScript

…
app.handle('restart', conv => {
  conv.add(new Canvas({
    data: {
      command: 'RESTART_GAME'
    }
  }));
});
…

תגובת Canvas הזו מפעילה את הקריאה החוזרת (callback) onUpdate(), שמפעילה את הקוד בקטע הקוד RESTART_GAME הבא:

JavaScript

…
RESTART_GAME: (data) => {
    this.scene.button.texture = this.scene.button.textureButton;
    this.scene.sprite.spin = true;
    this.scene.sprite.tint = 0x00FF00; // green
    this.scene.sprite.rotation = 0;
},
…

פיתוח גרסת build עם מילוי הזמנות בצד השרת

אפשר להטמיע ב-webhook את ממשקי ה-API האינטראקטיביים הבאים של לוח הציור:

הפעלת מצב מסך מלא

כברירת מחדל, אפליקציות האינטרנט האינטראקטיביות של Canvas כוללות כותרת בחלק העליון של המסך עם השם של הפעולה. אפשר להשתמש ב-enableFullScreen כדי להסיר את הכותרת ולהחליף אותה בהודעה זמנית שתוצג במסך הטעינה. ההודעה הזו מאפשרת למשתמש ליהנות מחוויית שימוש במסך מלא במהלך האינטראקציה עם הפעולה. בהודעה של החלון הקופץ מוצגים השם המוצג של הפעולה, שם המפתח והוראות ליציאה מהפעולה. צבע ההודעה משתנה בהתאם למה שהמשתמשים בחרו כעיצוב במכשיר שלהם.

**איור 1.** הודעה קופצת במסך הטעינה של פעולה.

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

אפשר להפעיל את מצב מסך מלא דרך התגובה לפעולה מאתר אחר (webhook) או בהנחיה סטטית ב-Actions Builder.

כדי להפעיל מצב מסך מלא ב-webhook, צריך לבצע את השלבים הבאים:

מגדירים את השדה enableFullScreen לערך true בתגובה הראשונה מסוג canvas שהוחזרה על ידי ה-webhook בסשן. קטע הקוד הבא הוא דוגמה להטמעה באמצעות ספריית הלקוח של Node.js:

 const { conversation, Canvas } = require('@assistant/conversation');
 const functions = require('firebase-functions');

 const app = conversation();

 app.handle('invocation_fullscreen', conv => {
   conv.add(new Canvas(
     {
       url: 'https://example-url.com',
       enableFullScreen: true
     }));
 });

 exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

כדי להפעיל מצב מסך מלא בהנחיה סטטית ב-Actions Builder, מבצעים את השלבים הבאים:

פותחים את הפרויקט בקונסולה ל-Actions.
בסרגל הניווט, לוחצים על פיתוח ופותחים את ההנחיה שכוללת את התגובה הראשונה של canvas.

הגדר את enable_full_screen ל-true, כפי שמוצג בקטע הקוד הבא:

 {
  "candidates": [
    {
      "canvas": {
        "url": "https://example-url.com",
        "enable_full_screen": true
      }
    }
  ]
}

`continueTtsDuringTouch`

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

אפשר להטמיע את ההתנהגות הזו ב-webhook או בהנחיה סטטית ב-Actions Builder.

כדי להמשיך את ההקראה אחרי שהמשתמש מקיש על המסך ב-webhook, צריך לבצע את השלב הבא:

מגדירים את השדה continueTtsDuringTouch לערך true בתגובה הראשונה מסוג canvas שהוחזרה על ידי ה-webhook בסשן. קטע הקוד הבא הוא דוגמה להטמעה באמצעות ספריית הלקוח של Node.js:

const { conversation, Canvas } = require('@assisant/conversation');
const functions = require('firebase-functions');

const app = conversation();

app.handle('intent-name', conv => {
  conv.add(new Canvas(
    {
      url: 'https://example-url.com',
      continueTtsDuringTouch: true
    }));
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

כדי להפעיל את המרת הטקסט לדיבור (TTS) אחרי שהמשתמש מקיש על המסך בהודעה סטטית ב-Actions Builder, מבצעים את השלבים הבאים:

פותחים את הפרויקט בקונסולה ל-Actions.
לוחצים על פיתוח בסרגל הניווט ופותחים את ההנחיה שכוללת את התגובה הראשונה של canvas.

הגדר את continue_tts_during_touch ל-true, כפי שמוצג בקטע הקוד הבא:

  {
   "candidates": [
     {
       "canvas": {
         "url": "https://example-url.com",
         "continue_tts_during_touch": true
       }
     }
   ]
 }