Configurar seu app da Web

Um app da Web é a interface do usuário (IU) de uma ação que usa a tela interativa. É possível usar tecnologias da Web existentes, como HTML, CSS, JavaScript e WebAssembly, para projetar e desenvolver seu app da Web. Na maioria das vezes, a tela interativa pode renderizar conteúdo da Web como um navegador, mas há algumas restrições aplicadas para privacidade e segurança do usuário. Antes de começar a projetar sua interface, considere os princípios de design descritos nas Diretrizes de design. Recomendamos o uso do Firebase Hosting para implantar seu app da Web.

O HTML e o JavaScript do seu app da Web fazem o seguinte:

Esta página aborda as maneiras recomendadas de criar seu app da Web, como ativar a comunicação entre a ação de conversa e o app da Web, além de diretrizes e restrições gerais.

Embora você possa usar qualquer método para criar a interface, o Google recomenda o uso das seguintes bibliotecas:

Arquitetura

O Google recomenda o uso de uma arquitetura de aplicativo de página única. Essa abordagem possibilita a performance ideal e oferece suporte à experiência do usuário de conversa contínua. A tela interativa pode ser usada com frameworks de front-end, como Vue, Angular e React, que ajudam no gerenciamento do estado.

Arquivo HTML

O arquivo HTML define a aparência da interface. Esse arquivo também carrega a API Interactive Canvas, que permite a comunicação entre seu app da Web e a ação de conversa.

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>
    

Fazer a comunicação entre a ação de conversa e o app da Web

Depois de criar seu app da Web e a ação de conversa e carregar na biblioteca de tela interativa no arquivo do app da Web, você precisa definir como o app da Web e a ação de conversa interagem. Para isso, modifique os arquivos que contêm a lógica do app da Web.

action.js

Esse arquivo contém o código para definir callbacks e invocar métodos usando interactiveCanvas. Os callbacks permitem que seu app da Web responda a informações ou solicitações da ação de conversa. Os métodos oferecem uma maneira de enviar informações ou solicitações para a ação de conversa.

Adicione interactiveCanvas.ready(callbacks); ao arquivo HTML para inicializar e registrar 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

O módulo JavaScript main.js importa os arquivos action.js e scene.js e cria instâncias de cada um deles quando o app da Web é carregado. Este módulo também registra callbacks para a tela interativa.

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

O arquivo scene.js constrói a cena para seu app da Web. Confira um trecho de 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;
});
    

Suporte a interações por toque

Sua ação de tela interativa pode responder ao toque do usuário e às entradas vocais. De acordo com as diretrizes de design da tela interativa, você precisa desenvolver a ação para priorizar a voz. Algumas telas inteligentes oferecem suporte a interações de toque.

O suporte a toque é semelhante ao suporte a respostas conversacionais. No entanto, em vez de uma resposta vocal do usuário, o JavaScript do lado do cliente procura interações de toque e as usa para mudar elementos no app da Web.

Veja um exemplo disso na amostra, que usa a biblioteca 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;
});
    

Solução de problemas

Embora você possa usar o simulador no Console do Actions para testar a ação de tela interativa durante o desenvolvimento, também é possível ver erros que ocorrem no app da Web de tela interativa nos dispositivos dos usuários em produção. Veja esses erros nos registros do Google Cloud Platform.

Para ver essas mensagens de erro nos registros do Google Cloud Platform, siga estas etapas:

  1. Abra seu projeto do Actions no Console do Actions.
  2. Clique em Testar na navegação da parte de cima.
  3. Clique no link Ver registros no Google Cloud Platform.

Os erros dos dispositivos dos usuários aparecem em ordem cronológica no visualizador de registros.

Tipos de erro

Há três tipos de erros de apps da Web que podem ser vistos nos registros do Google Cloud Platform:

  • Tempos limite que ocorrem quando ready não é chamado em 10 segundos
  • Tempos limite que ocorrem quando a promessa retornada por onUpdate() não é atendida em 10 segundos
  • Erros de tempo de execução JavaScript que não são detectados no seu app da Web

Mais detalhes do erro de JavaScript

Os detalhes dos erros de tempo de execução do JavaScript no app da Web não estão disponíveis por padrão. Para ver os detalhes dos erros de ambiente de execução do JavaScript, siga estas etapas:

  1. Verifique se você configurou os cabeçalhos de resposta HTTP de compartilhamento de recursos entre origens (CORS) adequados nos arquivos do app da Web. Para mais informações, consulte Compartilhamento de recursos entre origens.
  2. Adicione crossorigin="anonymous" às tags <script> importadas no arquivo HTML, conforme mostrado no snippet de código a seguir:
<script crossorigin="anonymous" src="<SRC>"></script>

Diretrizes e restrições

Considere as seguintes diretrizes e restrições ao desenvolver seu app da Web:

  • Sem cookies
  • Sem armazenamento local
  • Sem geolocalização
  • Sem uso da câmera
  • Sem gravação de áudio ou vídeo
  • Sem pop-ups
  • Permanecer abaixo do limite de 200 MB de memória
  • Considere o cabeçalho "Nome da ação" ao renderizar conteúdo (ocupa a parte superior da tela).
  • Não é possível aplicar estilos aos vídeos
  • Somente um elemento de mídia pode ser usado por vez
  • Nenhum banco de dados Web SQL
  • Não há suporte para a interface SpeechRecognition da API Web Speech.
  • A configuração de modo escuro não se aplica
  • É possível assistir vídeos em smart displays. Para mais informações sobre os formatos e codecs de mídia compatíveis, consulte Codecs do Google Nest Hub.

Compartilhamento de recursos entre origens

Como os apps da Web de tela interativa são hospedados em um iframe e a origem está definida como nula, ative o compartilhamento de recursos entre origens (CORS, na sigla em inglês) para os servidores da Web e recursos de armazenamento. Esse processo permite que seus recursos aceitem solicitações de origens nulas.

Próximas etapas

Para adicionar mais recursos ao app da Web, consulte Continuar criando com o fulfillment do lado do cliente ou do servidor.