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:
- Dalam scene, tambahkan slot ke bagian Slot fill.
- 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.
- Centang kotak Call your webhook dan berikan nama pengendali peristiwa di webhook yang ingin Anda gunakan untuk respons pemilihan visual.
- Centang kotak Sendprompt.
- Dalam perintah, berikan konten JSON atau YAML yang sesuai berdasarkan respons pemilihan visual yang ingin Anda tampilkan.
- 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
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)
- Teks biasa, Markdown tidak didukung. Format yang sama dengan respons kaya kartu dasar digunakan.
- 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." } } } }