Kể từ ngày 13 tháng 6 năm 2023, Hành động trò chuyện không còn được dùng nữa. Để biết thêm thông tin, hãy xem phần Hành động trò chuyện ngừng hoạt động.

Trang này được dịch bởi Cloud Translation API.

Tiếp tục xây dựng bằng phương thức thực hiện phía máy khách hoặc phía máy chủ

Giờ đây, sau khi đã tìm hiểu kiến thức cơ bản, bạn có thể cải thiện và tuỳ chỉnh Hành động của mình bằng các phương thức dành riêng cho Canvas. Bạn có thể chọn phát triển Hành động của mình bằng mô hình phương thức thực hiện ứng dụng hoặc mô hình thực hiện phía máy chủ khi tạo dự án Actions. Để biết thêm thông tin về các tuỳ chọn này, hãy xem bài viết Bật Canvas tương tác.

Nếu chọn tuỳ chọn mô hình thực hiện ứng dụng, bạn có thể dùng những gợi ý sau trong Hành động của mình:

Tất cả API được liệt kê trong phần Tạo bằng phương thức thực hiện phía máy khách
Tất cả API được liệt kê trong phần Tạo bằng phương thức thực hiện phía máy chủ

Lưu ý: Đối với phương thức thực hiện phía máy khách, bạn chỉ nên gọi một webhook cho những tính năng không phải Canvas cần đến webhook, chẳng hạn như liên kết tài khoản.
Lệnh gọi lại onTtsMark()

Nếu chọn tuỳ chọn mô hình thực hiện của máy chủ, bạn có thể dùng những gợi ý sau trong Hành động của mình:

Tất cả API được liệt kê trong phần Tạo bằng phương thức thực hiện phía máy chủ
Lệnh gọi lại

Bạn không nên dùng một số API Canvas tương tác để sử dụng với một mô hình thực hiện đơn hàng cụ thể. Bảng sau đây cho thấy các API được bật khi bạn chọn tuỳ chọn phương thức thực hiện ứng dụng, và liệu các API này có được đề xuất hay không nên áp dụng cho mỗi mô hình:

Tên API	Có hỗ trợ trong mô hình thực hiện của máy chủ không?	Mô hình thực hiện đơn hàng có được hỗ trợ không?
`sendTextQuery()`	Có	Được hỗ trợ nhưng không nên (xem sendtextQuery() để biết thêm thông tin)
`outputTts()`	Có	Có
`triggerScene()`	Không	Có
`createIntentHandler(), expect(), clearExpectations(), prompt()`	Không	Có
`createNumberSlot(),createTextSlot, createConfirmationSlot, createOptionsSlot()`	Không	Có
`setHomeParam(), getHomeParam(), setUserParam(), getUserParam()`	Không	Có

Các phần sau đây giải thích cách triển khai API cho mô hình thực hiện máy khách và mô hình thực hiện phía máy chủ trong Thao tác Canvas tương tác.

Tạo bản dựng bằng phương thức thực hiện phía máy khách

Bạn có thể triển khai các API Canvas tương tác sau đây trong logic của ứng dụng web:

`outputTts()`

API này cho phép bạn xuất văn bản sang lời nói (TTS) từ thiết bị mà không cần gửi lời nhắc tĩnh từ Trình tạo hành động hoặc gọi webhook. Nếu không yêu cầu logic phía máy chủ liên kết với chức năng TTS, bạn có thể sử dụng outputTts() từ phía máy khách để bỏ qua chuyến đi đến máy chủ và cung cấp phản hồi nhanh hơn cho người dùng.

outputTts() phía máy khách có thể làm gián đoạn hoặc huỷ tính năng TTS phía máy chủ. Bạn có thể tránh làm gián đoạn tính năng TTS phía máy chủ bằng cách thực hiện các biện pháp phòng ngừa sau:

Tránh gọi outputTts() ở đầu phiên; thay vào đó, hãy sử dụng tính năng TTS phía máy chủ trong lượt trò chuyện đầu tiên của Hành động.
Tránh gọi outputTts() liên tiếp mà không có hành động của người dùng ở giữa.

Đoạn mã sau đây cho biết cách sử dụng outputTts() để xuất TTS từ phía máy khách:

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

