Risposte avanzate

Le risposte avanzate aggiungono elementi visivi per migliorare le interazioni degli utenti con la tua azione. In una richiesta puoi utilizzare i seguenti tipi di risposta avanzata:

  • Carta di base
  • Scheda immagine
  • Scheda tabella

Quando definisci una risposta avanzata, utilizza un candidato con la funzionalità della piattaforma RICH_RESPONSE in modo che l'Assistente Google restituisca solo la risposta avanzata sui dispositivi supportati. Puoi utilizzare una sola risposta avanzata per oggetto content in una richiesta.

Carta di base

Le schede di base sono concepite per essere concise, per presentare informazioni chiave (o di riepilogo) agli utenti e per consentire a questi ultimi di saperne di più (utilizzando un link web).

Utilizza le schede di base principalmente a scopo di visualizzazione, in quanto non hanno funzionalità di interazione senza un pulsante. Per collegare un pulsante al web, una piattaforma deve avere anche la funzionalità WEB_LINK.

Esempio di una carta di base su uno smart display

Proprietà

Il tipo di risposta della scheda di base ha le seguenti proprietà:

Proprietà Tipo Requisito Descrizione
title stringa Facoltativo Titolo della scheda in testo normale. I titoli hanno un carattere e una dimensione fissi e i caratteri che superano la prima riga vengono troncati. L'altezza della scheda si comprime se non viene specificato alcun titolo.
subtitle stringa Facoltativo Sottotitolo in testo normale della scheda. I titoli hanno un carattere e una dimensione fissi e i caratteri oltre la prima riga vengono troncati. L'altezza della scheda si comprime se non viene specificato alcun sottotitolo.
text stringa Condizionali

Contenuti di testo normale della scheda. Il testo troppo lungo viene troncato in corrispondenza dell'ultima interruzione di parola con i puntini di sospensione. Questa proprietà è obbligatoria, a meno che non sia presente image.

Questa proprietà ha le seguenti limitazioni:

  • Massimo 15 righe senza immagine o 10 con image. Questo valore corrisponde a circa 750 (senza immagine) o 500 (con immagine) caratteri. Tieni presente che i dispositivi mobili troncano il testo prima rispetto alle piattaforme con schermi più grandi.
  • Il testo non deve contenere un link.

È supportato un sottoinsieme limitato di Markdown:

  • Nuova riga con doppio spazio seguito da \n
  • **bold**
  • *italics*
image Image Facoltativo Immagine visualizzata nella scheda. Le immagini possono essere JPG, PNG e GIF (animate e non animate).
image_fill ImageFill Facoltativo Bordo tra la scheda e il contenitore dell'immagine da utilizzare quando le proporzioni dell'immagine non corrispondono a quelle del contenitore dell'immagine.
button Link Facoltativo Pulsante che, quando toccato, collega l'utente a un URL. Il pulsante deve avere una proprietà name contenente il testo del pulsante e una proprietà url che contiene l'URL del link. Il testo del pulsante non può essere fuorviante e viene controllato durante la procedura di revisione.

Codice campione

YAML

candidates:
  - first_simple:
      variants:
        - speech: This is a card.
          text: This is a card.
    content:
      card:
        title: Card Title
        subtitle: Card Subtitle
        text: Card Content
        image:
          url: 'https://developers.google.com/assistant/assistant_96.png'
          alt: Google Assistant logo

JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "This is a card.",
            "text": "This is a card."
          }
        ]
      },
      "content": {
        "card": {
          "title": "Card Title",
          "subtitle": "Card Subtitle",
          "text": "Card Content",
          "image": {
            "url": "https://developers.google.com/assistant/assistant_96.png",
            "alt": "Google Assistant logo"
          }
        }
      }
    }
  ]
}

Node.js

