Jeśli użytkownik ma wybrać jedną z kilku opcji w celu kontynuowania akcji, użyj wizualnej odpowiedzi wyboru. W prompcie możesz używać tych typów odpowiedzi dotyczących wyboru wizualnego:
- Lista
- Kolekcja
- Przeglądanie kolekcji
Podczas definiowania odpowiedzi wizualnej wybierz kandydat z platformą RICH_RESPONSE. Dzięki temu Asystent Google będzie zwracał odpowiedź tylko na obsługiwanych urządzeniach. Możesz użyć tylko 1 odpowiedzi z elementami rozszerzonymi na obiekt content w prompcie.
Dodawanie odpowiedzi wyboru wizualnej
Wizualne odpowiedzi wyboru wykorzystują wypełnianie przedziałów w scenie zarówno do prezentowania opcji, które użytkownik może wybrać, jak i do obsługi wybranego elementu. Gdy użytkownicy wybierają element, Asystent przekazuje tę wartość do webhooka jako argument. Następnie jako wartość argumentu otrzymujesz klucz dla wybranego elementu.
Zanim użyjesz wizualnej odpowiedzi wyboru, musisz zdefiniować typ, który będzie reprezentował odpowiedź wybieraną później przez użytkownika. W webhooku zastąp ten typ treścią, którą chcesz wyświetlić do wyboru.
Aby dodać wizualną odpowiedź wyboru do sceny w Actions Builder:
- W scenie dodaj boks w sekcji Wypełnianie przedziałów.
- Wybierz wcześniej zdefiniowany typ odpowiedzi dotyczącej wyboru wizualnego i nadaj jej nazwę. Webhook użyje nazwy tego przedziału, aby później odwoływać się do tego typu.
- Zaznacz pole Wywołaj webhooka i podaj w webhooku nazwę modułu obsługi zdarzeń, którego chcesz używać w odpowiedzi wyboru wizualnego.
- Zaznacz pole Wysyłaj potwierdzenia.
- W prompcie podaj odpowiednią treść w formacie JSON lub YAML na podstawie wizualnej odpowiedzi wyboru, którą chcesz zwrócić.
- W webhooku wykonaj czynności opisane w sekcji Obsługa wybranych elementów.
W sekcjach list, kolekcji i przeglądania kolekcji poniżej znajdziesz dostępne właściwości promptów i przykłady ich zastępowania.
Obsługa wybranych elementów
Odpowiedzi wyboru wizualne wymagają obsługi wyboru użytkownika w kodzie webhooka. Gdy użytkownik wybierze coś z odpowiedzi na wybór wizualny, Asystent Google wypełnia boks odpowiednią wartością.
W poniższym przykładzie kod webhooka otrzymuje wybraną opcję i zapisuje ją 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
Lista zawiera pionową listę wielu elementów i umożliwia wybranie każdego z nich dotykowo lub głosowo. Gdy użytkownik wybiera pozycję na liście, Asystent generuje zapytanie (dymek czatu) zawierające tytuł elementu listy.
Listy przydają się, gdy ważne jest rozróżnianie opcji lub gdy użytkownik musi wybrać opcję, którą musi przeskanować w całości. Na przykład, do którego „Petera” potrzebujesz rozmawiać – z Peterem Jonsem czy Peterem Hansem?
Listy muszą zawierać od 2 do 30 pozycji. Liczba elementów wyświetlanych początkowo zależy od urządzenia użytkownika. Typowy numer początkowy to 10 elementów.
Tworzenie listy
Podczas tworzenia listy prompt zawiera tylko klucze dla każdego elementu, który użytkownik może wybrać. W webhooku określasz elementy odpowiadające tym kluczom na podstawie typu Entry.
Elementy listy zdefiniowane jako obiekty Entry mają te cechy wyświetlania:
- Tytuł
- Stały rozmiar czcionki
- Maksymalna długość: 1 wiersz (obcięty wielokropkiem...)
- Nazwa musi być niepowtarzalna (do obsługi wyboru głosu)
- Opis (opcjonalnie)
- Stały rozmiar czcionki
- Maksymalna długość: 2 wiersze (obcięte wielokropkiem...)
- Obraz (opcjonalnie)
- Rozmiar: 48 x 48 pikseli
Wizualne odpowiedzi wyboru wymagają zastąpienia typu nazwą przedziału za pomocą typu środowiska wykonawczego w trybie TYPE_REPLACE. W module obsługi zdarzeń webhooka określ typ, który chcesz zastąpić, podając nazwę jego boksu (zdefiniowaną w sekcji Dodawanie odpowiedzi wyboru) we właściwości name.
Po zastąpieniu typu wynikowy typ reprezentuje listę elementów, które użytkownik może wybrać z wyświetlanego przez Asystenta.
Właściwości
Typ odpowiedzi listy ma te właściwości:
| Właściwość | Typ | Wymaganie | Opis |
|---|---|---|---|
items |
tablica ListItem |
Wymagane | Reprezentuje element na liście, który użytkownicy mogą wybrać. Każdy element ListItem zawiera klucz mapowany na typ, do którego odwołuje się element listy. |
title |
ciąg znaków | Opcjonalnie | Tytuł listy w postaci zwykłego tekstu (maksymalnie 1 wiersz). Jeśli nie podasz tytułu, wysokość karty zostanie zwinięta. |
subtitle |
ciąg znaków | Opcjonalnie | Podtytuł listy w postaci zwykłego tekstu. |
Przykładowy kod
Poniższe przykłady określają treść promptu w kodzie webhooka lub w odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować treść promptu w Actions Builder (w formacie 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 umożliwia użytkownikom wybranie jednego elementu za pomocą dotyku lub rozpoznawania mowy. W porównaniu z listami kolekcje mają większe kafelki i zawierają bogatsze treści. Kafelki tworzące kolekcję są podobne do podstawowej karty z obrazem. Gdy użytkownik wybierze element z kolekcji, Asystent wygeneruje zapytanie (dymek czatu) zawierające tytuł elementu.
Kolekcje są przydatne, gdy użytkownik ma przedstawić różne opcje, ale bezpośrednie porównanie ich nie jest wymagane (w porównaniu z listami). Ogólnie lepiej używaj list niż kolekcji, ponieważ łatwiej jest je przeglądać i sterować głosem.
Kolekcje muszą zawierać od 2 do 10 kafelków. Na urządzeniach z wyświetlaczem użytkownicy mogą przesuwać palcem w lewo lub w prawo, aby przewijać karty w kolekcji, zanim wybierzą element.
Tworzenie kolekcji
Podczas tworzenia kolekcji prompt zawiera tylko klucze dla każdego elementu, który użytkownik może wybrać. W webhooku określasz elementy odpowiadające tym kluczom na podstawie typu Entry.
Elementy w kolekcji zdefiniowane jako obiekty Entry mają te cechy wyświetlania:
- Obraz (opcjonalnie)
- Obraz musi mieć wysokość 128 dp i szerokość 232 dp
- Jeśli współczynnik proporcji obrazu nie jest zgodny z ramką ograniczającą, obraz zostanie wyśrodkowany z paskami po obu stronach.
- Jeśli link do zdjęcia jest uszkodzony, zamiast niego zostanie użyty obraz zastępczy.
- Tytuł (wymagany)
- Zwykły tekst nie jest obsługiwany. Takie same opcje formatowania jak w przypadku podstawowej odpowiedzi z elementami rozszerzonymi
- Wysokość karty zwija się, jeśli nie określono tytułu.
- Nazwa musi być niepowtarzalna (do obsługi wyboru głosu)
- Opis (opcjonalnie)
- Zwykły tekst nie jest obsługiwany. Takie same opcje formatowania jak w przypadku podstawowej odpowiedzi z elementami rozszerzonymi
Wizualne odpowiedzi wyboru wymagają zastąpienia typu nazwą przedziału za pomocą typu środowiska wykonawczego w trybie TYPE_REPLACE. W module obsługi zdarzeń webhooka określ typ, który chcesz zastąpić, podając nazwę jego boksu (zdefiniowaną w sekcji Dodawanie odpowiedzi wyboru) we właściwości name.
Po zastąpieniu typu wynikowy typ reprezentuje zbiór elementów, które użytkownik może wybrać z wyświetlanych przez Asystenta.
Właściwości
Typ odpowiedzi kolekcji ma te właściwości:
| Właściwość | Typ | Wymaganie | Opis |
|---|---|---|---|
items |
tablica CollectionItem |
Wymagane | Reprezentuje element w kolekcji, który użytkownicy mogą wybrać. Każdy element CollectionItem zawiera klucz mapowany na określony typ elementu kolekcji. |
title |
ciąg znaków | Opcjonalnie | Zwykły tekst tytułu kolekcji. Aby można było wybrać głos, tytuły muszą być unikalne w obrębie kolekcji. |
subtitle |
ciąg znaków | Opcjonalnie | Zwykły tekst podtytuł kolekcji. |
image_fill |
ImageFill |
Opcjonalnie | Obramowanie między kartą a kontenerem obrazu, używane, gdy współczynnik proporcji obrazu nie jest zgodny ze współczynnikiem proporcji kontenera obrazów. |
Przykładowy kod
Poniższe przykłady określają treść promptu w kodzie webhooka lub w odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować treść promptu w Actions Builder (w formacie 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 w przypadku kolekcji przeglądanie kolekcji umożliwia użytkownikom przewijanie kart opcji. Przeglądanie kolekcji zostało zaprojektowane specjalnie pod kątem treści internetowych i otwiera wybrany kafelek w przeglądarce (lub w przeglądarce AMP, jeśli wszystkie kafelki obsługują AMP).
Odpowiedzi podczas przeglądania kolekcji zawierają od 2 do 10 kafelków. Na urządzeniach wyposażonych w wyświetlacz użytkownik może przewijać karty, przesuwając palcem w górę lub w dół, zanim wybierze element.
Tworzenie przeglądania kolekcji
Podczas tworzenia przeglądania kolekcji zastanów się, jak użytkownicy będą wchodzić w interakcję z tym komunikatem. Każdy element item przeglądania kolekcji otwiera zdefiniowany adres URL, więc podaj użytkownikowi przydatne informacje.
Elementy przeglądania kolekcji mają te cechy wyświetlania:
- Obraz (opcjonalnie)
- Obraz ma wymiary 128 dp (wysokość) i 232 dp (szerokość).
- Jeśli współczynnik proporcji obrazu nie jest zgodny z ramką ograniczającą obraz, zostanie on wyśrodkowany z paskami po bokach lub u góry i dołu. Kolor pasków jest określany przez właściwość przeglądania kolekcji
ImageFill. - Jeśli link do zdjęcia nie działa, zamiast niego jest używany obraz zastępczy.
- Tytuł (wymagany)
- Zwykły tekst nie jest obsługiwany. Używane jest takie samo formatowanie jak w przypadku podstawowej odpowiedzi z elementami rozszerzonymi.
- Wysokość karty zwija się, jeśli nie określono tytułu.
- Opis (opcjonalnie)
- Zwykły tekst nie jest obsługiwany. Używane jest takie samo formatowanie jak w przypadku podstawowej odpowiedzi z elementami rozszerzonymi.
- Stopka (opcjonalnie)
- Zwykły tekst; Markdown nie jest obsługiwany.
Właściwości
Typ odpowiedzi przeglądania kolekcji ma te właściwości:
| Właściwość | Typ | Wymaganie | Opis |
|---|---|---|---|
item |
obiekt | Wymagane | Reprezentuje element w kolekcji, który użytkownicy mogą wybrać. |
image_fill |
ImageFill |
Opcjonalnie | Obramowanie między kartą a kontenerem obrazu, używane, gdy współczynnik proporcji obrazu nie jest zgodny ze współczynnikiem proporcji kontenera obrazów. |
Funkcja przeglądania kolekcji item ma następujące właściwości:
| Właściwość | Typ | Wymaganie | Opis |
|---|---|---|---|
title |
ciąg znaków | Wymagane | Tytuł elementu kolekcji w postaci zwykłego tekstu. |
description |
ciąg znaków | Opcjonalnie | Opis elementu kolekcji. |
footer |
ciąg znaków | Opcjonalnie | Tekst stopki elementu kolekcji wyświetlany pod opisem. |
image |
Image |
Opcjonalnie | Obraz wyświetlany dla elementu kolekcji. |
openUriAction |
OpenUrl |
Wymagane | Identyfikator URI otwierany po wybraniu elementu kolekcji. |
Przykładowy kod
Poniższe przykłady określają treść promptu w kodzie webhooka lub w odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować treść promptu w Actions Builder (w formacie 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."
}
}
}
}