Utilizza una risposta di selezione visiva se vuoi che l'utente selezioni una tra le diverse opzioni per continuare con l'Azione. In un messaggio puoi utilizzare i seguenti tipi di risposta di selezione visiva:
- Elenco
- Raccolta
- Sfoglia raccolte
Quando definisci una risposta di selezione visiva, utilizza un candidato con la funzionalità di visualizzazione RICH_RESPONSE in modo che l'Assistente Google restituisca la risposta solo sui dispositivi supportati. Puoi utilizzare una sola risposta avanzata per oggetto content in un prompt.
Aggiunta di una risposta di selezione visiva
Le risposte alla selezione visiva utilizzano la compilazione degli slot in una scena sia per presentare le opzioni che l'utente può selezionare sia per gestire un elemento selezionato. Quando gli utenti selezionano un elemento, l'assistente passa il valore dell'elemento selezionato al tuo webhook come argomento. Quindi, nel valore dell'argomento, ricevi la chiave per l'elemento selezionato.
Prima di poter utilizzare una risposta di selezione visiva, devi definire un tipo che rappresenti la risposta selezionata in seguito da un utente. Nel webhook, sostituisci questo tipo con i contenuti da visualizzare per la selezione.
Per aggiungere una risposta di selezione visiva a una scena in Actions Builder:
- Nella scena, aggiungi uno slot alla sezione Riempimento slot.
- Seleziona un tipo definito in precedenza per la risposta alla selezione visiva e assegnagli un nome. Il webhook utilizza questo nome di area per fare riferimento al tipo in un secondo momento.
- Seleziona la casella Chiama il tuo webhook e fornisci il nome del gestore di eventi nel webhook che vuoi utilizzare per la risposta di selezione visiva.
- Seleziona la casella Invia richieste.
- Nel prompt, fornisci i contenuti JSON o YAML appropriati in base alla risposta di selezione visiva che vuoi restituire.
- Nel webhook, segui i passaggi descritti in Gestire gli elementi selezionati.
Consulta le sezioni relative a elenco, raccolta ed esplorazione delle raccolte riportate di seguito per conoscere le proprietà dei prompt disponibili ed esempi di override dei tipi.
Gestione degli elementi selezionati
Le risposte alla selezione visiva richiedono che tu gestisca la selezione di un utente nel codice del webhook. Quando l'utente seleziona qualcosa da una risposta di selezione visiva, l'Assistente Google riempie l'area annuncio con quel valore.
Nell'esempio seguente, il codice webhook riceve e archivia l'opzione selezionata in una variabile:
Node.js
app.handle('Option', conv => {
// Note: 'prompt_option' is the name of the slot.
const selectedOption = conv.session.params.prompt_option;
conv.add(`You selected ${selectedOption}.`);
});
JSON
{
"responseJson": {
"session": {
"id": "session_id",
"params": {
"prompt_option": "ITEM_1"
}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "You selected ITEM_1.",
"text": "You selected ITEM_1."
}
}
}
}
Elenco
Un elenco presenta agli utenti un elenco verticale di più elementi e consente loro di selezionarne uno tramite tocco o input vocale. Quando un utente seleziona un elemento dall'elenco, l'assistente genera una query dell'utente (bolla della chat) contenente il titolo dell'elemento dell'elenco.
Gli elenchi sono utili quando è importante chiarire le opzioni o quando l'utente deve scegliere tra le opzioni che devono essere scansionate nella loro interezza. Ad esempio, con quale "Peter" hai bisogno di parlare, Peter Jons o Peter Hans?
Gli elenchi devono contenere da un minimo di 2 a un massimo di 30 voci. Il numero di elementi visualizzati inizialmente dipende dal dispositivo dell'utente e il numero iniziale comune è 10.
Creazione di un elenco
Quando crei un elenco, il prompt contiene solo le chiavi per ogni elemento che un utente
può selezionare. Nel webhook, definisci gli elementi che corrispondono a queste chiavi in base al tipo Entry.
Gli elementi di elenco definiti come oggetti Entry hanno le seguenti caratteristiche
di visualizzazione:
- Titolo
- Carattere e dimensione del carattere corretti
- Lunghezza massima: 1 riga (troncata con le ellissi...)
- Deve essere univoco (per supportare la selezione vocale)
- Descrizione (facoltativa)
- Carattere e dimensione del carattere corretti
- Lunghezza massima: 2 righe (troncamento con ellissi...)
- Immagine (facoltativa)
- Dimensioni: 48 x 48 px
Le risposte alla selezione visiva richiedono di eseguire l'override di un tipo in base al nome dello slot utilizzando un tipo di runtime in modalità TYPE_REPLACE. Nel gestore di eventi webhook, fai riferimento al tipo da sostituire con il nome dell'area (definito in Aggiunta di risposte di selezione) nella proprietà name.
Dopo che un tipo viene sovrascritto, il tipo risultante rappresenta l'elenco di elementi che l'utente può scegliere tra quelli visualizzati dall'assistente.
Proprietà
Il tipo di risposta all'elenco ha le seguenti proprietà:
| Proprietà | Tipo | Requisito | Descrizione |
|---|---|---|---|
items |
array di ListItem |
Obbligatorie | Rappresenta un elemento dell'elenco che gli utenti possono selezionare. Ogni ListItem contiene una chiave mappata a un tipo di riferimento per l'elemento dell'elenco. |
title |
stringa | Facoltativo | Titolo dell'elenco in testo normale, limitato a una sola riga. Se non viene specificato alcun titolo, l'altezza della scheda si comprime. |
subtitle |
stringa | Facoltativo | Sottotitolo dell'elenco in testo normale. |
Codice campione
I seguenti esempi definiscono il contenuto dei prompt nel codice webhook o nella webhookResponse JSON. Tuttavia, puoi definire i contenuti del prompt anche in Actions Builder (come YAML o JSON).
Node.js
const ASSISTANT_LOGO_IMAGE = new Image({
url: 'https://developers.google.com/assistant/assistant_96.png',
alt: 'Google Assistant logo'
});
app.handle('List', conv => {
conv.add('This is a list.');
// Override type based on slot 'prompt_option'
conv.session.typeOverrides = [{
name: 'prompt_option',
mode: 'TYPE_REPLACE',
synonym: {
entries: [
{
name: 'ITEM_1',
synonyms: ['Item 1', 'First item'],
display: {
title: 'Item #1',
description: 'Description of Item #1',
image: ASSISTANT_LOGO_IMAGE,
}
},
{
name: 'ITEM_2',
synonyms: ['Item 2', 'Second item'],
display: {
title: 'Item #2',
description: 'Description of Item #2',
image: ASSISTANT_LOGO_IMAGE,
}
},
{
name: 'ITEM_3',
synonyms: ['Item 3', 'Third item'],
display: {
title: 'Item #3',
description: 'Description of Item #3',
image: ASSISTANT_LOGO_IMAGE,
}
},
{
name: 'ITEM_4',
synonyms: ['Item 4', 'Fourth item'],
display: {
title: 'Item #4',
description: 'Description of Item #4',
image: ASSISTANT_LOGO_IMAGE,
}
},
]
}
}];
// Define prompt content using keys
conv.add(new List({
title: 'List title',
subtitle: 'List subtitle',
items: [
{
key: 'ITEM_1'
},
{
key: 'ITEM_2'
},
{
key: 'ITEM_3'
},
{
key: 'ITEM_4'
}
],
}));
});
JSON
{
"responseJson": {
"session": {
"id": "session_id",
"params": {},
"typeOverrides": [
{
"name": "prompt_option",
"synonym": {
"entries": [
{
"name": "ITEM_1",
"synonyms": [
"Item 1",
"First item"
],
"display": {
"title": "Item #1",
"description": "Description of Item #1",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
},
{
"name": "ITEM_2",
"synonyms": [
"Item 2",
"Second item"
],
"display": {
"title": "Item #2",
"description": "Description of Item #2",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
},
{
"name": "ITEM_3",
"synonyms": [
"Item 3",
"Third item"
],
"display": {
"title": "Item #3",
"description": "Description of Item #3",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
},
{
"name": "ITEM_4",
"synonyms": [
"Item 4",
"Fourth item"
],
"display": {
"title": "Item #4",
"description": "Description of Item #4",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
}
]
},
"typeOverrideMode": "TYPE_REPLACE"
}
]
},
"prompt": {
"override": false,
"content": {
"list": {
"items": [
{
"key": "ITEM_1"
},
{
"key": "ITEM_2"
},
{
"key": "ITEM_3"
},
{
"key": "ITEM_4"
}
],
"subtitle": "List subtitle",
"title": "List title"
}
},
"firstSimple": {
"speech": "This is a list.",
"text": "This is a list."
}
}
}
}
Raccolta
Una raccolta scorre in orizzontale e consente agli utenti di selezionare un elemento tramite tocco o input vocale. Rispetto agli elenchi, le raccolte hanno riquadri di grandi dimensioni e consentono contenuti più completi. I riquadri che compongono una raccolta sono simili alle schede di base con immagini. Quando gli utenti selezionano un elemento da una raccolta, l'assistente genera una query utente (bolla della chat) contenente il titolo dell'elemento.
Le raccolte sono valide quando all'utente vengono presentate varie opzioni, ma non è necessario un confronto diretto tra loro (rispetto agli elenchi). In generale, preferisci gli elenchi alle raccolte, perché gli elenchi sono più facili da esaminare visivamente e da interagire con la voce.
Le raccolte devono contenere da un minimo di 2 a un massimo di 10 riquadri. Sui dispositivi compatibili con i display, gli utenti possono scorrere verso sinistra o destra per scorrere le schede di una raccolta prima di selezionare un elemento.
Creare una raccolta
Quando crei una raccolta, il prompt contiene solo le chiavi per ogni elemento che
un utente può selezionare. Nel webhook, definisci gli elementi che corrispondono a queste chiavi in base al tipo Entry.
Gli elementi della raccolta definiti come oggetti Entry hanno le seguenti caratteristiche
di visualizzazione:
- Immagine (facoltativa)
- Altezza dell'immagine: 128 dp x larghezza 232 dp
- Se le proporzioni non corrispondono a quelle del riquadro di delimitazione, l'immagine viene centrata con barre ai lati
- Se un link immagine non funziona, viene utilizzata un'immagine segnaposto.
- Titolo (obbligatorio)
- Testo normale, Markdown non è supportato. Le stesse opzioni di formattazione della risposta multimediale di base alla scheda
- L'altezza della scheda si comprime se non viene specificato alcun titolo.
- Deve essere univoco (per supportare la selezione vocale)
- Descrizione (facoltativa)
- Testo normale, Markdown non è supportato. Le stesse opzioni di formattazione della risposta multimediale di base alla scheda
Le risposte alla selezione visiva richiedono di eseguire l'override di un tipo in base al nome dello slot utilizzando un tipo di runtime in modalità TYPE_REPLACE. Nel gestore di eventi webhook, fai riferimento al tipo da sostituire con il nome dell'area (definito in Aggiunta di risposte di selezione) nella proprietà name.
Dopo che un tipo viene sovrascritto, il tipo risultante rappresenta la raccolta di elementi che l'utente può scegliere tra quelli mostrati dall'assistente.
Proprietà
Il tipo di risposta della raccolta ha le seguenti proprietà:
| Proprietà | Tipo | Requisito | Descrizione |
|---|---|---|---|
items |
array di CollectionItem |
Obbligatorie | Rappresenta un elemento della raccolta che gli utenti possono selezionare. Ogni elemento CollectionItem contiene una chiave mappata a un tipo di riferimento per l'elemento della raccolta. |
title |
stringa | Facoltativo | Titolo in testo normale della raccolta. Per supportare la selezione vocale, i titoli devono essere univoci in una raccolta. |
subtitle |
stringa | Facoltativo | Sottotitolo in testo normale della raccolta. |
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. |
Codice campione
Gli esempi riportati di seguito definiscono i contenuti dei prompt nel codice o nella risposta del webhook JSON. Tuttavia, puoi definire i contenuti del prompt anche in Actions Builder (come YAML o JSON).
Node.js
const ASSISTANT_LOGO_IMAGE = new Image({
url: 'https://developers.google.com/assistant/assistant_96.png',
alt: 'Google Assistant logo'
});
app.handle('Collection', conv => {
conv.add("This is a collection.");
// Override type based on slot 'prompt_option'
conv.session.typeOverrides = [{
name: 'prompt_option',
mode: 'TYPE_REPLACE',
synonym: {
entries: [
{
name: 'ITEM_1',
synonyms: ['Item 1', 'First item'],
display: {
title: 'Item #1',
description: 'Description of Item #1',
image: ASSISTANT_LOGO_IMAGE,
}
},
{
name: 'ITEM_2',
synonyms: ['Item 2', 'Second item'],
display: {
title: 'Item #2',
description: 'Description of Item #2',
image: ASSISTANT_LOGO_IMAGE,
}
},
{
name: 'ITEM_3',
synonyms: ['Item 3', 'Third item'],
display: {
title: 'Item #3',
description: 'Description of Item #3',
image: ASSISTANT_LOGO_IMAGE,
}
},
{
name: 'ITEM_4',
synonyms: ['Item 4', 'Fourth item'],
display: {
title: 'Item #4',
description: 'Description of Item #4',
image: ASSISTANT_LOGO_IMAGE,
}
},
]
}
}];
// Define prompt content using keys
conv.add(new Collection({
title: 'Collection Title',
subtitle: 'Collection subtitle',
items: [
{
key: 'ITEM_1'
},
{
key: 'ITEM_2'
},
{
key: 'ITEM_3'
},
{
key: 'ITEM_4'
}
],
}));
});
JSON
{
"responseJson": {
"session": {
"id": "ABwppHHz--uQEEy3CCOANyB0J58oF2Yw5JEX0oXwit3uxDlRwzbEIK3Bcz7hXteE6hWovrLX9Ahpqu8t-jYnQRFGpAUqSuYjZ70",
"params": {},
"typeOverrides": [
{
"name": "prompt_option",
"synonym": {
"entries": [
{
"name": "ITEM_1",
"synonyms": [
"Item 1",
"First item"
],
"display": {
"title": "Item #1",
"description": "Description of Item #1",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
},
{
"name": "ITEM_2",
"synonyms": [
"Item 2",
"Second item"
],
"display": {
"title": "Item #2",
"description": "Description of Item #2",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
},
{
"name": "ITEM_3",
"synonyms": [
"Item 3",
"Third item"
],
"display": {
"title": "Item #3",
"description": "Description of Item #3",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
},
{
"name": "ITEM_4",
"synonyms": [
"Item 4",
"Fourth item"
],
"display": {
"title": "Item #4",
"description": "Description of Item #4",
"image": {
"alt": "Google Assistant logo",
"height": 0,
"url": "https://developers.google.com/assistant/assistant_96.png",
"width": 0
}
}
}
]
},
"typeOverrideMode": "TYPE_REPLACE"
}
]
},
"prompt": {
"override": false,
"content": {
"collection": {
"imageFill": "UNSPECIFIED",
"items": [
{
"key": "ITEM_1"
},
{
"key": "ITEM_2"
},
{
"key": "ITEM_3"
},
{
"key": "ITEM_4"
}
],
"subtitle": "Collection subtitle",
"title": "Collection Title"
}
},
"firstSimple": {
"speech": "This is a collection.",
"text": "This is a collection."
}
}
}
}
Sfoglia raccolte
Analogamente a una raccolta, la consultazione delle raccolte è una risposta avanzata che consente agli utenti di scorrere le schede delle opzioni. La consultazione della raccolta è progettata appositamente per i contenuti web e apre il riquadro selezionato in un browser web (o in un browser AMP se tutti i riquadri sono abilitati per AMP).
Le risposte alla consultazione della raccolta contengono un minimo di 2 e un massimo di 10 riquadri. Sui dispositivi compatibili con i display, gli utenti possono scorrere verso l'alto o verso il basso per visualizzare le schede prima di selezionare un elemento.
Creazione di una navigazione tra raccolte
Quando crei una consultazione delle raccolte, valuta il modo in cui gli utenti interagiranno con la richiesta. Ogni pagina di consultazione delle raccolte item apre l'URL definito, quindi fornisci dettagli utili all'utente.
Gli elementi di consultazione della raccolta hanno le seguenti caratteristiche di visualizzazione:
- Immagine (facoltativa)
- L'immagine deve essere forzata a 128 dp di altezza x 232 dp di larghezza.
- Se le proporzioni non corrispondono a quelle del riquadro di delimitazione, l'immagine è centrata con barre ai lati o in alto e in basso. Il colore delle
barra è determinato dalla proprietà di consultazione delle raccolte
ImageFill. - Se un link immagine non funziona, al suo posto viene utilizzata un'immagine segnaposto.
- Titolo (obbligatorio)
- Testo normale, Markdown non è supportato. Viene utilizzata la stessa formattazione della risposta avanzata della scheda di base.
- L'altezza della scheda si comprime se non viene definito alcun titolo.
- Descrizione (facoltativa)
- Testo normale, Markdown non è supportato. Viene utilizzata la stessa formattazione della risposta avanzata della scheda di base.
- Piè di pagina (facoltativo)
- Testo normale; Markdown non è supportato.
Proprietà
Il tipo di risposta alla consultazione delle raccolte ha le seguenti proprietà:
| Proprietà | Tipo | Requisito | Descrizione |
|---|---|---|---|
item |
oggetto | Obbligatorie | Rappresenta un elemento della raccolta che gli utenti possono selezionare. |
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. |
La consultazione della raccolta item ha le seguenti proprietà:
| Proprietà | Tipo | Requisito | Descrizione |
|---|---|---|---|
title |
stringa | Obbligatorie | Titolo in testo normale dell'elemento della raccolta. |
description |
stringa | Facoltativo | Descrizione dell'elemento della raccolta. |
footer |
stringa | Facoltativo | Testo a piè di pagina per l'elemento della raccolta, visualizzato sotto la descrizione. |
image |
Image |
Facoltativo | Immagine visualizzata per l'elemento della raccolta. |
openUriAction |
OpenUrl |
Obbligatorie | URI da aprire quando è selezionato l'elemento della raccolta. |
Codice campione
Gli esempi riportati di seguito definiscono i contenuti dei prompt nel codice o nella risposta del webhook JSON. Tuttavia, puoi definire i contenuti del prompt anche in Actions Builder (come YAML o JSON).
YAML
candidates:
- first_simple:
variants:
- speech: This is a collection browse.
content:
collection_browse:
items:
- title: Item #1
description: Description of Item #1
footer: Footer of Item #1
image:
url: 'https://developers.google.com/assistant/assistant_96.png'
open_uri_action:
url: 'https://www.example.com'
- title: Item #2
description: Description of Item #2
footer: Footer of Item #2
image:
url: 'https://developers.google.com/assistant/assistant_96.png'
open_uri_action:
url: 'https://www.example.com'
image_fill: WHITE
JSON
{
"candidates": [
{
"firstSimple": {
"speech": "This is a collection browse.",
"text": "This is a collection browse."
},
"content": {
"collectionBrowse": {
"items": [
{
"title": "Item #1",
"description": "Description of Item #1",
"footer": "Footer of Item #1",
"image": {
"url": "https://developers.google.com/assistant/assistant_96.png"
},
"openUriAction": {
"url": "https://www.example.com"
}
},
{
"title": "Item #2",
"description": "Description of Item #2",
"footer": "Footer of Item #2",
"image": {
"url": "https://developers.google.com/assistant/assistant_96.png"
},
"openUriAction": {
"url": "https://www.example.com"
}
}
],
"imageFill": "WHITE"
}
}
}
]
}
Node.js
// Collection Browse
app.handle('collectionBrowse', (conv) => {
conv.add('This is a collection browse.');
conv.add(new CollectionBrowse({
'imageFill': 'WHITE',
'items':
[
{
'title': 'Item #1',
'description': 'Description of Item #1',
'footer': 'Footer of Item #1',
'image': {
'url': 'https://developers.google.com/assistant/assistant_96.png'
},
'openUriAction': {
'url': 'https://www.example.com'
}
},
{
'title': 'Item #2',
'description': 'Description of Item #2',
'footer': 'Footer of Item #2',
'image': {
'url': 'https://developers.google.com/assistant/assistant_96.png'
},
'openUriAction': {
'url': 'https://www.example.com'
}
}
]
}));
});
JSON
{
"responseJson": {
"session": {
"id": "session_id",
"params": {},
"languageCode": ""
},
"prompt": {
"override": false,
"content": {
"collectionBrowse": {
"imageFill": "WHITE",
"items": [
{
"title": "Item #1",
"description": "Description of Item #1",
"footer": "Footer of Item #1",
"image": {
"url": "https://developers.google.com/assistant/assistant_96.png"
},
"openUriAction": {
"url": "https://www.example.com"
}
},
{
"title": "Item #2",
"description": "Description of Item #2",
"footer": "Footer of Item #2",
"image": {
"url": "https://developers.google.com/assistant/assistant_96.png"
},
"openUriAction": {
"url": "https://www.example.com"
}
}
]
}
},
"firstSimple": {
"speech": "This is a collection browse.",
"text": "This is a collection browse."
}
}
}
}