Respostas visuais para seleção

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:

  1. Na cena, adicione um slot à seção Preenchimento de slot.
  2. 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.
  3. 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.
  4. Marque a caixa Enviar solicitações.
  5. No comando, forneça o conteúdo JSON ou YAML apropriado com base na resposta de seleção visual que você quer retornar.
  6. 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

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.

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)
  • 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."
      }
    }
  }
}