Use uma resposta de seleção visual se quiser que o usuário selecione uma entre várias opções para continuar com a ação. É possível usar os seguintes tipos de resposta de seleção visual como parte de um comando:
- Lista
- Coleção
- Navegação de coleções
Ao definir uma resposta de seleção visual, use um candidato com o
recurso de superfície RICH_RESPONSE
para que o Google Assistente retorne a
resposta apenas em dispositivos com suporte. Só é possível usar uma resposta avançada por objeto content
em uma solicitação.
Como adicionar uma resposta de seleção visual
As respostas de seleção visual usam o preenchimento de slots em uma cena para apresentar opções que um usuário pode selecionar e processar um item selecionado. Quando os usuários selecionam um item, o Google Assistente transmite o valor do item selecionado para o webhook como um argumento. Em seguida, no valor do argumento, você recebe a chave para o item selecionado.
Antes de usar uma resposta de seleção visual, é preciso definir um tipo que representa a resposta selecionada depois pelo usuário. No webhook, substitua esse tipo pelo conteúdo que você quer exibir para seleção.
Para adicionar uma resposta de seleção visual a uma cena no Actions Builder, siga estas etapas:
- Na cena, adicione um slot à seção Preenchimento de slot.
- Selecione um type definido anteriormente para a resposta de seleção visual e dê um nome a ela. O webhook usa esse nome de slot para fazer referência ao tipo mais tarde.
- Marque a caixa Call your webhook e forneça o nome do manipulador de eventos no webhook que você quer usar para a resposta de seleção visual.
- Marque a caixa Enviar solicitações.
- No comando, forneça o conteúdo JSON ou YAML apropriado com base na resposta de seleção visual que você quer retornar.
- No webhook, siga as etapas em Como processar itens selecionados.
Consulte as seções lista, coleção e navegação de coleções abaixo para conferir as propriedades de comandos disponíveis e exemplos de tipos de modificação.
Processar itens selecionados
As respostas de seleção visual exigem que você manipule a seleção de um usuário no código de webhook. Quando o usuário seleciona algo em uma resposta de seleção visual, o Google Assistente preenche o slot com esse valor.
No exemplo a seguir, o código do webhook recebe e armazena a opção selecionada em uma variável:
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." } } } }
Lista
![Exemplo de resposta de seleção de lista em um dispositivo móvel](https://developers-dot-devsite-v2-prod.appspot.com/static/assistant/conversational/images/list.png?authuser=7&hl=pt)
Uma lista apresenta aos usuários uma lista vertical com vários itens e permite que eles selecionem um por toque ou entrada de texto por voz. Quando um usuário seleciona um item da lista, o Google Assistente gera uma consulta (balão de chat) com o título do item da lista.
As listas são boas para quando é importante remover a ambiguidade das opções ou quando o usuário precisa escolher entre as opções que precisam ser verificadas na íntegra. Por exemplo, com qual "Peter" você precisa falar, Peter Jons ou Peter Hans?
As listas precisam conter no mínimo 2 e no máximo 30 itens. O número de elementos mostrados inicialmente depende do dispositivo do usuário, e o número inicial comum é 10 itens.
Como criar uma lista
Ao criar uma lista, sua solicitação contém apenas chaves para cada item que um usuário
pode selecionar. No webhook, defina os itens que correspondem a essas chaves
com base no tipo Entry
.
Os itens de lista definidos como objetos Entry
têm as seguintes características
de exibição:
- Título
- Fonte e tamanho da fonte corrigidos
- Comprimento máximo: uma linha (truncada com reticências...)
- Necessário para ser exclusivo (para oferecer suporte à seleção de voz)
- Descrição (opcional)
- Fonte e tamanho da fonte corrigidos
- Comprimento máximo: 2 linhas (truncadas com reticências...)
- Imagem (opcional)
- Tamanho: 48 x 48 px
As respostas de seleção visual exigem que você substitua um tipo pelo nome do slot usando
um tipo de ambiente de execução no modo TYPE_REPLACE
. No manipulador de eventos
do webhook, faça referência ao tipo a ser substituído pelo nome do slot, definido em
Como adicionar respostas de seleção na propriedade name
.
Depois que um tipo é substituído, o tipo resultante representa a lista de itens que o usuário pode escolher nessas telas do Google Assistente.
Propriedades
O tipo de resposta de lista tem as seguintes propriedades:
Propriedade | Tipo | Requisito | Descrição |
---|---|---|---|
items |
matriz de ListItem |
Obrigatório | Representa um item na lista que os usuários podem selecionar. Cada
ListItem contém uma chave que é mapeada para um tipo referenciado para
o item da lista. |
title |
string | Opcional | Título em texto simples da lista, restrito a uma única linha. Se nenhum título for especificado, a altura do card vai ser reduzida. |
subtitle |
string | Opcional | Subtítulo em texto simples da lista. |
Exemplo de código
Os exemplos a seguir definem o conteúdo da solicitação no código do webhook ou na JSON webhookResponse. No entanto, também é possível definir o conteúdo da solicitação no Actions Builder (como YAML ou 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." } } } }
Coleção
Uma coleção rola horizontalmente e permite que os usuários selecionem um item por toque ou entrada de texto por voz. Em comparação com listas, as coleções têm blocos grandes e permitem um conteúdo mais avançado. Os blocos que compõem uma coleção são semelhantes ao card básico com imagem. Quando os usuários selecionam um item de uma coleção, o Google Assistente gera uma consulta (balão de chat) com o título do item.
As coleções são boas quando várias opções são apresentadas ao usuário, mas não é necessária uma comparação direta entre elas (em comparação com listas). Em geral, dê preferência a listas em vez de coleções, porque elas são mais fáceis de verificar visualmente e de interagir por voz.
As coleções precisam conter de 2 a 10 blocos. Em dispositivos compatíveis com tela, os usuários podem deslizar para a esquerda ou direita para navegar pelos cards em uma coleção antes de selecionar um item.
![Exemplo de resposta de seleção de coleção em um smart display](https://developers-dot-devsite-v2-prod.appspot.com/static/assistant/conversational/images/smart-display/carousel.png?authuser=7&hl=pt)
Criar uma coleção
Ao criar uma coleção, o comando contém apenas chaves para cada item que um
usuário pode selecionar. No webhook, defina os itens que correspondem a essas
chaves com base no tipo Entry
.
Os itens de coleção definidos como objetos Entry
têm as seguintes características
de exibição:
- Imagem (opcional)
- A imagem é forçada a ter 128 dp de altura x 232 dp de largura
- Se a proporção da imagem não corresponder à caixa delimitadora da imagem, ela será centralizada com barras em ambos os lados
- Se um link de imagem for corrompido, uma imagem de marcador será usada.
- Título (obrigatório)
- Texto simples. Markdown não é compatível. Mesmas opções de formatação que a resposta avançada em ficha de informações básica
- A altura do card vai ser fechada se nenhum título for especificado.
- Necessário para ser exclusivo (para oferecer suporte à seleção de voz)
- Descrição (opcional)
- Texto simples. Markdown não é compatível. Mesmas opções de formatação que a resposta avançada em ficha de informações básica
As respostas de seleção visual exigem que você substitua um tipo pelo nome do slot usando
um tipo de ambiente de execução no modo TYPE_REPLACE
. No manipulador de eventos
do webhook, faça referência ao tipo a ser substituído pelo nome do slot, definido em
Como adicionar respostas de seleção na propriedade name
.
Depois que um tipo é substituído, o tipo resultante representa a coleção de itens que o usuário pode escolher nessas telas do Google Assistente.
Propriedades
O tipo de resposta de coleção tem as seguintes propriedades:
Propriedade | Tipo | Requisito | Descrição |
---|---|---|---|
items |
matriz de CollectionItem |
Obrigatório | Representa um item na coleção que os usuários podem selecionar. Cada
CollectionItem contém uma chave que é mapeada para um tipo referenciado
para o item da coleção. |
title |
string | Opcional | Título em texto simples da coleção. Os títulos precisam ser exclusivos em uma coleção para oferecer suporte à seleção de voz. |
subtitle |
string | Opcional | Subtítulo em texto simples da coleção. |
image_fill |
ImageFill |
Opcional | Borda entre o cartão e o contêiner da imagem a ser usada quando a proporção da imagem não corresponder à do contêiner. |
Exemplo de código
Os exemplos a seguir definem o conteúdo do prompt no código do webhook ou na resposta do webhook JSON. No entanto, também é possível definir o conteúdo da solicitação no Actions Builder (como YAML ou 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." } } } }
Navegação de coleções
Semelhante a uma coleção, a navegação de coleções é uma resposta avançada que permite que os usuários rolem pelos cards de opções. A navegação por coleção foi projetada especificamente para o conteúdo da Web e abre o bloco selecionado em um navegador da Web (ou em um navegador AMP se todos os blocos forem compatíveis com AMP).
As respostas da navegação de coleções contêm de 2 a 10 blocos. Em dispositivos compatíveis com tela, os usuários podem deslizar para cima ou para baixo para navegar pelos cards antes de selecionar um item.
Como criar um navegador de coleções
Ao criar uma navegação de coleção, considere como os usuários interagirão com essa
solicitação. Cada navegação de coleção item
abre o URL definido. Portanto, forneça detalhes úteis para o usuário.
Os itens de navegação das coleções têm as seguintes características de exibição:
- Imagem (opcional)
- A imagem é forçada a 128 dp de altura x 232 dp de largura.
- Se a proporção não corresponder à caixa delimitadora de imagem, ela será
centralizada com barras nas laterais ou nas partes de cima e de baixo. A cor das
barras é determinada pela propriedade
ImageFill
de navegação da coleção. - Se um link de imagem estiver corrompido, uma imagem de marcador será usada no lugar dela.
- Título (obrigatório)
- Texto simples. Markdown não é compatível. É usada a mesma formatação da resposta avançada de card básico.
- A altura do card vai ser fechada se nenhum título for definido.
- Descrição (opcional)
- Texto simples. Markdown não é compatível. É usada a mesma formatação da resposta avançada de card básico.
- Rodapé (opcional)
- Texto simples. Markdown não compatível.
Propriedades
O tipo de resposta de navegação de coleção tem as seguintes propriedades:
Propriedade | Tipo | Requisito | Descrição |
---|---|---|---|
item |
objeto | Obrigatório | Representa um item na coleção que os usuários podem selecionar. |
image_fill |
ImageFill |
Opcional | Borda entre o cartão e o contêiner da imagem a ser usada quando a proporção da imagem não corresponder à do contêiner. |
O recurso Procurar por coleção item
tem as seguintes propriedades:
Propriedade | Tipo | Requisito | Descrição |
---|---|---|---|
title |
string | Obrigatório | Título em texto simples do item da coleção. |
description |
string | Opcional | Descrição do item da coleção. |
footer |
string | Opcional | Texto do rodapé do item da coleção, exibido abaixo da descrição. |
image |
Image |
Opcional | Imagem exibida para o item da coleção. |
openUriAction |
OpenUrl |
Obrigatório | URI a ser aberto quando o item da coleção for selecionado. |
Exemplo de código
Os exemplos a seguir definem o conteúdo do prompt no código do webhook ou na resposta do webhook JSON. No entanto, também é possível definir o conteúdo da solicitação no Actions Builder (como YAML ou 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." } } } }