回呼

您可以在互動式畫布動作中實作下列回呼:

onUpdate()

onUpdate() 回呼會將 Webhook 中的資料傳送至網頁應用程式,以便正確更新網頁應用程式。這個回呼只應與互動式畫布開發的伺服器端執行要求模型搭配使用。

如要進一步瞭解 onUpdate(),請參閱「傳遞資料以更新網頁應用程式」。

onTtsMark()

當語音轉語音 (TTS) 的語音合成標記語言 (SSML) 中納入回應時,系統會呼叫 onTtsMark() 回呼。<mark>您可以在伺服器端和用戶端執行要求開發模型中使用 onTtsMark()

在下列程式碼片段中,onTtsMark() 會將網頁應用程式的動畫與對應的 TTS 輸出內容同步處理。此動作向使用者指出「很抱歉,你遺失了」時,網頁應用程式會拼出正確的字詞,並向使用者顯示字母。

在以下範例中,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()

當互動式畫布動作中的輸入狀態變更時,onInputStatusChanged() 回呼會通知您。輸入狀態變更表示麥克風何時開啟和關閉,或 Google 助理正在處理查詢。以下事件可能會導致輸入狀態變更:

  • 使用者與您的動作交談
  • 使用者在 Android Google 搜尋應用程式 (AGSA) 上輸入文字
  • 使用 sendTextQuery() API 將文字查詢傳送至動作的網頁應用程式
  • 動作會寫入住家儲存空間和其他 Google 助理事件

這個回呼的主要用途是將您的動作與使用者的語音互動同步處理。舉例來說,如果使用者正在玩互動式畫布遊戲並開啟麥克風,您就可以在使用者說話時暫停遊戲。您也可以等到麥克風開啟,再向 Google 助理傳送文字查詢,確保裝置能接收查詢內容。

這個 API 會回報下列狀態:

  • LISTENING - 表示麥克風已開啟。
  • IDLE - 表示麥克風已關閉。
  • PROCESSING:表示 Google 助理目前正在執行查詢,且麥克風已關閉。

每次狀態變更時,API 都會向動作回報輸入狀態。

雖然可以在狀態之間進行任何轉換,但常見流程如下:

  • IDLE>LISTENING>PROCESSING>IDLE:使用者說查詢,已處理查詢並關閉麥克風。
  • IDLE>PROCESSING>IDLE:網頁應用程式使用 sendTextQuery() API 將文字查詢傳送至動作。
  • IDLE>LISTENING>IDLE:使用者開啟麥克風,但並未說出查詢。

如要在動作中使用這項功能,請將 onInputStatusChanged() 加入網頁應用程式程式碼,如以下程式碼片段所示:

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

onInputStatusChanged() 回呼會傳回單一列舉參數 inputStatus。您可以檢查這個值來查看目前的輸入狀態。inputStatus 可以是 LISTENINGPROCESSINGIDLE

接下來,請將 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);
 }
}