התקשרות חזרה

ניתן להטמיע את הקריאות החוזרות הבאות בפעולת ההדפסה האינטראקטיבית:

onUpdate()

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

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

onTtsMark()

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

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

בדוגמה הבאה, ה-handler של התגובה לפעולה מאתר אחר (webhook) revealWord כולל סימן מותאם אישית בתגובה שנשלח למשתמש במקרה שהפסיד במשחק:

JavaScript

…
app.handle('revealWord', conv => {
  conv.add(new Simple(`<speak>Sorry, you lost.<mark name="REVEAL_WORD"/> The word is ${conv.session.params.word}.</speak>`));
  conv.add(new Canvas());
});
…

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

JavaScript

…
setCallbacks() {
    // declare Assistant Canvas Action callbacks
    const callbacks = {
        onTtsMark(markName) {
            if (markName === 'REVEAL_WORD') {
                // display the correct word to the user
                that.revealCorrectWord();
            }
        },
    }
    callbacks.onUpdate.bind(this);
}
…

onInputStatusChanged()

תקבלו התראה מהקריאה החוזרת (callback) של onInputStatusChanged() כשסטטוס הקלט ישתנה בפעולת ההדפסה האינטראקטיבית. שינויים בסטטוס הקלט מציינים מתי המיקרופון נפתח ונסגר, או מתי Assistant מעבדת שאילתה. האירועים הבאים יכולים לגרום לשינוי בסטטוס הקלט:

  • המשתמש שמדבר אל הפעולה
  • המשתמש מזין טקסט באפליקציה של חיפוש Google ל-Android (AGSA)
  • אפליקציית האינטרנט שמשתמשת ב-API sendTextQuery() כדי לשלוח שאילתת טקסט לפעולה
  • הפעולה 'כתיבה לאחסון בבית' ואירועים אחרים של Assistant

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

ה-API מדווח על הסטטוסים הבאים:

  • LISTENING – סמל המיקרופון פתוח.
  • IDLE – אם המיקרופון סגור.
  • PROCESSING – מציין ש-Assistant מבצעת עכשיו שאילתה, והמיקרופון סגור.

ה-API מדווח על סטטוס הקלט לפעולה בכל פעם שהסטטוס משתנה.

אמנם ניתן לעבור בין מצבים, אך התהליכים הבאים נפוצים:

  • IDLE>LISTENING>PROCESSING>IDLE – המשתמש אומר שאילתה, השאילתה מעובדת והמיקרופון נסגר.
  • IDLE>PROCESSING>IDLE – אפליקציית האינטרנט משתמשת ב-API של sendTextQuery() כדי לשלוח שאילתות טקסט אל הפעולה.
  • IDLE>LISTENING>IDLE – המשתמש פותח את המיקרופון אבל לא אומר שאילתה.

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

onInputStatusChanged(inputStatus) {
   console.log("The new input status is: ", inputStatus);
}

הקריאה החוזרת onInputStatusChanged() מחזירה פרמטר enum יחיד, inputStatus. אפשר לבדוק את הערך הזה כדי לראות את סטטוס הקלט הנוכחי. הערך בשדה inputStatus יכול להיות LISTENING, PROCESSING או IDLE.

לאחר מכן מוסיפים את onInputStatusChanged() לאובייקט callbacks כדי לרשום אותו, כפי שמוצג בקטע הקוד הבא:

 /**
  * Register all callbacks used by the Interactive Canvas Action
  * executed during game creation time.
  */
 setCallbacks() {
   const that = this;
   // Declare the Interactive Canvas action callbacks.
   const callbacks = {
     onUpdate(data) {
       console.log('Received data', data);
     },
     onInputStatusChanged(inputStatus) {
       console.log("The new input status is: ", inputStatus);
     },
   };
   // Called by the Interactive Canvas web app once web app has loaded to
   // register callbacks.
   this.canvas.ready(callbacks);
 }
}