Czynności dotyczące rozmów zostały wycofane 13 czerwca 2023 r. Więcej informacji znajdziesz w artykule Wycofanie czynności konwersacyjnych.

Odpowiedzi wizualne

Użyj odpowiedzi wizualnej, jeśli chcesz, aby użytkownik wybrał jedną z kilku dostępnych opcji, aby kontynuować działanie. W propozycji możesz użyć tych rodzajów odpowiedzi wizualnych wyboru:

  • Lista
  • Kolekcja
  • Przeglądanie kolekcji

Podczas definiowania odpowiedzi wizualnych użyj kandydatu z właściwością RICH_RESPONSE, by Asystent Google zwracał odpowiedzi tylko na obsługiwanych urządzeniach. W każdym wierszu obiektu możesz użyć tylko 1 odpowiedzi na żądanie content.

Dodawanie wizualnej odpowiedzi na pytanie o wybór

Wizualne odpowiedzi związane z wyborem wykorzystują wypełnianie boksu zarówno w celu zaprezentowania opcji, które użytkownik może wybrać, jak i obsługiwania wybranego elementu. Gdy użytkownik wybiera element, Asystent przekazuje wybraną wartość elementu do webhooka jako argument. Następnie w wartości argumentu otrzymujesz klucz dla wybranego elementu.

Zanim użyjesz wizualnej odpowiedzi wyboru, musisz zdefiniować typ, który reprezentuje odpowiedź wybraną później przez użytkownika. 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:

  1. W scenie dodaj boks w sekcji Wypełnienie boksu.
  2. Wybierz wcześniej zdefiniowany typ swojej odpowiedzi wizualnej odpowiedzi i nadaj jej nazwę. Webhook używa tej nazwy boksu, by później się do niego odwoływać.
  3. Zaznacz pole Wywołaj webhooka i podaj nazwę modułu obsługi zdarzeń w webhooku, której chcesz używać w przypadku odpowiedzi wizualnej wyboru.
  4. Zaznacz pole Wyślij potwierdzenia.
  5. W wierszu poleceń wpisz odpowiednią treść JSON lub YAML na podstawie wizualnej odpowiedzi, którą chcesz zwrócić.
  6. W webhooku wykonaj czynności opisane w artykule Obsługa wybranych elementów.

Informacje o dostępnych właściwościach wiersza poleceń i przykładach zastąpień wymienionych poniżej znajdziesz w sekcjach dotyczących list, kolekcji i kolekcji.

Obsługa wybranych elementów

Odpowiedzi wizualne do wyboru wymagają obsługi wyboru użytkownika w kodzie webhooka. Gdy użytkownik wybierze coś z odpowiedzi wizualnej, Asystent Google wypełnia tę wartość odpowiednimi polami.

W tym przykładzie kod webhook odbiera 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

Przykład odpowiedzi na wybór listy na urządzeniu mobilnym

Dzięki niej użytkownicy mają dostęp do pionowych list wielu elementów i mogą ją wybrać dotykiem lub głosowo. Gdy użytkownik wybiera pozycję na liście, Asystent generuje zapytanie (dymek czatu) z tytułem tej pozycji.

Listy są przydatne, gdy trzeba rozróżnić opcje lub gdy użytkownik musi wybrać którąś z opcji skanowania w całości. Z kim kontakt ze Peterem Jonsem lub Peterem Hansem to na przykład „Peter”?

Listy muszą zawierać od 2 do 30 elementów. Liczba wyświetlanych elementów zależy od urządzenia użytkownika, a typowy początek to 10 elementów.

Tworzenie listy

Podczas tworzenia listy monit zawiera tylko klucze dla każdego elementu, który użytkownik może wybrać. W webhooku definiujesz elementy odpowiadające tym kluczom na podstawie typu Entry.

Elementy listy zdefiniowane jako obiekty Entry mają następujące cechy wyświetlania:

  • Tytuł
    • Stały rozmiar czcionki
    • Maksymalna długość: 1 wiersz (skrócony na podstawie wielokropka)
    • Wymagane, aby były unikalne (obsługa wyboru głosu)
  • Opis (opcjonalny)
    • Stały rozmiar czcionki
    • Maksymalna długość: 2 wiersze (obcinane wielokropkiem)
  • Obraz (opcjonalnie)
    • Rozmiar: 48 x 48 pikseli

Wizualne odpowiedzi do wyboru wymagają zastąpienia typu na podstawie nazwy przedziału przy użyciu typu środowiska wykonawczego w trybie TYPE_REPLACE. W module obsługi zdarzeń webhooka zastąp ten typ nazwą właściwości (zgodnie z definicją w sekcji Dodawanie odpowiedzi na potrzeby wyboru) we właściwości name.

Gdy typ zostanie zastąpiony, typ wynikowy będzie zawierał listę elementów, które użytkownik może wybrać z wyświetlanego Asystenta.

Właściwości

Typ odpowiedzi na liście ma te właściwości:

Właściwość Typ Wymaganie Opis
items tablica 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 Opcjonalnie Tytuł zwykłego tekstu listy, ograniczony do jednego wiersza. Jeśli tytuł nie zostanie określony, wysokość karty zwinie się.
subtitle tekst Opcjonalnie Podtytuł listy tekstowej.

Przykładowy kod

