Định cấu hình ứng dụng web của bạn

Ứng dụng web là giao diện người dùng (UI) cho một Hành động sử dụng Canvas tương tác. Bạn có thể sử dụng các công nghệ web hiện có (chẳng hạn như HTML, CSS, JavaScript và WebAssembly) để thiết kế và phát triển ứng dụng web. Đối với hầu hết các công nghệ, Canvas tương tác có thể hiển thị nội dung web như một trình duyệt, nhưng có một vài quy định hạn chế được áp dụng đối với quyền riêng tư và tính bảo mật của người dùng. Trước khi bắt đầu thiết kế giao diện người dùng, hãy cân nhắc các nguyên tắc thiết kế được nêu trong Nguyên tắc thiết kế. Bạn nên sử dụng lưu trữ Firebase để triển khai ứng dụng web.

HTML và JavaScript cho ứng dụng web của bạn thực hiện những việc sau:

Trang này sẽ đề cập đến các cách đề xuất để tạo ứng dụng web, cách cho phép giao tiếp giữa Hành động trò chuyện và ứng dụng web, cũng như các nguyên tắc và hạn chế chung.

Mặc dù bạn có thể dùng bất kỳ phương thức nào để xây dựng giao diện người dùng, nhưng bạn nên sử dụng các thư viện sau:

Cấu trúc

Bạn nên sử dụng cấu trúc ứng dụng một trang. Phương pháp này mang lại hiệu suất tối ưu và hỗ trợ trải nghiệm người dùng trò chuyện liên tục. Bạn có thể sử dụng Canvas tương tác cùng với các khung giao diện người dùng như Vue, Angular và React để hỗ trợ quản lý trạng thái.

Tệp HTML

Tệp HTML xác định giao diện người dùng của bạn. Tệp này cũng tải API Canvas tương tác, cho phép giao tiếp giữa ứng dụng web và Hành động trò chuyện.

HTML

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>Interactive Canvas Sample</title>

    <!-- Disable favicon requests -->
    <link rel="shortcut icon" type="image/x-icon" href="data:image/x-icon;,">

    <!-- Load Interactive Canvas JavaScript -->
    <script src="https://www.gstatic.com/assistant/interactivecanvas/api/interactive_canvas.min.js"></script>

    <!-- Load PixiJS for graphics rendering -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/pixi.js/4.8.7/pixi.min.js"></script>

    <!-- Load Stats.js for fps monitoring -->
    <script src="https://cdnjs.cloudflare.com/ajax/libs/stats.js/r16/Stats.min.js"></script>

    <!-- Load custom CSS -->
    <link rel="stylesheet" href="css/main.css">
  </head>
  <body>
    <div id="view" class="view">
      <div class="debug">
        <div class="stats"></div>
        <div class="logs"></div>
      </div>
    </div>
    <!-- Load custom JavaScript after elements are on page -->
    <script src="js/log.js"></script>
    <script type="module" src="js/main.js"></script>
  </body>
</html>

Giao tiếp giữa Hành động trò chuyện và ứng dụng web

Sau khi tạo ứng dụng web và Hành động trò chuyện, rồi tải vào Thư viện Canvas tương tác trong tệp ứng dụng web, bạn cần xác định cách ứng dụng web và Hành động trò chuyện tương tác. Để thực hiện việc này, hãy sửa đổi các tệp chứa logic ứng dụng web của bạn.

action.js

Tệp này chứa mã để xác định callbacks và gọi các phương thức thông qua interactiveCanvas. Lệnh gọi lại cho phép ứng dụng web của bạn phản hồi thông tin hoặc yêu cầu từ Hành động trò chuyện, còn các phương thức cung cấp cách gửi thông tin hoặc yêu cầu đến Hành động trò chuyện đó.

Thêm interactiveCanvas.ready(callbacks); vào tệp HTML của bạn để khởi chạy và đăng ký callbacks:

JavaScript

