Configura la tua app web

Un'app web è l'interfaccia utente (UI) di un'azione che utilizza Interactive Canvas. Puoi utilizzare tecnologie web esistenti (come HTML, CSS, JavaScript e WebAssembly) per progettare e sviluppare la tua app web. Nella maggior parte dei casi, Interactive Canvas è in grado di eseguire il rendering dei contenuti web come un browser, ma sono state applicate alcune limitazioni per la privacy e la sicurezza degli utenti. Prima di iniziare a progettare la tua UI, prendi in considerazione i principi di progettazione descritti nelle Linee guida per la progettazione. Ti consigliamo di utilizzare Firebase Hosting per implementare la tua app web.

I codici HTML e JavaScript della tua applicazione web:

Questa pagina illustra i modi consigliati per creare la tua app web, come attivare la comunicazione tra l'azione conversazionale e la tua app web, nonché linee guida e limitazioni generali.

Anche se puoi utilizzare qualsiasi metodo per creare la tua UI, Google consiglia di utilizzare le seguenti librerie:

Architettura

Google consiglia vivamente di utilizzare un'architettura dell'applicazione a pagina singola. Questo approccio consente prestazioni ottimali e supporta un'esperienza utente conversazionale continua. Interactive Canvas può essere utilizzato in combinazione con framework front-end come Vue, Angular e React, utili per la gestione degli stati.

File HTML

Il file HTML definisce l'aspetto dell'interfaccia utente. Questo file carica anche l'API Interactive Canvas, che consente la comunicazione tra la tua app web e l'azione conversazionale.

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>

Comunicazione tra azione conversazionale e app web

Dopo aver creato l'app web e l'azione conversazionale e averle caricate nella libreria Interactive Canvas nel file dell'app web, devi definire la modalità di interazione tra l'app web e l'azione conversazionale. Per farlo, modifica i file che contengono la logica della tua app web.

action.js

Questo file contiene il codice per definire i callbacks e richiamare i metodi tramite interactiveCanvas. I callback consentono alla tua app web di rispondere a informazioni o richieste da l'azione conversazionale, mentre i metodi forniscono un modo per inviare informazioni o richieste all'azione conversazionale.

Aggiungi interactiveCanvas.ready(callbacks); al file HTML per inizializzare e registrare i 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

Il modulo JavaScript main.js importa i file action.js e scene.js e crea istanze di ciascuno di essi al caricamento dell'app web. Questo modulo registra anche i callback per Interactive Canvas.

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

Il file scene.js crea la scena per l'app web. Di seguito è riportato un estratto di 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;
});

Supporta le interazioni touch

La tua azione interattiva Canvas può rispondere al tocco dell'utente e ai suoi input vocali. Secondo le linee guida per la progettazione di Canvas Interattive, devi sviluppare l'Azione in modo che sia orientata alla voce. Detto questo, alcuni smart display supportano le interazioni touch.

Il tocco di supporto è simile al supporto delle risposte conversazionali; tuttavia, invece di una risposta vocale da parte dell'utente, il tuo codice JavaScript lato client cerca le interazioni di tocco e le utilizza per cambiare elementi nell'app web.

Puoi vederne un esempio nell'esempio, che utilizza la libreria 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;
});

Risolvere i problemi

Sebbene sia possibile utilizzare il simulatore nella console Actions per testare l'Azione Interactive Canvas durante lo sviluppo, puoi anche visualizzare gli errori che si verificano all'interno dell'app web Interactive Canvas sui dispositivi degli utenti in fase di produzione. Puoi visualizzare questi errori nei log di Google Cloud Platform.

Per visualizzare questi messaggi di errore nei log di Google Cloud Platform, procedi nel seguente modo:

  1. Apri il progetto Actions nella console Actions.
  2. Fai clic su Test nella barra di navigazione in alto.
  3. Fai clic sul link Visualizza i log in Google Cloud.

Gli errori relativi ai dispositivi degli utenti vengono visualizzati in ordine cronologico nel visualizzatore dei log.

Tipi di errore

Nei log di Google Cloud Platform puoi vedere tre tipi di errori delle app web:

  • Timeout che si verificano quando ready non viene chiamato entro 10 secondi
  • Timeout che si verificano quando la promessa restituita da onUpdate() non viene soddisfatta entro 10 secondi
  • Errori di runtime di JavaScript che non vengono rilevati nella tua app web

Visualizza dettagli errore JavaScript

I dettagli degli errori di runtime JavaScript all'interno della tua app web non sono disponibili per impostazione predefinita. Per visualizzare i dettagli degli errori di runtime JavaScript, segui questi passaggi:

  1. Assicurati di aver configurato le intestazioni delle risposte HTTP CORS (Cross-Origin Resource Sharing) appropriate nei file dell'app web. Per ulteriori informazioni, consulta Condivisione delle risorse tra origini.
  2. Aggiungi crossorigin="anonymous" ai tag <script> importati nel file HTML, come mostrato nel seguente snippet di codice:
<script crossorigin="anonymous" src="<SRC>"></script>

Linee guida e limitazioni

Tieni presente le seguenti linee guida e limitazioni durante lo sviluppo della tua app web:

  • Nessun cookie
  • Nessuno spazio di archiviazione locale
  • Nessuna geolocalizzazione
  • Nessun utilizzo della fotocamera
  • Nessuna registrazione audio o video
  • Nessun popup
  • Rimanere al di sotto del limite di 200 MB
  • Prendi in considerazione l'intestazione Nome azione quando esegui il rendering dei contenuti (occupa la parte superiore dello schermo)
  • Nessuno stile può essere applicato ai video
  • È possibile utilizzare un solo elemento multimediale alla volta
  • Nessun database SQL web
  • Nessun supporto per l'interfaccia SpeechRecognition dell'API Web Speech.
  • Impostazione modalità Buio non applicabile
  • La riproduzione di video è supportata sugli smart display. Per ulteriori informazioni sui codec e formati di contenitori multimediali supportati, consulta la pagina Codec Google Nest Hub.

Condivisione delle risorse tra origini (CORS)

Poiché le app web Interactive Canvas sono ospitate in un iframe e l'origine è impostata su null, devi attivare la condivisione delle risorse multiorigine (CORS) per i server web e le risorse di archiviazione. Questo processo consente agli asset di accettare richieste da origini null.

Passaggi successivi

Per aggiungere altre funzionalità alla tua app web, vedi Continua a creare con il fulfillment lato client o lato server.