Bạn cũng có thể sử dụng outputTts() với onTtsMark() để đặt điểm đánh dấu SSML vào trình tự văn bản. Việc sử dụng onTtsMark() sẽ đồng bộ hoá ảnh động trong ứng dụng web hoặc trạng thái trò chơi tại các điểm cụ thể của chuỗi TTS SSML, như minh hoạ trong đoạn mã sau:

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

Trong ví dụ trước, 2 đánh dấu tuỳ chỉnh phản hồi của bạn sẽ được gửi đến ứng dụng web thông qua TTS.

Xử lý việc thực hiện ý định trên máy khách

Trong mô hình phương thức thực hiện của máy chủ cho Canvas tương tác, tất cả các ý định phải được một webhook xử lý. Điều này làm tăng độ trễ trong Hành động của bạn. Thay vì gọi webhook, bạn có thể xử lý phương thức thực hiện ý định trong ứng dụng web.

Để xử lý ý định ở phía máy khách, bạn có thể sử dụng các API sau:

createIntentHandler(): Phương thức cho phép bạn xác định trình xử lý ý định trong mã ứng dụng web cho các ý định tuỳ chỉnh được xác định trong Trình tạo hành động.
expect(): Phương thức kích hoạt/đăng ký trình xử lý ý định để người dùng có thể so khớp ý định.
clearExpectations(): Một phương thức giúp xoá kỳ vọng của mọi ý định đang được kích hoạt sao cho không thể so khớp ý định, ngay cả khi người dùng nói một cách nói khớp với ý định.
deleteHandler(): Một phương thức vô hiệu hoá từng trình xử lý ý định để không thể so khớp các ý định đó.

Với những API này, bạn có thể kích hoạt hoặc tắt một cách có chọn lọc các ý định cho nhiều trạng thái của tương tác Canvas Action. Bạn phải sử dụng expect() trên trình xử lý ý định để kích hoạt các ý định đó.

Kích hoạt trình xử lý ý định

Việc kích hoạt trình xử lý ý định là quy trình gồm 2 bước. Trước tiên, bạn phải xác định ý định trong Trình tạo hành động. Tiếp theo, để có thể so khớp ý định, bạn cần gọi expect() trên trình xử lý ý định.

Để định cấu hình và kích hoạt trình xử lý ý định ở phía máy khách, hãy làm theo các bước sau:

Mở dự án của bạn trong bảng điều khiển Actions (Thao tác) rồi thêm một Ý định tuỳ chỉnh.
Chọn Có cho câu hỏi Đây có phải là ý định chung không?

Lưu ý: Những ý định bạn tạo trong Trình tạo hành động được kích hoạt từ phía máy khách phải được định cấu hình là ý định chung.
Định cấu hình ý định của bạn rồi nhấp vào Lưu.

Xác định trình xử lý cho ý định trong logic của ứng dụng web, như minh hoạ trong đoạn mã sau:

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

Gọi phương thức expect() để đăng ký trình xử lý ý định, như minh hoạ trong đoạn mã sau:

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

Tắt trình xử lý ý định

Sau khi xác định trình xử lý ý định, bạn có thể kích hoạt hoặc huỷ kích hoạt ý định cho Hành động của mình nếu cần. Khi bạn gọi expect() để kích hoạt một ý định, ý định này sẽ trả về một đối tượng có phương thức deleteHandler(). Bạn có thể sử dụng phương thức này để tắt trình xử lý mới tạo. Định nghĩa của trình xử lý ý định sẽ vẫn tồn tại ngay cả khi ý định hiện không hoạt động, vì vậy, bạn có thể kích hoạt lại ý định khi cần.

Để tắt trình xử lý ý định, hãy gọi deleteHandler() trên trình xử lý ý định, như minh hoạ trong đoạn mã sau:

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

Bạn có thể gọi expect() để thêm lại trình xử lý ý định đã tắt, như minh hoạ trong đoạn mã sau:

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

Để tắt hàng loạt ý định, bạn có thể sử dụng phương thức clearExpectations(). Phương thức này sẽ vô hiệu hoá mọi ý định hiện được kích hoạt. Đoạn mã sau đây cho biết cách xoá kỳ vọng đối với tất cả các trình xử lý ý định:

interactiveCanvas.clearExpectations();

Xử lý việc lấp đầy ô trên ứng dụng

Thay vì thêm lấp đầy vị trí vào cảnh trong Trình tạo hành động, bạn có thể xử lý việc lấp đầy vị trí ngay trong ứng dụng web.