Poniższe przykłady określają zawartość wiersza poleceń w kodzie webhook lub w odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować treść wiersza poleceń w Actions Actions (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 dotykiem lub głosem. W porównaniu z listami kolekcje mają większe kafelki i umożliwiają bogatsze treści. Kafelki, które tworzą kolekcję, są podobne do karty podstawowej z obrazem. Gdy użytkownik wybiera element w kolekcji, Asystent generuje zapytanie (dymek czatu) z tytułem elementu.

Kolekcje są dobre, gdy użytkownik ma do wyboru różne opcje, ale nie jest wymagane bezpośrednie porównanie (w przeciwieństwie do list). Ogólnie stosuj listy do kolekcji, ponieważ są łatwiejsze do skanowania oraz interakcji głosowej.

Kolekcje muszą zawierać od 2 do 10 kafelków. Na urządzeniach z wyświetlaczem użytkownik może przesuwać karty w lewo lub w prawo, aby wybrać elementy z kolekcji.

Tworzenie kolekcji

Podczas tworzenia kolekcji pojawia się tylko klucz dla każdego elementu, który użytkownik może wybrać. 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)
    • Obraz musi mieć szerokość 128 dp × 232 dp
    • Jeśli współczynnik proporcji obrazu nie pasuje do ramki ograniczającej obrazu, obraz jest wyśrodkowany z paskami po obu stronach
    • Jeśli link do zdjęcia jest uszkodzony, zamiast tego używany jest obraz zastępczy.
  • Tytuł (wymagany)
    • Markdown nie obsługuje zwykłego tekstu. Takie same opcje formatowania jak w przypadku podstawowej odpowiedzi z elementami rozszerzonymi na karcie
    • Wysokość karty zwija się, jeśli nie określono tytułu.
    • Wymagane, aby były unikalne (obsługa wyboru głosu)
  • Opis (opcjonalny)
    • Markdown nie obsługuje zwykłego tekstu. Takie same opcje formatowania jak w przypadku podstawowej odpowiedzi z elementami rozszerzonymi na karcie

Wizualne odpowiedzi do wyboru wymagają zastąpienia typu na podstawie nazwy przedziału przy użyciu typu środowiska wykonawczego w trybie TYPE_REPLACE. W module obsługi zdarzeń webhooka zastąp ten typ nazwą właściwości (zgodnie z definicją w sekcji Dodawanie odpowiedzi na potrzeby wyboru) we właściwości name.

Po zastąpieniu typu wynikowy zbiór elementów, które użytkownik może wybrać, wyświetla się w Asystencie.

Właściwości

Typ odpowiedzi na kolekcję ma następujące właściwości:

Właściwość Typ Wymaganie Opis
items tablica 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 Opcjonalnie Tytuł zwykłego tekstu kolekcji. Aby można było korzystać z wyboru głosowego, tytuły muszą być unikalne w kolekcji.
subtitle tekst Opcjonalnie Podtytuł tekstowy kolekcji.
image_fill ImageFill Opcjonalnie Obramowanie między kartą a kontenerem obrazu, które ma być stosowane, gdy współczynnik proporcji obrazu nie odpowiada współczynnikowi proporcji kontenera obrazu.

Przykładowy kod

Poniższe przykłady określają zawartość wiersza poleceń w kodzie webhook lub odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować treść wiersza poleceń w Actions Actions (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 to rozbudowana odpowiedź, która pozwala użytkownikom przewijać karty opcji. Przeglądanie kolekcji zostało zaprojektowane specjalnie z myślą o treściach internetowych. Otwiera wybrany kafelek w przeglądarce (lub w przeglądarce AMP, jeśli wszystkie kafelki są włączone na AMP).

Odpowiedzi przeglądania kolekcji zawierają co najmniej 2, a maksymalnie 10 kafelków. Na urządzeniach z wyświetlaczem użytkownik musi przewinąć kartę, aby móc wybrać element.

Tworzenie przeglądania kolekcji

Podczas tworzenia przeglądania kolekcji weź pod uwagę to, jak użytkownicy mogą korzystać z tego komunikatu. Każda kolekcja item otwiera zdefiniowany adres URL, więc podaj użytkownikowi przydatne informacje.

Elementy do przeglądania kolekcji mają następujące cechy wyświetlania:

  • Obraz (opcjonalnie)
    • Obraz jest wymuszany do wysokości 128 dp x 232 dp szerokości.
    • Jeśli współczynnik proporcji obrazu nie pasuje do ramki ograniczającej obrazu, 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ść ImageFill przeglądania kolekcji.
    • Jeśli link do zdjęcia jest uszkodzony, zamiast niego używany jest obraz zastępczy.
  • Tytuł (wymagany)
  • Opis (opcjonalny)
  • Stopka (opcjonalnie)
    • Zwykły tekst. Markdown nie jest obsługiwany.

Właściwości

Typ odpowiedzi na przeglądanie kolekcji ma te 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 Opcjonalnie Obramowanie między kartą a kontenerem obrazu, które ma być stosowane, gdy współczynnik proporcji obrazu nie odpowiada współczynnikowi proporcji kontenera obrazu.

Funkcja przeglądania kolekcji item ma te właściwości:

Właściwość Typ Wymaganie Opis
title tekst Wymagany Tytuł tekstowy kolekcji.
description tekst Opcjonalnie Opis elementu kolekcji.
footer tekst Opcjonalnie Tekst stopki elementu kolekcji widoczny pod opisem.
image Image Opcjonalnie Obraz dla elementu kolekcji.
openUriAction OpenUrl Wymagany Identyfikator URI do otwarcia po wybraniu elementu kolekcji.

Przykładowy kod

Poniższe przykłady określają zawartość wiersza poleceń w kodzie webhook lub odpowiedzi webhooka JSON. Zamiast tego możesz też zdefiniować treść wiersza poleceń w Actions Actions (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."
      }
    }
  }
}