app.handle('Card', conv => {
  conv.add('This is a card.');
  conv.add(new Card({
    "title": "Card Title",
    "subtitle": "Card Subtitle",
    "text": "Card Content",
    "image": new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

JSON

{
  "responseJson": {
    "session": {
      "id": "session_id",
      "params": {}
    },
    "prompt": {
      "override": false,
      "content": {
        "card": {
          "title": "Card Title",
          "subtitle": "Card Subtitle",
          "text": "Card Content",
          "image": {
            "alt": "Google Assistant logo",
            "height": 0,
            "url": "https://developers.google.com/assistant/assistant_96.png",
            "width": 0
          }
        }
      },
      "firstSimple": {
        "speech": "This is a card.",
        "text": "This is a card."
      }
    }
  }
}

Schede con immagini

Le schede con immagini sono progettate per essere un'alternativa più semplice alle schede di base che contengono anche un'immagine. Utilizza una scheda immagine quando vuoi presentare un'immagine e non hai bisogno di supportare testi o componenti interattivi.

Proprietà

Il tipo di risposta della scheda immagine ha le seguenti proprietà:

Proprietà Tipo Requisito Descrizione
url stringa Obbligatorie URL di origine dell'immagine. Le immagini possono essere JPG, PNG o GIF (animate e non animate).
alt stringa Obbligatorie Descrizione testuale dell'immagine da utilizzare per l'accessibilità.
height int32 Facoltativo Altezza dell'immagine in pixel.
width int32 Facoltativo Larghezza dell'immagine in pixel.

Codice campione

YAML

candidates:
  - first_simple:
      variants:
        - speech: This is an image prompt.
          text: This is an image prompt.
    content:
      image:
        alt: Google Assistant logo
        url: 'https://developers.google.com/assistant/assistant_96.png'

JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "This is an image prompt.",
            "text": "This is an image prompt."
          }
        ]
      },
      "content": {
        "image": {
          "alt": "Google Assistant logo",
          "url": "https://developers.google.com/assistant/assistant_96.png"
        }
      }
    }
  ]
}

Node.js

app.handle('Image', conv => {
  conv.add("This is an image prompt!");
  conv.add(new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
  }));
});

JSON

{
  "responseJson": {
    "session": {
      "id": "session_id",
      "params": {}
    },
    "prompt": {
      "override": false,
      "content": {
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      },
      "firstSimple": {
        "speech": "This is an image prompt.",
        "text": "This is an image prompt."
      }
    }
  }
}

Schede tabella

Le schede tabella ti consentono di visualizzare dati tabulari nella risposta (ad esempio, classifiche sportive, risultati elettorali e voli). Puoi definire colonne e righe (fino a tre ciascuna) che l'assistente mostrerà nella scheda della tabella. Puoi anche definire colonne e righe aggiuntive, insieme alla loro priorità.

Esempio di scheda tabella su smart display

Le tabelle visualizzano dati statici e non è possibile interagire. Per le risposte di selezione interattive, utilizza invece una risposta di selezione visiva.

Proprietà

Il tipo di risposta della scheda della tabella ha le seguenti proprietà:

Proprietà Tipo Requisito Descrizione
title stringa Condizionali Titolo della tabella in testo normale. Questa proprietà è obbligatoria se è impostato subtitle.
subtitle stringa Facoltativo Sottotitolo in testo normale della tabella. I sottotitoli nelle schede della tabella non sono interessati dalla personalizzazione del tema.
columns array di TableColumn Obbligatorie Intestazioni e allineamento delle colonne. Ogni oggetto TableColumn descrive l'intestazione e l'allineamento di una colonna diversa nella stessa tabella.
rows array di TableRow Obbligatorie

Dati delle righe della tabella. È garantito che le prime 3 righe vengano mostrate, ma altre potrebbero non essere visualizzate su alcune piattaforme. Puoi eseguire test con il simulatore per vedere quali righe vengono mostrate per una determinata superficie.

Ogni oggetto TableRow descrive le celle di una riga diversa nella stessa tabella.

image Image Facoltativo Immagine associata alla tabella.
button Link Facoltativo Pulsante che, quando toccato, collega l'utente a un URL. Il pulsante deve avere una proprietà name contenente il testo del pulsante e una proprietà url che contiene l'URL del link. Il testo del pulsante non può essere fuorviante e viene controllato durante la procedura di revisione.

Codice campione

I seguenti snippet mostrano come implementare una scheda della tabella:

YAML

candidates:
  - first_simple:
      variants:
        - speech: This is a table.
          text: This is a table.
    content:
      table:
        title: Table Title
        subtitle: Table Subtitle
        columns:
          - header: Column A
          - header: Column B
          - header: Column C
        rows:
          - cells:
              - text: A1
              - text: B1
              - text: C1
          - cells:
              - text: A2
              - text: B2
              - text: C2
          - cells:
              - text: A3
              - text: B3
              - text: C3
        image:
          alt: Google Assistant logo
          url: 'https://developers.google.com/assistant/assistant_96.png'

JSON

