Respons pemilihan visual

Gunakan respons pemilihan visual jika Anda ingin pengguna memilih salah satu di antara beberapa opsi untuk melanjutkan Action Anda. Anda dapat menggunakan jenis respons pemilihan visual berikut sebagai bagian dari perintah:

  • Daftar
  • Collection
  • Penjelajahan koleksi

Saat menentukan respons pemilihan visual, gunakan kandidat dengan kemampuan platform RICH_RESPONSE sehingga Asisten Google hanya menampilkan respons di perangkat yang didukung. Anda hanya dapat menggunakan satu respons lengkap per objek content dalam satu perintah.

Menambahkan respons pemilihan visual

Respons pemilihan visual menggunakan slot yang mengisi scene untuk menampilkan opsi yang dapat dipilih pengguna dan untuk menangani item yang dipilih. Saat pengguna memilih item, Asisten akan meneruskan nilai item yang dipilih ke webhook Anda sebagai argumen. Kemudian, dalam nilai argumen, Anda menerima kunci untuk item yang dipilih.

Sebelum dapat menggunakan respons pemilihan visual, Anda harus menentukan jenis yang mewakili respons yang dipilih pengguna nanti. Di webhook, Anda mengganti jenis tersebut dengan konten yang ingin ditampilkan untuk dipilih.

Untuk menambahkan respons pemilihan visual ke scene di Action Builder, ikuti langkah-langkah berikut:

  1. Dalam scene, tambahkan slot ke bagian Slot fill.
  2. Pilih jenis yang telah ditentukan sebelumnya untuk respons pemilihan visual Anda dan beri nama. Webhook Anda akan menggunakan nama slot ini untuk mereferensikan jenis pada lain waktu.
  3. Centang kotak Call your webhook dan berikan nama pengendali peristiwa di webhook yang ingin Anda gunakan untuk respons pemilihan visual.
  4. Centang kotak Sendprompt.
  5. Dalam perintah, berikan konten JSON atau YAML yang sesuai berdasarkan respons pemilihan visual yang ingin Anda tampilkan.
  6. Di webhook, ikuti langkah-langkah dalam Menangani item yang dipilih.

Lihat bagian daftar, koleksi, dan penjelajahan koleksi di bawah untuk mengetahui properti perintah yang tersedia dan contoh jenis penggantian.

Menangani item yang dipilih

Respons pemilihan visual mengharuskan Anda menangani pilihan pengguna dalam kode webhook. Saat pengguna memilih sesuatu dari respons pemilihan visual, Asisten Google akan mengisi slot dengan nilai tersebut.

Pada contoh berikut, kode webhook menerima dan menyimpan opsi yang dipilih dalam variabel:

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

Daftar

Contoh respons pemilihan daftar di perangkat seluler

Daftar memberi pengguna daftar vertikal yang berisi beberapa item dan memungkinkan mereka memilih satu item dengan sentuhan atau input suara. Saat pengguna memilih item dari daftar, Asisten akan membuat kueri pengguna (balon chat) yang berisi judul item daftar.

Daftar cocok untuk saat-saat penting untuk membedakan opsi, atau ketika pengguna perlu memilih di antara opsi yang perlu dipindai secara keseluruhan. Misalnya, "Peter" mana yang perlu Anda hubungi, Peter Jons atau Peter Hans?

Daftar harus berisi minimal 2 dan maksimal 30 item daftar. Jumlah elemen yang awalnya ditampilkan bergantung pada perangkat pengguna, dan nomor awal umum adalah 10 item.

Membuat daftar

Saat membuat daftar, perintah Anda hanya berisi kunci untuk setiap item yang dapat dipilih pengguna. Di webhook, Anda menentukan item yang sesuai dengan kunci tersebut berdasarkan jenis Entry.