Để xử lý việc lấp đầy vị trí ở phía máy khách, trước tiên bạn phải tạo một khu vực bằng một trong các API sau:

createNumberSlot(callback, hints): Phương thức cho phép bạn xác định một ô số trong mã ứng dụng web của mình. Dùng để nhắc người dùng nhập một số điện thoại.
createTextSlot(callback, hints): Phương thức cho phép bạn xác định một ô văn bản trong mã ứng dụng web của mình. Dùng để nhắc người dùng nhập một từ.
createConfirmationSlot(callback, hints): Phương thức cho phép bạn xác định vùng xác nhận trong mã ứng dụng web của mình. Dùng để nhắc người dùng xác nhận (có/không).
createOptionsSlot(options, callback, hints): Phương thức cho phép bạn xác định một ô tuỳ chọn trong mã ứng dụng web của mình. Dùng để nhắc người dùng chọn trong danh sách các tuỳ chọn được xác định trước.

Khi tạo một vùng, bạn có thể tuỳ ý xác định triggerHints. Đây là các từ khoá giúp cải thiện hệ thống hiểu ngôn ngữ tự nhiên (NLU) cho Hành động của bạn. Các từ khoá này nên là những từ ngắn mà người dùng có thể nói khi lấp đầy một chỗ trống. Ví dụ: từ khoá triggerHints cho vùng số có thể là years. Khi người dùng trả lời câu hỏi về độ tuổi của họ trong cuộc trò chuyện với câu trả lời "Tôi đã 30 tuổi", Hành động của bạn có nhiều khả năng nhận ra rằng người dùng đang lấp đầy khoảng thời gian phù hợp.

Sau khi tạo một khu vực, bạn có thể nhắc người dùng về một khu vực bằng cách sử dụng API prompt:

prompt(tts, slot): Một phương thức sẽ xuất TTS cho người dùng, nhắc họ về một ô trống dự kiến sẽ được lấp đầy.

Việc gọi prompt() sẽ trả về một lời hứa với trạng thái và giá trị của vị trí đã lấp đầy.

Tạo ô số

Ô số cho phép bạn nhắc người dùng nhập một số điện thoại trong cuộc trò chuyện. Để biết thêm thông tin về việc lấp đầy vị trí, hãy xem mục Lấp đầy vị trí trong tài liệu về Trình tạo hành động.

Để nhắc người dùng điền vào một ô số ở phía máy khách, hãy làm theo các bước sau:

Gọi phương thức createNumberSlot() để tạo khe số trong logic ứng dụng web:

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

Gọi phương thức prompt() để nhắc người dùng về vị trí và xử lý giá trị vị trí từ lời hứa được trả về như minh hoạ trong đoạn mã sau:

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

Tạo vùng văn bản

Ô văn bản cho phép bạn nhắc người dùng nhập một từ trong cuộc trò chuyện. Để biết thêm thông tin về việc lấp đầy vị trí, hãy xem mục Lấp đầy vị trí trong tài liệu về Trình tạo hành động.

Để nhắc người dùng điền vào một vùng văn bản ở phía máy khách, hãy làm theo các bước sau:

Gọi phương thức createTextSlot() để tạo một khe văn bản trong logic của ứng dụng web:

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

Gọi phương thức prompt() để nhắc người dùng về vị trí và xử lý giá trị vị trí từ lời hứa được trả về như minh hoạ trong đoạn mã sau:

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

Tạo khung xác nhận

Ô xác nhận cho phép bạn nhắc người dùng xác nhận (người dùng có thể trả lời "Có" hoặc "Không" để lấp đầy vị trí). Để biết thêm thông tin về việc lấp đầy vị trí, hãy xem mục Lấp đầy vị trí trong tài liệu về Trình tạo hành động.

Để nhắc người dùng điền vào một vùng xác nhận ở phía máy khách, hãy làm theo các bước sau:

Gọi phương thức createConfirmationSlot() để tạo vùng xác nhận trong logic ứng dụng web:

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

Gọi phương thức prompt() để nhắc người dùng về vị trí và xử lý giá trị vị trí từ lời hứa được trả về như minh hoạ trong đoạn mã sau:

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

Vị trí tạo tuỳ chọn

Vùng tuỳ chọn cho phép bạn nhắc người dùng chọn trong danh sách các tuỳ chọn được xác định trước. Để biết thêm thông tin về việc lấp đầy vị trí, hãy xem mục Lấp đầy vị trí trong tài liệu về Trình tạo hành động.

