Esta página foi traduzida pela API Cloud Translation.

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 prompt:

Listar
Coleção
Navegação da coleção

Ao definir uma resposta de seleção visual, use um candidato com o recurso de superfície RICH_RESPONSE para que o Google Assistente só retorne a resposta em dispositivos compatíveis. É possível usar apenas uma resposta avançada por objeto content em uma solicitação.

Como adicionar uma resposta visual à seleção

As respostas de seleção visual usam o preenchimento de slot 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 do item selecionado.

Antes de usar uma resposta de seleção visual, é necessário definir um tipo que represente a resposta que um usuário selecionar posteriormente. No webhook, modifique esse tipo com 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 tipo definido anteriormente para sua resposta de seleção visual e dê um nome a ele. Seu 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 prompt, 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 gerenciar itens selecionados.

Consulte as seções list, collection e collection browse abaixo para ver as propriedades de prompt disponíveis e exemplos de tipos de modificação.

Como processar itens selecionados

As respostas da seleção visual exigem que você manipule a seleção de um usuário no código do webhook. Quando o usuário seleciona algo de 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 (link em inglês)

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

Listar

Exemplo de uma 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 selecionar um por toque ou entrada de texto por voz. Quando um usuário seleciona um item da lista, o Google Assistente gera uma consulta do usuário (balão de chat) contendo o título do item da lista.

As listas são boas para quando é importante eliminar a ambiguidade das opções ou quando o usuário precisa escolher entre opções que precisam ser totalmente verificadas. 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 exibidos inicialmente depende do dispositivo do usuário, e o número inicial comum é de 10 itens.

Como criar uma lista

Ao criar uma lista, seu prompt contém apenas chaves para cada item que um usuário pode selecionar. No webhook, você define 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 fixos
- Comprimento máximo: uma linha (truncada com reticências...)
- Necessário para ser exclusivo (para oferecer compatibilidade com a seleção de voz)
Descrição (opcional)
- Fonte e tamanho da fonte fixos
- Comprimento máximo: duas 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 a partir 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 da 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 do texto sem formatação da lista, restrito a uma única linha. Se nenhum título for especificado, a altura do card será recolhida.
`subtitle`	string	Opcional	Subtítulo de texto simples da lista.

Exemplo de código

Os exemplos a seguir definem o conteúdo do prompt no código do webhook ou no webhook webhook JSON. No entanto, você também pode definir o conteúdo do prompt no Actions Builder (como YAML ou JSON).

Node.js (link em inglês)

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 a tela horizontalmente e permite que os usuários selecionem um item por toque ou entrada de voz. Em comparação com listas, as coleções têm blocos grandes e permitem 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 do usuário (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 uma comparação direta não é necessária entre elas (em comparação com listas). Em geral, prefira listas a coleções, porque elas são mais fáceis de verificar visualmente e interagir por voz.

As coleções precisam conter no mínimo dois e no máximo 10 blocos. Em dispositivos com funcionalidade de exibição, os usuários podem deslizar para a esquerda ou direita para rolar pelos cards de uma coleção antes de selecionar um item.

Exemplo de uma resposta de seleção de coleção em um smart display

Como criar uma coleção

Ao criar uma coleção, o prompt contém apenas chaves para cada item que um usuário pode selecionar. No webhook, você define 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, a imagem será centralizada com barras em ambos os lados
- Se um link de imagem estiver corrompido, uma imagem de marcador será usada
Título (obrigatório)
- Texto simples, não há suporte para Markdown. As mesmas opções de formatação da resposta avançada do cartão básico
- A altura do card será recolhida se nenhum título for especificado.
- Necessário para ser exclusivo (para oferecer compatibilidade com a seleção de voz)
Descrição (opcional)
- Texto simples, não há suporte para Markdown. As mesmas opções de formatação da resposta avançada do cartão básico

Depois que um tipo é substituído, o tipo resultante representa a coleção de itens que o usuário pode escolher a partir do Google Assistente exibido.

Propriedades

O tipo de resposta da coleção tem as seguintes propriedades:

Propriedade	Tipo	Requisito	Descrição
`items`	matriz de `CollectionItem`	Obrigatório	Representa um item da 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 serem compatíveis com a seleção de voz.
`subtitle`	string	Opcional	Subtítulo de texto simples da coleção.
`image_fill`	`ImageFill`	Opcional	Borda entre o card e o contêiner de imagem a ser usado quando a proporção não corresponder à do contêiner de imagem.

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, você também pode definir o conteúdo do prompt no Actions Builder (como YAML ou JSON).

Node.js (link em inglês)

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 da coleção

Semelhante a uma coleção, a navegação por coleções é uma resposta avançada que permite aos usuários rolar pelos cards de opções. A procura de coleções foi criada especificamente para conteúdo da Web e abre o bloco selecionado em um navegador da Web (ou em um navegador AMP, se todos os blocos estiverem ativados para AMP).

As respostas de navegação da coleção contêm um mínimo de 2 e um máximo de 10 blocos. Em dispositivos com funcionalidade de exibição, os usuários podem deslizar para cima ou para baixo para rolar pelos cards antes de selecionar um item.

Como criar uma navegação de coleção

Ao criar uma navegação de coleção, considere como os usuários vão interagir com essa solicitação. Cada coleção de procura item abre o URL definido. Por isso, forneça detalhes úteis ao usuário.

Os itens de navegação da coleção têm as seguintes características de exibição:

Imagem (opcional)
- A imagem é forçada para 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 nas laterais ou na parte superior e inferior. A cor das barras é determinada pela propriedade ImageFill do navegador da coleção.
- Se o link de uma imagem estiver corrompido, uma imagem de marcador será usada no lugar dela.
Título (obrigatório)
- Texto simples, não há suporte para Markdown. A mesma formatação da resposta básica do card básico é usada.
- A altura do card será recolhida se nenhum título for definido.
Descrição (opcional)
- Texto simples, não há suporte para Markdown. A mesma formatação da resposta básica do card básico é usada.
Rodapé (opcional)
- Texto simples. Não há suporte para marcação.

Propriedades

O tipo de resposta de navegação da coleção tem as seguintes propriedades:

Propriedade	Tipo	Requisito	Descrição
`item`	objeto	Obrigatório	Representa um item da coleção que os usuários podem selecionar.
`image_fill`	`ImageFill`	Opcional	Borda entre o card e o contêiner de imagem a ser usado quando a proporção da imagem não corresponder à do contêiner de imagem.

A navegação da 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 de coleção.
`openUriAction`	`OpenUrl`	Obrigatório	URI a ser aberto quando o item da coleção for selecionado.

Exemplo de código

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 (link em inglês)

// 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."
      }
    }
  }
}