設定網頁應用程式

網頁應用程式是指使用互動式畫布動作的使用者介面 (UI)。您可以使用現有的網路技術 (例如 HTML、CSS、JavaScript 和 WebAssembly) 來設計及開發網頁應用程式。大多數情況下,互動式 Canvas 可以轉譯網頁內容,就像瀏覽器一樣,但為了使用者隱私和安全,設有幾項限制。開始設計 UI 之前,請考量設計指南中所述的設計原則。建議您使用 Firebase 代管來部署網頁應用程式。

網頁應用程式的 HTML 和 JavaScript 會提供以下功能:

本頁將說明建構網頁應用程式的建議做法、如何在對話動作與網頁應用程式之間啟用通訊,以及一般指南和限制。

雖然您可以使用任何方法建構 UI,但 Google 建議您使用下列程式庫:

架構

Google 強烈建議使用單頁應用程式架構。這種方法可以達到最佳效能,並支援連續的對話體驗。互動式畫布可與 VueAngularReact 等前端架構搭配使用,藉此協助管理狀態。

HTML 檔案

HTML 檔案會定義使用者介面的外觀。這個檔案也會載入互動式 Canvas API,讓您在網頁應用程式和對話動作之間進行通訊

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>
    

在對話動作與網頁應用程式之間進行通訊

建立網頁應用程式和對話動作,並載入至網頁應用程式檔案的互動式 Canvas 程式庫後,您需要定義網頁應用程式和對話動作的互動方式。方法是修改包含網頁應用程式邏輯的檔案。

action.js

這個檔案含有定義callbacks的程式碼,並透過 interactiveCanvas 叫用方法。回呼可讓網頁應用程式回應「來自」對話動作的資訊或要求,而方法則提供傳送資訊或要求「傳送至」對話動作的方式。

interactiveCanvas.ready(callbacks); 新增至 HTML 檔案,以便初始化及註冊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

main.js JavaScript 模組會匯入 action.jsscene.js 檔案,並在網頁應用程式載入時為每個檔案建立例項。這個模組也會註冊互動畫布的回呼。

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

scene.js 檔案會建構網頁應用程式的場景。以下是 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;
});
    

支援觸控互動

互動式畫布動作可以回應使用者的觸控動作和使用者的語音輸入內容。根據互動畫布設計指南,您應將動作開發為「語音優先」。不過,有些智慧螢幕支援觸控互動。

輔助觸控與支援對話回應類似,不過用戶端 JavaScript 會尋找觸控互動,並使用此類互動變更網頁應用程式的元素。

您可以在範例中查看使用 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;
});
    

疑難排解

雖然您可以在動作主控台中使用模擬器,在開發期間測試互動式畫布動作,但您也可以查看互動式畫布網頁應用程式在實際工作環境中使用者裝置中發生的錯誤。您可以在 Google Cloud Platform 記錄檔中查看這些錯誤。

如要在 Google Cloud Platform 記錄中查看這些錯誤訊息,請按照下列步驟操作:

  1. Actions 主控台中開啟您的動作專案。
  2. 按一下頂端導覽列中的「測試」
  3. 按一下「查看 Google Cloud Platform 中的記錄檔」連結。

記錄檢視器中會依照時間順序顯示使用者裝置發生的錯誤。

錯誤類型

Google Cloud Platform 記錄檔中會顯示三種網頁應用程式錯誤:

  • 未於 10 秒內呼叫 ready 時發生的逾時
  • onUpdate() 傳回的承諾在 10 秒內未執行而發生逾時
  • 網頁應用程式未偵測到的 JavaScript 執行階段錯誤

查看 JavaScript 錯誤詳細資料

根據預設,系統無法提供網頁應用程式中 JavaScript 執行階段錯誤的詳細資料。如要查看 JavaScript 執行階段錯誤的詳細資料,請按照下列步驟操作:

  1. 請確認您已在網頁應用程式檔案中設定適當的跨源資源共享 (CORS) HTTP 回應標頭。詳情請參閱「跨來源資源共享」。
  2. HTML 檔案中,將 crossorigin="anonymous" 加入匯入的 <script> 標記,如以下程式碼片段所示:
<script crossorigin="anonymous" src="<SRC>"></script>

規範與限制

開發網頁應用程式時,請考量下列規範和限制:

  • 沒有 Cookie
  • 沒有本機儲存空間
  • 無地理位置
  • 未使用攝影機
  • 沒有錄音或錄影
  • 不顯示彈出式視窗
  • 不要超過 200 MB 的記憶體限制
  • 算繪內容時,將動作名稱標頭納入考量 (佔據畫面的上方部分)
  • 無法將任何樣式套用至影片
  • 一次只能使用一個媒體元素
  • 沒有網路 SQL 資料庫
  • 不支援 Web Speech APISpeechRecognition 介面。
  • 深色模式設定不適用
  • 智慧螢幕可播放影片。如要進一步瞭解支援的媒體容器格式和轉碼器,請參閱 Google Nest Hub 轉碼器

跨源資源共享

由於互動式 Canvas 網頁應用程式是在 iframe 中代管,且來源設為空值,因此您必須為網路伺服器和儲存空間資源啟用跨源資源共享 (CORS)。此程序可讓資產接受來自空值來源的要求。

後續步驟

如要為網頁應用程式新增更多功能,請參閱「使用用戶端或伺服器端執行要求繼續建構」。