Để nhắc người dùng điền vào một vùng tuỳ chọn ở phía máy khách, hãy làm theo các bước sau:

Gọi phương thức createOptionsSlot() để tạo vùng tuỳ chọn trong logic ứng dụng web:

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

Gọi phương thức prompt() để nhắc người dùng về vị trí và xử lý giá trị vị trí từ lời hứa được trả về như minh hoạ trong đoạn mã sau:

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() cho phép bạn chuyển sang một cảnh khác trong Hành động Canvas tương tác từ phương thức thực hiện phía máy khách. Với triggerScene(), bạn cũng có thể chuyển từ phương thức thực hiện phía máy khách sang phương thức thực hiện phía máy chủ khi người dùng cần truy cập vào cảnh hệ thống trong Trình tạo hành động yêu cầu webhook. Ví dụ: bạn có thể gọi triggerScene() khi người dùng cần liên kết tài khoản của họ hoặc nhận thông báo; sau đó, bạn có thể trả về từ cảnh đó đến phương thức thực hiện phía máy khách bằng lời nhắc Canvas.

Đoạn mã sau đây cho biết cách triển khai triggerScene() trong Hành động của bạn:

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

Bộ nhớ của trang chủ và bộ nhớ của người dùng trên ứng dụng

Thay vì sử dụng webhook để nhận và đặt giá trị bộ nhớ cho nhà cũng như bộ nhớ của người dùng, bạn có thể gọi API phía máy khách để xử lý bộ nhớ của nhà và bộ nhớ của người dùng trong ứng dụng web. Sau đó, ứng dụng web của bạn có thể dùng các giá trị được lưu trữ này trong nhiều phiên hoạt động (ví dụ: trong lời nhắc và điều kiện), đồng thời có thể truy cập vào các giá trị của một hộ gia đình hoặc người dùng cụ thể khi cần. Việc sử dụng các API này có thể giúp giảm độ trễ cho Hành động Canvas tương tác của bạn vì bạn không còn cần phải gọi webhook để nhận và đặt các giá trị bộ nhớ.

Bộ nhớ của trang chủ và bộ nhớ của người dùng trong ứng dụng web tuân theo các nguyên tắc chung giống như bộ nhớ trong webhook. Để biết thêm thông tin về bộ nhớ của nhà và bộ nhớ của người dùng, hãy xem tài liệu về Bộ nhớ trong nhà và Bộ nhớ của người dùng.

Bộ nhớ phía máy khách

Bộ nhớ trên màn hình chính cho phép bạn lưu trữ các giá trị cho người dùng hộ gia đình dựa trên biểu đồ màn hình chính và được chia sẻ trên tất cả các phiên trong hộ gia đình. Ví dụ: nếu một người dùng chơi trò chơi Canvas tương tác trong một hộ gia đình, thì điểm số của trò chơi đó có thể được lưu trữ trong bộ nhớ nhà, và các thành viên khác trong gia đình có thể tiếp tục chơi trò chơi đó với điểm số đã lưu trữ.

Để cho phép Hành động của bạn hỗ trợ bộ nhớ trong nhà, hãy làm theo các bước sau:

Trong bảng điều khiển Actions (Thao tác), hãy chuyển đến phần Triển khai > Thông tin thư mục > Thông tin bổ sung.
Chọn hộp Có cho mục Hành động của bạn có sử dụng bộ nhớ trong nhà không?

Để ghi một giá trị vào bộ nhớ trên màn hình chính trong ứng dụng web, hãy gọi phương thức setHomeParam() như minh hoạ trong đoạn mã sau:

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

Để đọc một giá trị từ bộ nhớ nhà riêng trong ứng dụng web, hãy gọi phương thức getHomeParam() như trong đoạn mã sau:

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

Để xoá toàn bộ bộ nhớ hiện có của nhà, hãy gọi phương thức resetHomeParam() như minh hoạ trong đoạn mã sau:

interactiveCanvas.resetHomeParam();

Bộ nhớ người dùng phía máy khách

Bộ nhớ người dùng cho phép bạn lưu trữ các giá trị thông số cho một người dùng cụ thể, đã xác minh trong nhiều phiên. Ví dụ: nếu một người dùng đang chơi một trò chơi, hệ thống có thể lưu trữ điểm số của trò chơi cho người dùng đó. Trong phiên chơi tiếp theo, người dùng có thể tiếp tục chơi trò chơi với cùng một điểm số.