Item daftar yang ditentukan sebagai objek Entry memiliki karakteristik tampilan berikut:

  • Judul
    • Font dan ukuran font tetap
    • Panjang maks: 1 baris (dipotong dengan elipsis...)
    • Harus unik (untuk mendukung pemilihan suara)
  • Deskripsi (opsional)
    • Font dan ukuran font tetap
    • Panjang maks: 2 baris (dipotong dengan elipsis...)
  • Gambar (opsional)
    • Ukuran: 48x48 px

Respons pemilihan visual mengharuskan Anda mengganti jenis berdasarkan nama slotnya menggunakan jenis runtime dalam mode TYPE_REPLACE. Di pengendali peristiwa webhook Anda, rujuk jenis yang akan diganti dengan nama slotnya (ditentukan dalam Menambahkan respons pilihan) di properti name.

Setelah jenis ditimpa, jenis yang dihasilkan mewakili daftar item yang dapat dipilih pengguna dari yang ditampilkan Asisten tersebut.

Properti

Jenis respons daftar memiliki properti berikut:

Properti Jenis Persyaratan Deskripsi
items array ListItem Wajib Mewakili item dalam daftar yang dapat dipilih pengguna. Setiap ListItem berisi kunci yang memetakan ke jenis yang direferensikan untuk item daftar.
title string Opsional Judul teks biasa daftar, dibatasi untuk satu baris. Jika tidak ada judul yang ditentukan, tinggi kartu akan diciutkan.
subtitle string Opsional Subtitel teks biasa dalam daftar.

Kode contoh

Contoh berikut menentukan konten perintah dalam kode webhook atau di webhookResponse JSON. Namun, Anda juga dapat menentukan konten perintah di Actions Builder (sebagai YAML atau 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."
     }
   }
 }
}

Collection

Koleksi di-scroll secara horizontal dan memungkinkan pengguna memilih satu item dengan sentuhan atau input suara. Dibandingkan dengan daftar, koleksi memiliki kartu besar dan memungkinkan konten yang lebih lengkap. Kartu yang membentuk koleksi mirip dengan kartu dasar dengan gambar. Saat pengguna memilih item dari koleksi, Asisten akan membuat kueri pengguna (balon chat) yang berisi judul item.

Koleksi berfungsi baik jika berbagai opsi ditampilkan kepada pengguna, tetapi perbandingan langsung tidak diperlukan untuk opsi tersebut (dibandingkan daftar). Secara umum, pilih daftar daripada koleksi karena daftar lebih mudah dipindai secara visual dan berinteraksi dengan suara.

Koleksi harus berisi minimal 2 dan maksimal 10 kotak. Pada perangkat yang mendukung layar, pengguna dapat menggeser ke kiri atau kanan untuk men-scroll kartu dalam koleksi sebelum memilih item.

Membuat koleksi

Saat membuat koleksi, perintah Anda hanya berisi kunci untuk setiap item yang dapat dipilih pengguna. Di webhook, Anda menentukan item yang sesuai dengan kunci tersebut berdasarkan jenis Entry.

Item koleksi yang ditentukan sebagai objek Entry memiliki karakteristik tampilan berikut:

  • Gambar (opsional)
    • Gambar dipaksa memiliki tinggi 128 dp x lebar 232 dp
    • Jika rasio aspek gambar tidak cocok dengan kotak pembatas gambar, gambar akan dipusatkan dengan batang di kedua sisi
    • Jika link gambar rusak, gambar placeholder akan digunakan
  • Judul (wajib diisi)
    • Teks biasa, Markdown tidak didukung. Opsi pemformatan yang sama seperti respons kaya kartu dasar
    • Tinggi kartu diciutkan jika tidak ada judul yang ditentukan.
    • Harus unik (untuk mendukung pemilihan suara)
  • Deskripsi (opsional)
    • Teks biasa, Markdown tidak didukung. Opsi pemformatan yang sama seperti respons kaya kartu dasar

Respons pemilihan visual mengharuskan Anda mengganti jenis berdasarkan nama slotnya menggunakan jenis runtime dalam mode TYPE_REPLACE. Di pengendali peristiwa webhook Anda, rujuk jenis yang akan diganti dengan nama slotnya (ditentukan dalam Menambahkan respons pilihan) di properti name.

