Halaman ini menjelaskan cara menambahkan widget dan elemen UI ke kartu agar pengguna dapat berinteraksi dengan aplikasi Google Chat Anda, seperti dengan mengklik tombol atau mengirimkan informasi.
Aplikasi Chat dapat menggunakan antarmuka Chat berikut untuk membuat kartu interaktif:
- Pesan yang berisi satu atau beberapa kartu.
- Halaman beranda, yang merupakan kartu yang muncul dari tab Beranda dalam pesan langsung dengan aplikasi Chat.
- Dialog, yang merupakan kartu yang terbuka di jendela baru dari pesan dan halaman beranda.
Saat pengguna berinteraksi dengan kartu, aplikasi Chat dapat menggunakan data yang mereka terima untuk memproses dan merespons dengan sesuai. Untuk mengetahui detailnya, lihat Mengumpulkan dan memproses informasi dari pengguna Google Chat.
Gunakan Card Builder untuk mendesain dan melihat pratinjau pesan dan antarmuka pengguna untuk aplikasi Chat:
Buka Pembuat KartuPrasyarat
Aplikasi Google Chat yang diaktifkan untuk fitur interaktif. Untuk membuat aplikasi Chat interaktif, selesaikan salah satu panduan memulai berikut berdasarkan arsitektur aplikasi yang ingin Anda gunakan:
- Layanan HTTP dengan Google Cloud Functions
- Google Apps Script
- Google Cloud Dialogflow CX
- Google Cloud Pub/Sub
Menambahkan tombol
Widget ButtonList
menampilkan serangkaian tombol. Tombol dapat menampilkan teks,
ikon, atau teks dan ikon sekaligus. Setiap
Button
mendukung
tindakan OnClick
yang terjadi saat pengguna mengklik tombol. Contoh:
- Buka hyperlink dengan
OpenLink
, untuk memberi pengguna informasi tambahan. - Jalankan
action
yang menjalankan fungsi kustom, seperti memanggil API.
Untuk aksesibilitas, tombol mendukung teks alternatif.
Menambahkan tombol yang menjalankan fungsi kustom
Berikut adalah kartu yang terdiri dari widget ButtonList
dengan dua tombol.
Satu tombol akan membuka dokumentasi developer Google Chat di tab baru. Tombol
lainnya menjalankan fungsi kustom yang disebut goToView()
dan meneruskan
parameter viewType="BIRD EYE VIEW"
.
Menambahkan tombol dengan gaya Desain Material
Berikut ini menampilkan kumpulan tombol dalam gaya tombol Desain Material yang berbeda.
Untuk menerapkan gaya Desain Material, jangan sertakan atribut 'color'.
Menambahkan tombol dengan warna kustom dan tombol yang dinonaktifkan
Anda dapat mencegah pengguna mengklik tombol dengan menetapkan "disabled": "true"
.
Berikut ini menampilkan kartu yang terdiri dari widget ButtonList
dengan dua
tombol. Satu tombol menggunakan
kolom Color
untuk menyesuaikan warna latar
belakang tombol. Tombol lainnya dinonaktifkan dengan kolom Disabled
, yang
mencegah pengguna mengklik tombol dan menjalankan fungsi.
Menambahkan tombol dengan ikon
Kode berikut menampilkan kartu yang terdiri dari widget ButtonList
dengan dua widget Button
ikon. Satu tombol menggunakan kolom
knownIcon
untuk menampilkan ikon email bawaan Google Chat. Tombol lainnya menggunakan kolom iconUrl
untuk menampilkan widget ikon kustom.
Menambahkan tombol dengan ikon dan teks
Berikut ini menampilkan kartu yang terdiri dari widget ButtonList
yang meminta
pengguna untuk mengirim email. Tombol pertama menampilkan ikon email dan
tombol kedua menampilkan teks. Pengguna dapat mengklik ikon atau tombol
teks untuk menjalankan fungsi sendEmail
.
Menyesuaikan tombol untuk bagian yang dapat diciutkan
Sesuaikan tombol kontrol yang menciutkan dan meluaskan bagian dalam kartu. Pilih dari berbagai ikon atau gambar untuk merepresentasikan konten bagian secara visual, sehingga memudahkan pengguna untuk memahami dan berinteraksi dengan informasi.
Menambahkan Menu Tambahan
Overflow menu
dapat digunakan di kartu Chat untuk menawarkan opsi dan tindakan tambahan. Hal ini memungkinkan
Anda menyertakan lebih banyak opsi tanpa mengacaukan antarmuka kartu, sehingga memastikan
desain yang rapi dan teratur.
Menambahkan daftar Chip
Widget ChipList
menyediakan cara yang serbaguna dan menarik secara visual untuk menampilkan informasi.
Gunakan daftar chip untuk merepresentasikan tag, kategori, atau data relevan lainnya, sehingga
memudahkan pengguna untuk membuka dan berinteraksi dengan konten Anda.
Mengumpulkan informasi dari pengguna
Bagian ini menjelaskan cara menambahkan widget yang mengumpulkan informasi, seperti teks atau pilihan.
Untuk mempelajari cara memproses input pengguna, lihat Mengumpulkan dan memproses informasi dari pengguna Google Chat.
Mengumpulkan teks
Widget TextInput
menyediakan kolom tempat pengguna dapat memasukkan teks. Widget
ini mendukung saran, yang membantu pengguna memasukkan data seragam, dan tindakan
saat perubahan, yaitu
Actions
yang berjalan saat perubahan terjadi di kolom input teks, seperti pengguna menambahkan atau
menghapus teks.
Jika Anda perlu mengumpulkan data abstrak atau tidak diketahui dari pengguna, gunakan widget
TextInput
ini. Untuk mengumpulkan data yang ditentukan dari pengguna, gunakan widget
SelectionInput
sebagai gantinya.
Berikut adalah kartu yang terdiri dari widget TextInput
:
Mengumpulkan tanggal atau waktu
Widget DateTimePicker
memungkinkan pengguna memasukkan tanggal, waktu, atau tanggal dan
waktu. Atau, pengguna dapat menggunakan pemilih untuk memilih tanggal dan waktu. Jika pengguna memasukkan
tanggal atau waktu yang tidak valid, pemilih akan menampilkan error yang meminta pengguna memasukkan
informasi dengan benar.
Berikut ini menampilkan kartu yang terdiri dari tiga jenis widget
DateTimePicker
yang berbeda:
Mengizinkan pengguna memilih item
Widget SelectionInput
menyediakan serangkaian item yang dapat dipilih, seperti kotak centang, tombol pilihan, tombol,
atau menu drop-down. Anda dapat menggunakan widget ini
untuk mengumpulkan data yang ditentukan dan standar dari pengguna. Untuk mengumpulkan data yang tidak ditentukan
dari pengguna, gunakan widget TextInput
.
Widget SelectionInput
mendukung saran, yang membantu pengguna memasukkan data
seragam, dan tindakan saat perubahan, yaitu
Actions
yang berjalan saat perubahan terjadi di kolom input pilihan, seperti pengguna
memilih atau membatalkan pilihan item.
Aplikasi chat dapat menerima dan memproses nilai item yang dipilih. Untuk mengetahui detail tentang cara menggunakan input formulir, lihat Memproses informasi yang dimasukkan oleh pengguna.
Bagian ini memberikan contoh kartu yang menggunakan widget SelectionInput
.
Contoh menggunakan berbagai jenis input bagian:
Menambahkan kotak centang
Berikut ini menampilkan kartu yang meminta pengguna untuk menentukan apakah
kontak bersifat profesional, pribadi, atau keduanya, dengan widget SelectionInput
yang
menggunakan kotak centang:
Menambahkan tombol pilihan
Berikut ini menampilkan kartu yang meminta pengguna untuk menentukan apakah
kontak bersifat profesional atau pribadi dengan widget SelectionInput
yang menggunakan
tombol pilihan:
Menambahkan tombol
Berikut ini menampilkan kartu yang meminta pengguna untuk menentukan apakah
kontak bersifat profesional, pribadi, atau keduanya dengan widget SelectionInput
yang
menggunakan tombol:
Menambahkan menu drop-down
Berikut ini menampilkan kartu yang meminta pengguna untuk menentukan apakah
kontak bersifat profesional atau pribadi dengan widget SelectionInput
yang menggunakan
menu drop-down:
Menambahkan menu multi-pilih
Berikut ini menampilkan kartu yang meminta pengguna untuk memilih kontak dari menu multi-pilih:
Anda dapat mengisi item untuk menu multi-pilih dari sumber data berikut di Google Workspace:
- Pengguna Google Workspace: Anda hanya dapat mengisi pengguna dalam organisasi Google Workspace yang sama.
- Ruang Chat: Pengguna yang memasukkan item di menu multipilih hanya dapat melihat dan memilih ruang yang menjadi bagiannya dalam organisasi Google Workspace.
Untuk menggunakan sumber data Google Workspace, tentukan
kolom
platformDataSource
. Tidak seperti jenis input pilihan lainnya, Anda menghilangkan objek SectionItem
, karena item pilihan ini bersumber secara dinamis dari Google Workspace.
Kode berikut menampilkan menu multi-pilih pengguna Google Workspace.
Untuk mengisi pengguna, input pilihan menetapkan commonDataSource
ke USER
:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
Kode berikut menunjukkan menu multi-pilih ruang Chat. Untuk mengisi ruang, input pilihan menentukan
kolom hostAppDataSource
. Menu multi-pilih juga menetapkan
defaultToCurrentSpace
ke true
, yang menjadikan ruang saat ini sebagai pilihan
default di menu:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Menu multipilih juga dapat mengisi item dari sumber data pihak ketiga atau eksternal. Misalnya, Anda dapat menggunakan menu multipilih untuk membantu pengguna memilih dari daftar prospek penjualan dari sistem pengelolaan hubungan pelanggan (CRM).
Untuk menggunakan sumber data eksternal, Anda menggunakan kolom externalDataSource
untuk menentukan fungsi yang menampilkan item dari sumber data.
Untuk mengurangi permintaan ke sumber data eksternal, Anda dapat menyertakan
item yang disarankan yang muncul di menu multipilih sebelum pengguna mengetik
menu. Misalnya, Anda dapat mengisi kontak yang baru-baru ini ditelusuri untuk
pengguna. Untuk mengisi item yang disarankan dari sumber data eksternal, tentukan objek
SelectionItem
.
Kode berikut menampilkan menu multi-pilih item dari
kumpulan kontak eksternal untuk pengguna. Menu menampilkan satu kontak secara default
dan menjalankan fungsi getContacts
untuk mengambil dan mengisi item dari
sumber data eksternal:
Node.js
Python
Java
Apps Script
Untuk sumber data eksternal, Anda juga dapat melengkapi item secara otomatis yang mulai
diketik pengguna di menu multipilih. Misalnya, jika pengguna mulai mengetik Atl
untuk
menu yang mengisi kota di Amerika Serikat, aplikasi Chat
Anda dapat menyarankan Atlanta
secara otomatis sebelum pengguna
selesai mengetik. Anda dapat melakukan pelengkapan otomatis hingga 100 item.
Untuk mengisi otomatis item, Anda membuat fungsi yang membuat kueri sumber data eksternal dan menampilkan item setiap kali pengguna mengetik di menu multipilih. Fungsi ini harus melakukan hal berikut:
- Meneruskan objek peristiwa yang merepresentasikan interaksi pengguna dengan menu.
- Identifikasi bahwa nilai
invokedFunction
peristiwa interaksi cocok dengan fungsi dari kolomexternalDataSource
. - Jika fungsi cocok, tampilkan item yang disarankan dari sumber data
eksternal. Untuk menyarankan item berdasarkan apa yang diketik pengguna, dapatkan nilai untuk
kunci
autocomplete_widget_query
. Nilai ini mewakili apa yang diketik pengguna di menu.
Kode berikut melengkapi item dari resource data eksternal. Dengan menggunakan
contoh sebelumnya, aplikasi Chat menyarankan item berdasarkan
saat fungsi getContacts
dipicu:
Node.js
Python
Java
Apps Script
Memvalidasi data yang dimasukkan ke kartu
Halaman ini menjelaskan cara memvalidasi data yang dimasukkan ke action
dan widget kartu.
Misalnya, Anda dapat memvalidasi bahwa kolom input teks memiliki teks yang dimasukkan oleh
pengguna, atau bahwa kolom tersebut berisi jumlah karakter tertentu.
Menetapkan widget yang diperlukan untuk tindakan
Sebagai bagian dari action
kartu,
tambahkan nama widget yang diperlukan tindakan ke daftar requiredWidgets
-nya.
Jika widget yang tercantum di sini tidak memiliki nilai saat tindakan ini dipanggil, pengiriman tindakan formulir akan dibatalkan.
Jika "all_widgets_are_required": "true"
ditetapkan untuk tindakan, semua widget
di kartu diperlukan oleh tindakan ini.
Menetapkan tindakan all_widgets_are_required
dalam multi-pilihan
JSON
{
"sections": [
{
"header": "Select contacts",
"widgets": [
{
"selectionInput": {
"type": "MULTI_SELECT",
"label": "Selected contacts",
"name": "contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"value": "contact-1",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 1",
"bottomText": "Contact one description",
"selected": false
},
{
"value": "contact-2",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 2",
"bottomText": "Contact two description",
"selected": false
},
{
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 3",
"bottomText": "Contact three description",
"selected": false
},
{
"value": "contact-4",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 4",
"bottomText": "Contact four description",
"selected": false
},
{
"value": "contact-5",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 5",
"bottomText": "Contact five description",
"selected": false
}
]
}
}
]
}
]
}
Menetapkan tindakan all_widgets_are_required
di dateTimePicker
JSON
{
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "A datetime picker widget with both date and time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_and_time",
"label": "meeting",
"type": "DATE_AND_TIME"
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just date:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_only",
"label": "Choose a date",
"type": "DATE_ONLY",
"onChangeAction":{
"all_widgets_are_required": true
}
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_time_only",
"label": "Select a time",
"type": "TIME_ONLY"
}
}
]
}
]
}
Menetapkan tindakan all_widgets_are_required
di menu drop-down
JSON
{
"sections": [
{
"header": "Section Header",
"collapsible": true,
"uncollapsibleWidgetsCount": 1,
"widgets": [
{
"selectionInput": {
"name": "location",
"label": "Select Color",
"type": "DROPDOWN",
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"text": "Red",
"value": "red",
"selected": false
},
{
"text": "Green",
"value": "green",
"selected": false
},
{
"text": "White",
"value": "white",
"selected": false
},
{
"text": "Blue",
"value": "blue",
"selected": false
},
{
"text": "Black",
"value": "black",
"selected": false
}
]
}
}
]
}
]
}
Menetapkan validasi untuk widget input teks
Di kolom validasi widget textInput
, kolom ini dapat menentukan batas karakter dan jenis input untuk widget input teks ini.
Menetapkan batas karakter untuk widget input teks
JSON
{
"sections": [
{
"header": "Tell us about yourself",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "favoriteColor",
"label": "Favorite color",
"type": "SINGLE_LINE",
"validation": {"character_limit":15},
"onChangeAction":{
"all_widgets_are_required": true
}
}
}
]
}
]
}
Menetapkan jenis input untuk widget input teks
JSON
{
"sections": [
{
"header": "Validate text inputs by input types",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "mailing_address",
"label": "Please enter a valid email address",
"type": "SINGLE_LINE",
"validation": {
"input_type": "EMAIL"
},
"onChangeAction": {
"all_widgets_are_required": true
}
}
},
{
"textInput": {
"name": "validate_integer",
"label": "Please enter a number",
"type": "SINGLE_LINE",
"validation": {
"input_type": "INTEGER"
}
}
},
{
"textInput": {
"name": "validate_float",
"label": "Please enter a number with a decimal",
"type": "SINGLE_LINE",
"validation": {
"input_type": "FLOAT"
}
}
}
]
}
]
}
Memecahkan masalah
Saat aplikasi Google Chat atau kartu menampilkan error, antarmuka Chat akan menampilkan pesan yang bertuliskan "Terjadi masalah". atau "Tidak dapat memproses permintaan Anda". Terkadang UI Chat tidak menampilkan pesan error, tetapi aplikasi atau kartu Chat menghasilkan hasil yang tidak terduga; misalnya, pesan kartu mungkin tidak muncul.
Meskipun pesan error mungkin tidak ditampilkan di UI Chat, pesan error deskriptif dan data log tersedia untuk membantu Anda memperbaiki error saat logging error untuk aplikasi Chat diaktifkan. Untuk mendapatkan bantuan dalam melihat, men-debug, dan memperbaiki error, lihat Memecahkan masalah dan memperbaiki error Google Chat.