{
  "candidates": [
    {
      "first_simple": {
        "variants": [
          {
            "speech": "This is a table.",
            "text": "This is a table."
          }
        ]
      },
      "content": {
        "table": {
          "title": "Table Title",
          "subtitle": "Table Subtitle",
          "columns": [
            {
              "header": "Column A"
            },
            {
              "header": "Column B"
            },
            {
              "header": "Column C"
            }
          ],
          "rows": [
            {
              "cells": [
                {
                  "text": "A1"
                },
                {
                  "text": "B1"
                },
                {
                  "text": "C1"
                }
              ]
            },
            {
              "cells": [
                {
                  "text": "A2"
                },
                {
                  "text": "B2"
                },
                {
                  "text": "C2"
                }
              ]
            },
            {
              "cells": [
                {
                  "text": "A3"
                },
                {
                  "text": "B3"
                },
                {
                  "text": "C3"
                }
              ]
            }
          ],
          "image": {
            "alt": "Google Assistant logo",
            "url": "https://developers.google.com/assistant/assistant_96.png"
          }
        }
      }
    }
  ]
}

Node.js

app.handle('Table', conv => {
  conv.add('This is a table.');
  conv.add(new Table({
    "title": "Table Title",
    "subtitle": "Table Subtitle",
    "image": new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    }),
    "columns": [{
      "header": "Column A"
    }, {
      "header": "Column B"
    }, {
      "header": "Column C"
    }],
    "rows": [{
      "cells": [{
        "text": "A1"
      }, {
        "text": "B1"
      }, {
        "text": "C1"
      }]
    }, {
      "cells": [{
        "text": "A2"
      }, {
        "text": "B2"
      }, {
        "text": "C2"
      }]
    }, {
      "cells": [{
        "text": "A3"
      }, {
        "text": "B3"
      }, {
        "text": "C3"
      }]
    }]
  }));
});

JSON

{
  "responseJson": {
    "session": {
      "id": "session_id",
      "params": {}
    },
    "prompt": {
      "override": false,
      "content": {
        "table": {
          "button": {},
          "columns": [
            {
              "header": "Column A"
            },
            {
              "header": "Column B"
            },
            {
              "header": "Column C"
            }
          ],
          "image": {
            "alt": "Google Assistant logo",
            "height": 0,
            "url": "https://developers.google.com/assistant/assistant_96.png",
            "width": 0
          },
          "rows": [
            {
              "cells": [
                {
                  "text": "A1"
                },
                {
                  "text": "B1"
                },
                {
                  "text": "C1"
                }
              ]
            },
            {
              "cells": [
                {
                  "text": "A2"
                },
                {
                  "text": "B2"
                },
                {
                  "text": "C2"
                }
              ]
            },
            {
              "cells": [
                {
                  "text": "A3"
                },
                {
                  "text": "B3"
                },
                {
                  "text": "C3"
                }
              ]
            }
          ],
          "subtitle": "Table Subtitle",
          "title": "Table Title"
        }
      },
      "firstSimple": {
        "speech": "This is a table.",
        "text": "This is a table."
      }
    }
  }
}

Personalizzazione delle risposte

Puoi modificare l'aspetto delle risposte avanzate creando un tema personalizzato per il tuo progetto Actions. Questa personalizzazione può essere utile per definire un aspetto univoco della conversazione quando gli utenti richiamano le tue azioni su una piattaforma dotata di una schermata.

Per impostare un tema di risposta personalizzato:

  1. Nella console di Actions, vai a Sviluppo > Personalizzazione del tema.
  2. Imposta una o tutte le seguenti opzioni:
    • Colore sfondo: il colore utilizzato come sfondo delle schede. In generale, utilizza un colore chiaro per lo sfondo per facilitare la lettura dei contenuti della scheda.
    • Colore principale: colore principale per i testi delle intestazioni e gli elementi dell'interfaccia delle schede. In generale, utilizza un colore principale più scuro per migliorare il contrasto con il colore di sfondo.
    • Famiglia di caratteri: descrive il tipo di carattere utilizzato per i titoli e altri elementi di testo in evidenza.
    • Stile degli angoli dell'immagine: modifica l'aspetto degli angoli delle schede.
    • Immagine di sfondo: immagine personalizzata da utilizzare al posto del colore di sfondo. Fornisci due immagini diverse per quando la superficie del dispositivo è in modalità Orizzontale o Ritratto. Se usi un'immagine di sfondo, il colore principale è impostato su bianco.
  3. Fai clic su Salva.
Personalizzazione del tema nella console di Actions