Lệnh gọi lại

Bạn có thể triển khai các lệnh gọi lại sau trong Thao tác Canvas tương tác:

onUpdate()

Lệnh gọi lại onUpdate() sẽ truyền dữ liệu từ webhook đến ứng dụng web của bạn để cập nhật ứng dụng web cho phù hợp. Bạn chỉ nên sử dụng lệnh gọi lại này với mô hình thực hiện phía máy chủ của quá trình phát triển Canvas tương tác.

Để biết thêm thông tin về onUpdate(), hãy xem bài viết Truyền dữ liệu để cập nhật ứng dụng web.

onTtsMark()

Lệnh gọi lại onTtsMark() được gọi khi các thẻ <mark> tuỳ chỉnh có trong Ngôn ngữ đánh dấu tổng hợp lời nói (SSML) của câu trả lời được đọc cho người dùng trong quá trình chuyển văn bản sang lời nói (TTS). Bạn có thể sử dụng onTtsMark() trong cả mô hình phát triển phương thức thực hiện phía máy chủ và phía máy khách.

Trong các đoạn mã sau, onTtsMark() đồng bộ hoá ảnh động của ứng dụng web với đầu ra TTS tương ứng. Khi Hành động nói với người dùng: "Rất tiếc, bạn đã thua", ứng dụng web sẽ đọc từ chính xác và hiển thị các chữ cái cho người dùng.

Trong ví dụ sau, trình xử lý webhook revealWord bao gồm một dấu tuỳ chỉnh để phản hồi người dùng khi họ thua trò chơi:

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());
});
…

Sau đó, đoạn mã sau đây sẽ đăng ký lệnh gọi lại onTtsMark(), kiểm tra tên của nhãn và thực thi hàm revealCorrectWord() nhằm cập nhật ứng dụng web:

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()

Lệnh gọi lại onInputStatusChanged() sẽ thông báo cho bạn khi trạng thái nhập thay đổi trong Thao tác Canvas tương tác. Các thay đổi về trạng thái đầu vào cho biết thời điểm micrô mở và đóng hoặc khi Trợ lý đang xử lý một truy vấn. Sau đây là các sự kiện có thể khiến trạng thái nhập thay đổi:

  • Người dùng đang nói với Hành động của bạn
  • Người dùng nhập văn bản trên Ứng dụng Google Tìm kiếm dành cho Android (AGS)
  • Ứng dụng web sử dụng API sendTextQuery() để gửi truy vấn văn bản đến Hành động
  • Hành động ghi vào bộ nhớ trong nhà và các sự kiện khác trên Trợ lý

Trường hợp sử dụng chính của lệnh gọi lại này là đồng bộ hoá Hành động của bạn với hoạt động tương tác bằng giọng nói của người dùng. Ví dụ: nếu người dùng đang chơi một trò chơi trên Canvas tương tác và mở micrô, thì bạn có thể tạm dừng trò chơi trong khi người dùng nói. Bạn cũng có thể đợi cho đến khi micrô mở để gửi truy vấn bằng văn bản đến Trợ lý nhằm đảm bảo nhận được yêu cầu đó.

API này báo cáo các trạng thái sau:

  • LISTENING – Cho biết micrô đang mở.
  • IDLE – Cho biết micrô đã đóng.
  • PROCESSING – Cho biết Trợ lý đang thực thi một truy vấn và micrô đã đóng.

API báo cáo trạng thái đầu vào cho Hành động của bạn mỗi khi trạng thái thay đổi.

Mặc dù bất kỳ quá trình chuyển đổi nào giữa các trạng thái đều có thể xảy ra, nhưng các quy trình sau đây đều phổ biến:

  • IDLE>LISTENING>PROCESSING>IDLE – Người dùng nói một truy vấn, truy vấn đó được xử lý và micrô đóng lại.
  • IDLE>PROCESSING>IDLE – Ứng dụng web sử dụng API sendTextQuery() để gửi truy vấn văn bản đến Hành động.
  • IDLE>LISTENING>IDLE – Người dùng mở micrô nhưng không nói truy vấn.

Để sử dụng tính năng này trong Hành động, hãy thêm onInputStatusChanged() vào mã ứng dụng web, như minh hoạ trong đoạn mã sau:

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

Lệnh gọi lại onInputStatusChanged() trả về một tham số enum duy nhất là inputStatus. Bạn có thể kiểm tra giá trị này để xem trạng thái hiện tại của mục nhập. inputStatus có thể là LISTENING, PROCESSING hoặc IDLE.

Tiếp theo, hãy thêm onInputStatusChanged() vào đối tượng callbacks để đăng ký đối tượng này, như minh hoạ trong đoạn mã sau:

 /**
  * 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);
 }
}