Để ghi giá trị vào bộ nhớ của người dùng trong ứng dụng web, hãy gọi phương thức setUserParam() như minh hoạ trong đoạn mã sau:

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

Để đọc một giá trị từ bộ nhớ của người dùng trong ứng dụng web, hãy gọi phương thức getUserParam() như trong đoạn mã sau:

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

Để xoá toàn bộ bộ nhớ hiện có của người dùng, hãy gọi phương thức resetUserParam() như minh hoạ trong đoạn mã sau:

interactiveCanvas.resetUserParam();

`setCanvasState()`

Phương thức setCanvasState() cho phép bạn gửi dữ liệu trạng thái từ ứng dụng web Canvas tương tác đến phương thức thực hiện của bạn và thông báo cho Trợ lý rằng ứng dụng web đã cập nhật trạng thái. Ứng dụng web gửi trạng thái đã cập nhật dưới dạng đối tượng JSON.

Việc gọi setCanvasState() không gọi ra một ý định. Sau khi gọi setCanvasState(), nếu sendTextQuery() được gọi hoặc truy vấn của người dùng khớp với một ý định trong cuộc trò chuyện, thì dữ liệu đã được thiết lập bằng setCanvasState() trong lượt trò chuyện trước đó sẽ có sẵn trong các lượt trò chuyện tiếp theo.

Trong đoạn mã sau, ứng dụng web dùng setCanvasState() để thiết lập dữ liệu trạng thái Canvas:

JavaScript

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

Trạng thái Canvas tham chiếu từ webhook

Bạn có thể tham chiếu các giá trị trạng thái Canvas được lưu trữ trong mã thực hiện đơn hàng. Để tham chiếu giá trị, hãy sử dụng cú pháp conv.context.canvas.state.KEY, trong đó KEY là khoá được cung cấp khi đặt giá trị trạng thái Canvas.

Ví dụ: nếu trước đây bạn đã lưu trữ giá trị điểm cao cho một trò chơi trong trạng thái Canvas dưới dạng tham số score, hãy tham chiếu giá trị đó bằng cách sử dụng conv.context.canvas.state.score để truy cập giá trị đó trong phương thức thực hiện:

Node.js

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

Trạng thái Canvas tham chiếu trong câu lệnh

Bạn có thể tham chiếu các giá trị trạng thái Canvas được lưu trữ trong câu lệnh. Để tham chiếu giá trị, hãy sử dụng cú pháp $canvas.state.KEY, trong đó KEY là khoá được cung cấp khi đặt giá trị trạng thái Canvas.

Ví dụ: nếu trước đây bạn đã lưu trữ giá trị điểm cao cho một trò chơi ở trạng thái Canvas dưới dạng tham số score, hãy tham chiếu giá trị đó bằng cách sử dụng $canvas.state.score để truy cập vào giá trị đó trong lời nhắc:

JSON

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

Trạng thái Canvas tham chiếu trong các điều kiện

Bạn cũng có thể tham chiếu các giá trị trạng thái Canvas được lưu trữ trong các điều kiện. Để tham chiếu giá trị, hãy sử dụng cú pháp canvas.state.KEY, trong đó KEY là khoá được cung cấp khi đặt giá trị trạng thái Canvas.

Ví dụ: nếu trước đây bạn đã lưu trữ giá trị điểm cao cho một trò chơi ở trạng thái Canvas dưới dạng tham số score và muốn so sánh giá trị đó với giá trị 999 trong một điều kiện, thì bạn có thể tham chiếu giá trị được lưu trữ trong điều kiện của mình bằng cách sử dụng canvas.state.score. Biểu thức điều kiện của bạn sẽ có dạng như sau:

Cú pháp điều kiện

canvas.state.score >= 999

`sendTextQuery()`

Phương thức sendTextQuery() gửi truy vấn văn bản đến Hành động trò chuyện để so khớp một ý định theo phương thức lập trình. Mẫu này sử dụng sendTextQuery() để khởi động lại trò chơi quay hình tam giác khi người dùng nhấp vào một nút. Khi người dùng nhấp vào nút "Khởi động lại trò chơi", sendTextQuery() sẽ gửi một truy vấn văn bản khớp với ý định Restart game và trả về một lời hứa. Lời hứa này sẽ dẫn đến SUCCESS nếu ý định được kích hoạt và BLOCKED nếu ý định không được kích hoạt. Đoạn mã sau đây khớp với ý định và xử lý các trường hợp thành công và thất bại của lời hứa:

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

