Użyj opcji odpowiedzi wizualnej, jeśli chcesz, aby użytkownik wybrał jedną z kilku dostępnych opcji. W ramach potwierdzenia możesz używać tych wizualnych typów odpowiedzi:
- Lista
- Kolekcja
- Przeglądanie kolekcji
Definiując odpowiedź wizualną, użyj kandydatu z właściwością RICH_RESPONSE, aby Asystent Google zwracał odpowiedzi tylko na obsługiwanych urządzeniach. W wierszu poleceń możesz użyć tylko 1 odpowiedzi z elementami rozszerzonymi na każdy obiekt content.
Dodawanie odpowiedzi wizualnej do wyboru
Odpowiedzi wizualne pozwalają wykorzystać boks do wypełnienia sceny, aby wyświetlić opcje, które użytkownik może wybrać i który obsługuje wybrany element. Gdy użytkownik wybierze element, Asystent przekazuje wybraną wartość elementu do webhooka jako argument. Następnie w wartości argumentu otrzymujesz klucz dla wybranego elementu.
Zanim użyjesz odpowiedzi wizualnej zaznaczenia, musisz zdefiniować typ, który reprezentuje odpowiedź późną. W webhooku zastępujesz ten typ treściami, które chcesz wyświetlić.
Aby dodać wizualną odpowiedź do sceny w Kreatorze działań, wykonaj te czynności:
- W scenie dodaj boks w sekcji Wypełnienie boksu reklamowego.
- Wybierz wcześniej zdefiniowany typ odpowiedzi na wybór treści i nadaj mu nazwę. Webhook używa tej nazwy przedziału, aby móc później odwoływać się do danego typu.
- Zaznacz pole Wywołaj webhooka i podaj nazwę modułu obsługi zdarzeń w webhooku, którego chcesz używać do odpowiedzi dotyczącej wyboru wizualnego.
- Zaznacz pole Wyślij prośby.
- W wierszu poleceń wpisz odpowiednią treść w formacie JSON lub YAML na podstawie wizualnej odpowiedzi, którą chcesz zwrócić.
- W webhooku wykonaj czynności opisane w sekcji Obsługa wybranych elementów.
Informacje o dostępnych właściwościach wiersza poleceń i przykładach zastąpień znajdziesz w sekcjach dotyczących list, kolekcji i kolekcji.
Obsługa wybranych elementów
Odpowiedzi wizualne do wyboru wymagają zmiany wyboru użytkownika w kodzie webhooka. Gdy użytkownik wybierze coś z odpowiedzi wizualnej, Asystent Google wypełnia boks tą wartością.
W tym przykładzie kod webhook otrzymuje i przechowuje wybraną opcję w zmiennej:
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
Użytkownicy mogą korzystać z pionowej listy zawierającej wiele elementów i wybierać je za pomocą dotyku lub głosu. Gdy użytkownik wybierze pozycję na liście, Asystent wygeneruje zapytanie (dymek czatu) z tytułem elementu listy.
Listy są przydatne, gdy trzeba rozróżnić opcje lub gdy użytkownik musi wybrać opcje, które trzeba przeskanować w całości. Z którym „Peterem” musisz na przykład porozmawiać z Peterem Jonsem lub Peterem Hansem?
Listy muszą zawierać od 2 do 30 elementów. Liczba wyświetlanych początkowo elementów zależy od urządzenia użytkownika. Typowy początek to 10 elementów.
Tworzenie listy
Podczas tworzenia listy komunikat zawiera tylko klucze do każdego elementu, który może wybrać użytkownik. W webhooku definiujesz elementy odpowiadające tym kluczom na podstawie typu Entry.
Elementy listy zdefiniowane jako obiekty Entry mają następujące właściwości wyświetlania:
- Tytuł
- Stały rozmiar czcionki
- Maksymalna długość: 1 wiersz (skrócony na wielokropek...)
- Musi być unikalny (aby umożliwić wybór głosu)
- Opis (opcjonalnie)
- Stały rozmiar czcionki
- Maksymalna długość: 2 wiersze (skrócone z wielokropkiem...)
- Obraz (opcjonalnie)
- Rozmiar: 48 x 48 piks.
Odpowiedzi wizualne do wyboru wymagają zastąpienia danego typu według nazwy przedziału przy użyciu typu środowiska wykonawczego w trybie TYPE_REPLACE. W module obsługi zdarzeń webhooka zastąp typ boksu nazwą (określoną w sekcji Dodawanie odpowiedzi na pytania w odpowiedzi) we właściwości name.
Po zastąpieniu jednego typu typ wynikowy reprezentuje listę elementów, które użytkownik może wybrać z poziomu Asystenta.
Usługi
Typ odpowiedzi na liście ma te właściwości:
| Właściwość | Typ | Wymaganie | Opis |
|---|---|---|---|
items |
tablica obiektu ListItem |
Wymagany | Reprezentuje element na liście, który użytkownicy mogą wybrać. Każdy element ListItem zawiera klucz mapowany na określony typ elementu listy. |
title |
tekst | Opcjonalna | Zwykły tytuł listy złożony z 1 wiersza. Jeśli nie podasz tytułu, wysokość karty zwinie się. |
subtitle |
tekst | Opcjonalna | Podtytuł tekstowy listy. |
Przykładowy kod
Poniższe przykłady określają treść komunikatu w kodzie webhooka lub odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować komunikat w konstruktorze działań (jako YAML lub 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."
}
}
}
}
Kolekcja
Kolekcja przewija się w poziomie i pozwala wybrać jeden element dotykowo lub głosowo. W porównaniu z listami kolekcje mają duże kafelki i mogą zapewniać bogatsze treści. Płytki tworzące kolekcję są podobne do podstawowej karty z obrazem. Gdy użytkownik wybiera element z kolekcji, Asystent generuje zapytanie (dymek czatu) zawierający tytuł elementu.
Kolekcje są przydatne, gdy użytkownikowi wyświetla się różne opcje, ale nie jest wymagane bezpośrednie porównanie (w przeciwieństwie do list). Ogólnie preferuj listy do kolekcji, ponieważ są one łatwiejsze do skanowania i interakcji z nimi za pomocą głosu.
Kolekcje muszą zawierać co najmniej 2 i maksymalnie 10 kafelków. Na urządzeniach obsługujących wyświetlacz możesz przesuwać palcem po karcie w lewo lub w prawo, aby wybrać element.
Tworzenie kolekcji
Podczas tworzenia kolekcji wiersz poleceń zawiera tylko klucze do każdego elementu, który może wybrać użytkownik. W webhooku definiujesz elementy odpowiadające tym kluczom na podstawie typu Entry.
Elementy kolekcji zdefiniowane jako obiekty Entry mają następujące właściwości wyświetlania:
- Obraz (opcjonalnie)
- Wymagana jest szerokość obrazu 128 dp x 232 dp
- Jeśli współczynnik proporcji obrazu nie pasuje do ramki ograniczającej, obraz jest wyśrodkowany z paskami po obu stronach.
- Jeśli link do zdjęcia jest uszkodzony, używany jest obraz zastępczy.
- Tytuł (wymagany)
- Zwykły tekst, format Markdown nie jest obsługiwany. Takie same opcje formatowania jak w przypadku podstawowych odpowiedzi dotyczących karty
- Wysokość karty zwija się, jeśli nie określisz tytułu.
- Musi być unikalny (aby umożliwić wybór głosu)
- Opis (opcjonalnie)
- Zwykły tekst, format Markdown nie jest obsługiwany. Takie same opcje formatowania jak w przypadku podstawowych odpowiedzi dotyczących karty
Odpowiedzi wizualne do wyboru wymagają zastąpienia danego typu według nazwy przedziału przy użyciu typu środowiska wykonawczego w trybie TYPE_REPLACE. W module obsługi zdarzeń webhooka zastąp typ boksu nazwą (określoną w sekcji Dodawanie odpowiedzi na pytania w odpowiedzi) we właściwości name.
Po zastąpieniu jednego typu typ wynikowy określa zbiór elementów, które użytkownik może wybrać z poziomu Asystenta.
Usługi
Typ odpowiedzi na kolekcję ma te właściwości:
| Właściwość | Typ | Wymaganie | Opis |
|---|---|---|---|
items |
tablica obiektu CollectionItem |
Wymagany | Reprezentuje element w kolekcji, który użytkownicy mogą wybrać. Każdy element CollectionItem zawiera klucz mapowany na określony typ elementu kolekcji. |
title |
tekst | Opcjonalna | Tytuł zwykłego tekstu kolekcji. Aby można było rozpoznawać głos, tytuły muszą być unikalne w kolekcji. |
subtitle |
tekst | Opcjonalna | Podtytuł w postaci zwykłego tekstu w zbiorze. |
image_fill |
ImageFill |
Opcjonalna | Obramowanie między kartą a kontenerem obrazu, które ma być używane, gdy współczynnik proporcji obrazu nie pasuje do współczynnika proporcji kontenera. |
Przykładowy kod
Poniższe przykłady określają treść komunikatu w kodzie webhooka lub odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować komunikat w konstruktorze działań (jako YAML lub 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."
}
}
}
}
Przeglądanie kolekcji
Podobnie jak kolekcja, przeglądanie kolekcji to bogata odpowiedź, która umożliwia użytkownikom przewijanie kart opcji. Przeglądanie kolekcji zostało opracowane specjalnie z myślą o treściach internetowych. Otwiera wybrany kafelek w przeglądarce (lub w przeglądarce AMP, jeśli wszystkie karty są włączone).
Odpowiedzi przeglądania kolekcji zawierają od 2 do 10 kafelków. Na urządzeniach obsługujących wyświetlacz możesz przesuwać palcem w górę lub w dół, aby przewijać karty, zanim wybierzesz element.
Tworzenie przeglądania kolekcji
Podczas tworzenia przeglądania kolekcji weź pod uwagę to, jak użytkownicy będą z niego korzystać. Każda przeglądająca kolekcję item otwiera zdefiniowany URL, więc podaj użytkownikowi przydatne informacje.
Elementy przeglądania kolekcji mają następujące właściwości wyświetlania:
- Obraz (opcjonalnie)
- Obraz jest wymuszany do wysokości 128 dp x 232 dp.
- Jeśli współczynnik proporcji obrazu nie pasuje do ramki ograniczającej, obraz jest wyśrodkowany z paskami po bokach lub u góry i u dołu. Kolor pasków jest określany przez właściwość
ImageFillkolekcji. - Jeśli link do zdjęcia jest uszkodzony, w zamian zostanie użyty obraz zastępczy.
- Tytuł (wymagany)
- Zwykły tekst, format Markdown nie jest obsługiwany. Użyj tego samego formatowania, co w przypadku podstawowej odpowiedzi z karty informacyjnej.
- Wysokość karty zwija się, jeśli nie ma zdefiniowanego tytułu.
- Opis (opcjonalnie)
- Zwykły tekst, format Markdown nie jest obsługiwany. Użyj tego samego formatowania, co w przypadku podstawowej odpowiedzi z karty informacyjnej.
- Stopka (opcjonalnie)
- Zwykły tekst; Markdown nie jest obsługiwany.
Usługi
Typ odpowiedzi dotyczącej przeglądania kolekcji ma następujące właściwości:
| Właściwość | Typ | Wymaganie | Opis |
|---|---|---|---|
item |
obiekt | Wymagany | Reprezentuje element w kolekcji, który użytkownicy mogą wybrać. |
image_fill |
ImageFill |
Opcjonalna | Obramowanie karty i kontenera obrazu, które ma być używane, gdy współczynnik proporcji obrazu nie odpowiada współczynnikowi proporcji kontenera obrazu. |
Przeglądanie kolekcji item ma takie właściwości:
| Właściwość | Typ | Wymaganie | Opis |
|---|---|---|---|
title |
tekst | Wymagany | Tytuł zwykłego tekstu elementu kolekcji. |
description |
tekst | Opcjonalna | Opis elementu kolekcji. |
footer |
tekst | Opcjonalna | Tekst stopki elementu kolekcji widoczny pod opisem. |
image |
Image |
Opcjonalna | Wyświetlane jest zdjęcie elementu kolekcji. |
openUriAction |
OpenUrl |
Wymagany | Identyfikator URI do otwarcia po wybraniu elementu kolekcji. |
Przykładowy kod
Poniższe przykłady określają treść komunikatu w kodzie webhooka lub odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować komunikat w konstruktorze działań (jako YAML lub 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."
}
}
}
}