/**
* This class is used as a wrapper for Google Assistant Canvas Action class
* along with its callbacks.
*/
export class Action {
 /**
  * @param  {Phaser.Scene} scene which serves as a container of all visual
  * and audio elements.
  */
 constructor(scene) {
   this.canvas = window.interactiveCanvas;
   this.gameScene = scene;
   const that = this;
   this.intents = {
     GUESS: function(params) {
       that.gameScene.guess(params);
     },
     DEFAULT: function() {
       // do nothing, when no command is found
     },
   };
 }

 /**
  * 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) {
       const intent = data[0].google.intent;
       that.intents[intent ? intent.name.toUpperCase() : 'DEFAULT'](intent.params);
     },
   };
   // Called by the Interactive Canvas web app once web app has loaded to
   // register callbacks.
   this.canvas.ready(callbacks);
 }
}

main.js

Mô-đun JavaScript main.js nhập các tệp action.js và scene.js, đồng thời tạo các bản sao của từng tệp khi ứng dụng web tải. Mô-đun này cũng đăng ký các lệnh gọi lại cho Canvas tương tác.

JavaScript

import {Action} from './action.js';
import {Scene} from './scene.js';
window.addEventListener('load', () => {
  window.scene = new Scene();
  // Set Google Assistant Canvas Action at scene level
  window.scene.action = new Action(scene);
  // Call setCallbacks to register Interactive Canvas
  window.scene.action.setCallbacks();
});

scene.js

Tệp scene.js tạo cảnh cho ứng dụng web của bạn. Sau đây là một phần trích dẫn từ scene.js:

JavaScript

const view = document.getElementById('view');

// initialize rendering and set correct sizing
this.radio = window.devicePixelRatio;
this.renderer = PIXI.autoDetectRenderer({
  transparent: true,
  antialias: true,
  resolution: this.radio,
  width: view.clientWidth,
  height: view.clientHeight,
});
this.element = this.renderer.view;
this.element.style.width = `${this.renderer.width / this.radio}px`;
this.element.style.height = `${(this.renderer.height / this.radio)}px`;
view.appendChild(this.element);

// center stage and normalize scaling for all resolutions
this.stage = new PIXI.Container();
this.stage.position.set(view.clientWidth / 2, view.clientHeight / 2);
this.stage.scale.set(Math.max(this.renderer.width,
    this.renderer.height) / 1024);

// load a sprite from a svg file
this.sprite = PIXI.Sprite.from('triangle.svg');
this.sprite.anchor.set(0.5);
this.sprite.tint = 0x00FF00; // green
this.sprite.spin = true;
this.stage.addChild(this.sprite);

// toggle spin on touch events of the triangle
this.sprite.interactive = true;
this.sprite.buttonMode = true;
this.sprite.on('pointerdown', () => {
  this.sprite.spin = !this.sprite.spin;
});

Hỗ trợ tương tác chạm

Thao tác Canvas tương tác có thể phản hồi thao tác chạm của người dùng cũng như phản hồi bằng giọng nói của họ. Theo Nguyên tắc thiết kế Canvas tương tác, bạn nên phát triển Hành động của mình theo cách "ưu tiên lên tiếng". Tuy nhiên, một số màn hình thông minh hỗ trợ tương tác chạm.

Thao tác chạm hỗ trợ cũng tương tự như việc hỗ trợ phản hồi trò chuyện. Tuy nhiên, thay vì phản hồi bằng giọng nói của người dùng, JavaScript phía máy khách của bạn sẽ tìm các tương tác chạm và sử dụng các tương tác đó để thay đổi các thành phần trong ứng dụng web.

Bạn có thể xem ví dụ về cách này trong mẫu sử dụng thư viện Pixi.js:

JavaScript

…
this.sprite = PIXI.Sprite.from('triangle.svg');
…
this.sprite.interactive = true; // Enables interaction events
this.sprite.buttonMode = true; // Changes `cursor` property to `pointer` for PointerEvent
this.sprite.on('pointerdown', () => {
  this.sprite.spin = !this.sprite.spin;
});

Khắc phục sự cố

Mặc dù có thể sử dụng trình mô phỏng trong bảng điều khiển Actions để kiểm thử Hành động trên Canvas tương tác trong quá trình phát triển, nhưng bạn cũng có thể thấy các lỗi xảy ra trong ứng dụng web Canvas tương tác trên thiết bị của người dùng ở phiên bản chính thức. Bạn có thể xem những lỗi này trong nhật ký Google Cloud Platform.

Để xem các thông báo lỗi này trong nhật ký Google Cloud Platform, hãy làm theo các bước sau:

  1. Mở dự án Actions của bạn trong Bảng điều khiển Actions.
  2. Nhấp vào Test (Kiểm thử) ở thanh điều hướng trên cùng.
  3. Nhấp vào đường liên kết Xem nhật ký trong Google Cloud Platform.

Lỗi trên thiết bị của người dùng xuất hiện theo thứ tự thời gian trong trình xem nhật ký.

Các loại lỗi

Có ba loại lỗi ứng dụng web mà bạn có thể thấy trong nhật ký của Google Cloud Platform:

  • Thời gian chờ xảy ra khi ready không được gọi trong vòng 10 giây
  • Thời gian chờ xảy ra khi lời hứa được onUpdate() trả về không được thực hiện trong vòng 10 giây
  • Lỗi thời gian chạy JavaScript không được phát hiện trong ứng dụng web của bạn

Xem chi tiết lỗi JavaScript

Thông tin chi tiết về lỗi thời gian chạy JavaScript trong ứng dụng web không có sẵn theo mặc định. Để xem thông tin chi tiết về lỗi thời gian chạy JavaScript, hãy làm theo các bước sau:

  1. Đảm bảo rằng bạn đã định cấu hình các tiêu đề phản hồi HTTP chia sẻ tài nguyên nhiều nguồn gốc (CORS) phù hợp trong các tệp ứng dụng web. Để biết thêm thông tin, hãy xem bài viết Chia sẻ tài nguyên trên nhiều nguồn gốc.
  2. Thêm crossorigin="anonymous" vào các thẻ <script> đã nhập trong tệp HTML, như minh hoạ trong đoạn mã sau:
<script crossorigin="anonymous" src="<SRC>"></script>

Nguyên tắc và hạn chế

Hãy cân nhắc các nguyên tắc và hạn chế sau đây khi bạn phát triển ứng dụng web:

  • Không có cookie
  • Không có bộ nhớ cục bộ
  • Không có vị trí địa lý
  • Không sử dụng máy ảnh
  • Không có bản ghi âm thanh hoặc video
  • Không có cửa sổ bật lên
  • Duy trì giới hạn bộ nhớ dưới 200 MB
  • Xem xét tiêu đề Tên hành động khi hiển thị nội dung (chiếm phần trên của màn hình)
  • Không thể áp dụng kiểu nào cho video
  • Mỗi lần chỉ có thể sử dụng một phần tử nội dung nghe nhìn
  • Không có cơ sở dữ liệu Web SQL
  • Không hỗ trợ giao diện SpeechRecognition của Web Speech API.
  • Không áp dụng được chế độ cài đặt chế độ tối
  • Tính năng phát video được hỗ trợ trên màn hình thông minh. Để biết thêm thông tin về các định dạng vùng chứa nội dung nghe nhìn và bộ mã hoá và giải mã được hỗ trợ, hãy xem bài viết về bộ mã hoá và giải mã Google Nest Hub.

Chia sẻ tài nguyên trên nhiều nguồn gốc

Vì các ứng dụng web Canvas tương tác được lưu trữ trong một iframe và nguồn gốc được đặt thành rỗng, nên bạn phải bật tính năng chia sẻ tài nguyên trên nhiều nguồn gốc (CORS) cho máy chủ web và tài nguyên lưu trữ của mình. Quá trình này cho phép tài sản của bạn chấp nhận các yêu cầu từ nguồn gốc rỗng.

Các bước tiếp theo

Để thêm các tính năng khác vào ứng dụng web, hãy xem phần 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ủ.