Nếu lời hứa này dẫn đến SUCCESS, thì trình xử lý webhook Restart game sẽ gửi phản hồi Canvas đến ứng dụng web của bạn:

JavaScript

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

Phản hồi Canvas này sẽ kích hoạt lệnh gọi lại onUpdate(), lệnh này sẽ thực thi mã trong đoạn mã RESTART_GAME dưới đây:

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;
},
…

Tạo bản dựng bằng phương thức thực hiện phía máy chủ

Bạn có thể triển khai các API Canvas tương tác sau đây trong webhook:

Bật chế độ toàn màn hình

Theo mặc định, các ứng dụng web Canvas tương tác bao gồm một tiêu đề ở đầu màn hình cùng với tên Hành động của bạn. Bạn có thể sử dụng enableFullScreen để xoá tiêu đề và thay thế bằng một thông báo ngắn tạm thời xuất hiện trong màn hình tải, cho phép người dùng có trải nghiệm toàn màn hình trong khi tương tác với Hành động của bạn. Thông báo ngắn cho thấy tên hiển thị của Hành động, tên nhà phát triển và hướng dẫn thoát khỏi Hành động đó, đồng thời màu sắc của thông báo ngắn sẽ thay đổi tuỳ theo nội dung mà người dùng chọn làm giao diện trên thiết bị của họ.

**Hình 1.** Một thông báo ngắn trên màn hình tải cho một Hành động.

Nếu người dùng thường xuyên tương tác với Hành động của bạn, thì thông báo ngắn sẽ tạm thời dừng xuất hiện trên màn hình tải. Nếu người dùng không tương tác với Hành động của bạn trong một khoảng thời gian, thì thông báo ngắn sẽ xuất hiện lại khi họ khởi chạy Hành động đó.

Bạn có thể bật chế độ toàn màn hình trong webhook hoặc trong lời nhắc tĩnh trong Trình tạo hành động.

Để bật chế độ toàn màn hình trong webhook, hãy làm theo bước sau:

Đặt trường enableFullScreen thành true trong phản hồi canvas đầu tiên do webhook trả về trong một phiên. Đoạn mã sau đây là một ví dụ về cách triển khai bằng cách sử dụng thư viện ứng dụng 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);

Để bật chế độ toàn màn hình trong lời nhắc tĩnh trong Trình tạo hành động, hãy làm theo các bước sau:

Mở dự án trong Bảng điều khiển Actions.
Nhấp vào Phát triển trong thanh điều hướng và mở lời nhắc bao gồm phản hồi canvas đầu tiên.

Đặt enable_full_screen thành true, như minh hoạ trong đoạn mã sau:

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

`continueTtsDuringTouch`

Theo mặc định, khi người dùng nhấn vào màn hình trong khi sử dụng Thao tác Canvas tương tác, TTS sẽ ngừng phát. Bạn có thể bật tính năng TTS để tiếp tục phát khi người dùng chạm vào màn hình bằng continueTtsDuringTouch. Không thể bật và tắt hành vi này trong cùng một phiên.

Bạn có thể triển khai hành vi này trong webhook hoặc trong lời nhắc tĩnh trong Trình tạo hành động.

Để bật tính năng TTS tiếp tục sau khi người dùng nhấn vào màn hình trong webhook của bạn, hãy làm theo bước sau:

Đặt trường continueTtsDuringTouch thành true trong phản hồi canvas đầu tiên do webhook trả về trong một phiên. Đoạn mã sau đây là một ví dụ về cách triển khai bằng cách sử dụng thư viện ứng dụng 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);

Để cho phép tính năng TTS tiếp tục sau khi người dùng nhấn vào màn hình trong lời nhắc tĩnh trong Trình tạo thao tác, hãy làm theo các bước sau:

Mở dự án trong Bảng điều khiển Actions.
Nhấp vào Phát triển trong thanh điều hướng và mở lời nhắc bao gồm phản hồi canvas đầu tiên.

Đặt continue_tts_during_touch thành true, như minh hoạ trong đoạn mã sau:

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