Setelah jenis ditimpa, jenis yang dihasilkan mewakili koleksi item yang dapat dipilih pengguna dari tampilan Asisten tersebut.

Properti

Jenis respons pengumpulan memiliki properti berikut:

Properti Jenis Persyaratan Deskripsi
items array CollectionItem Wajib Mewakili item dalam koleksi yang dapat dipilih pengguna. Setiap CollectionItem berisi kunci yang memetakan ke jenis yang direferensikan untuk item koleksi.
title string Opsional Judul teks biasa koleksi. Judul harus unik dalam koleksi untuk mendukung pemilihan suara.
subtitle string Opsional Subjudul teks biasa koleksi.
image_fill ImageFill Opsional Batas antara kartu dan penampung gambar yang akan digunakan jika rasio aspek gambar tidak cocok dengan rasio aspek penampung gambar.

Kode contoh

Contoh berikut menentukan konten perintah dalam kode webhook atau dalam respons webhook JSON. Namun, Anda juga dapat menentukan konten perintah di Actions Builder (sebagai YAML atau 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."
      }
    }
  }
}

Penjelajahan koleksi

Mirip dengan koleksi, penjelajahan koleksi adalah respons lengkap yang memungkinkan pengguna men-scroll kartu opsi. Penjelajahan koleksi dirancang khusus untuk konten web dan membuka kartu yang dipilih di browser web (atau browser AMP jika semua kartu mendukung AMP).

Respons penjelajahan koleksi berisi minimal 2 dan maksimal 10 kotak. Pada perangkat yang mendukung layar, pengguna dapat menggeser ke atas atau ke bawah untuk men-scroll kartu sebelum memilih item.

Membuat penjelajahan koleksi

Saat membuat penjelajahan koleksi, pertimbangkan cara pengguna akan berinteraksi dengan permintaan ini. Setiap koleksi item akan membuka URL yang ditentukan, jadi berikan detail yang bermanfaat kepada pengguna.

Item penjelajahan koleksi memiliki karakteristik tampilan berikut:

  • Gambar (opsional)
    • Gambar dipaksa menjadi tinggi 128 dp x lebar 232 dp.
    • Jika rasio aspek gambar tidak sesuai dengan kotak pembatas gambar, gambar akan dipusatkan dengan batang di sisi atau atas dan bawah. Warna batang ditentukan oleh properti penjelajahan ImageFill koleksi.
    • Jika link gambar rusak, gambar placeholder akan digunakan sebagai gantinya.
  • Judul (wajib diisi)
    • Teks biasa, Markdown tidak didukung. Format yang sama dengan respons kaya kartu dasar digunakan.
    • Tinggi kartu diciutkan jika tidak ada judul yang ditentukan.
  • Deskripsi (opsional)
  • Footer (opsional)
    • Teks biasa; Markdown tidak didukung.

Properti

Jenis respons penjelajahan koleksi memiliki properti berikut:

Properti Jenis Persyaratan Deskripsi
item objek Wajib Mewakili item dalam koleksi yang dapat dipilih pengguna.
image_fill ImageFill Opsional Batas antara kartu dan penampung gambar yang akan digunakan saat rasio aspek gambar tidak cocok dengan rasio aspek penampung gambar.

Penjelajahan koleksi item memiliki properti berikut:

Properti Jenis Persyaratan Deskripsi
title string Wajib Judul teks biasa dari item koleksi.
description string Opsional Deskripsi item koleksi.
footer string Opsional Teks footer untuk item koleksi, yang ditampilkan di bawah deskripsi.
image Image Opsional Gambar ditampilkan untuk item koleksi.
openUriAction OpenUrl Wajib URI yang akan dibuka saat item koleksi dipilih.

Kode contoh

Contoh berikut menentukan konten perintah dalam kode webhook atau dalam respons webhook JSON. Namun, Anda juga dapat menentukan konten perintah di Actions Builder (sebagai YAML atau 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."
      }
    }
  }
}