Mendesain kartu atau dialog interaktif

Halaman ini menjelaskan cara menambahkan widget dan elemen UI ke pesan dialog atau kartu sehingga pengguna dapat berinteraksi dengan aplikasi Google Chat Anda, seperti dengan mengklik tombol atau mengirimkan informasi.


Desain dan pratinjau kartu dengan Pembuat Kartu.

Buka Pembuat Kartu

Prasyarat

  • Akun Google Workspace dengan akses ke Google Chat.
  • Aplikasi Chat yang dipublikasikan. Untuk mem-build aplikasi Chat, ikuti quickstart ini.
  • Menambahkan tombol

    Widget ButtonList menampilkan serangkaian tombol. Tombol bisa menampilkan teks, ikon, atau teks dan ikon. Setiap Button mendukung tindakan OnClick yang terjadi saat pengguna mengklik tombol. Contoh:

    • Buka hyperlink dengan OpenLink, untuk memberikan informasi tambahan kepada pengguna.
    • 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 warna khusus dan tombol yang dinonaktifkan

    Anda dapat mencegah pengguna mengklik tombol dengan menyetel "disabled": "true".

    Kode berikut 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

    Berikut adalah kartu yang terdiri dari widget ButtonList dengan dua ikon widget Button. 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.

    Menambahkan elemen UI yang dapat dipilih

    Widget SelectionInput menyediakan sekumpulan item yang dapat dipilih, seperti kotak centang, tombol pilihan, tombol akses, atau menu drop-down. Anda dapat menggunakan widget ini untuk mengumpulkan data yang telah ditentukan dan distandarisasi 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 atas perubahan, yaitu Actions yang dijalankan saat perubahan terjadi di kolom input pemilihan, 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 Menerima data formulir.

    Bagian ini memberikan contoh kartu yang menggunakan widget SelectionInput. Contoh tersebut menggunakan berbagai jenis input bagian:

    Menambahkan kotak centang

    Berikut adalah dialog yang meminta pengguna untuk menentukan apakah kontak adalah profesional, pribadi, atau keduanya, dengan widget SelectionInput yang menggunakan kotak centang:

    Menambahkan tombol pilihan

    Berikut adalah dialog yang meminta pengguna untuk menentukan apakah kontak bersifat profesional atau pribadi dengan widget SelectionInput yang menggunakan tombol pilihan:

    Menambahkan tombol

    Berikut adalah dialog yang meminta pengguna untuk menentukan apakah kontak adalah profesional, pribadi, atau keduanya dengan widget SelectionInput yang menggunakan tombol akses:

    Berikut adalah dialog yang meminta pengguna untuk menentukan apakah kontak bersifat profesional atau pribadi dengan widget SelectionInput yang menggunakan menu drop-down:

    Menambahkan menu multi-pilihan

    Berikut adalah dialog yang meminta pengguna untuk memilih kontak dari menu multi-pilihan:

    Menggunakan sumber data untuk menu dengan banyak pilihan

    Bagian berikut menjelaskan cara menggunakan menu multi-pilihan untuk mengisi data dari sumber dinamis, seperti aplikasi Google Workspace atau sumber data eksternal.

    Sumber data dari Google Workspace

    Anda dapat mengisi item untuk menu multi-pilihan dari sumber data berikut di Google Workspace:

    • Pengguna Google Workspace: Anda hanya dapat mengisi pengguna di dalam organisasi Google Workspace yang sama.
    • Ruang chat: Pengguna yang memasukkan item di menu multi-pilihan hanya dapat melihat dan memilih ruang tempat mereka berada dalam organisasi Google Workspace mereka.

    Untuk menggunakan sumber data Google Workspace, tentukan kolom platformDataSource. Tidak seperti jenis input pemilihan lainnya, Anda menghilangkan objek SectionItem, karena item pemilihan ini bersumber secara dinamis dari Google Workspace.

    Kode berikut menampilkan menu multi-pilihan pengguna Google Workspace. Untuk mengisi pengguna, input pemilihan 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-pilihan ruang Chat. Untuk mengisi ruang, input pemilihan menentukan kolom hostAppDataSource. Menu multi-pilihan juga menetapkan defaultToCurrentSpace ke true, yang membuat ruang saat ini menjadi pilihan default dalam menu:

    JSON

    {
      "selectionInput": {
        "name": "spaces",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 3,
        "multiSelectMinQueryLength": 1,
        "platformDataSource": {
          "hostAppDataSource": {
            "chatDataSource": {
              "spaceDataSource": {
                "defaultToCurrentSpace": true
              }
            }
          }
        }
      }
    }
    
    Sumber data di luar Google Workspace

    Menu multi-pilihan juga dapat mengisi item dari sumber data pihak ketiga atau eksternal. Misalnya, Anda dapat menggunakan menu beberapa pilihan untuk membantu pengguna memilih dari daftar prospek penjualan dari sistem pengelolaan hubungan pelanggan (CRM).

    Untuk menggunakan sumber data eksternal, gunakan kolom externalDataSource untuk menentukan fungsi yang menampilkan item dari sumber data tersebut.

    Untuk mengurangi permintaan ke sumber data eksternal, Anda dapat menyertakan item yang disarankan yang muncul di menu multi-pilihan sebelum pengguna mengetik menu. Misalnya, Anda dapat mengisi kontak pengguna yang baru saja ditelusuri. Untuk mengisi item yang disarankan dari sumber data eksternal, tentukan objek SelectionItem.

    Kode berikut menunjukkan menu multi-pilihan item dari kumpulan kontak eksternal untuk pengguna. Menu ini menampilkan satu kontak secara default dan menjalankan fungsi getContacts untuk mengambil serta mengisi item dari sumber data eksternal:

    JSON

    {
      "selectionInput": {
        "name": "contacts",
        "type": "MULTI_SELECT",
        "label": "Selected contacts",
        "multiSelectMaxSelectedItems": 5,
        "multiSelectMinQueryLength": 2,
        "externalDataSource": {
          "function": "getContacts"
        },
        "items": [
          {
            "text": "Contact 3",
            "value": "contact-3",
            "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
            "bottomText": "Contact three description",
            "selected": false
          }
        ]
      }
    }
    

    Untuk sumber data eksternal, Anda juga dapat otomatis melengkapi item yang mulai diketik pengguna di menu multi-pilihan. Misalnya, jika pengguna mulai mengetik Atl untuk menu yang mengisi kota-kota di Amerika Serikat, aplikasi Chat Anda dapat menyarankan Atlanta secara otomatis sebelum pengguna selesai mengetik. Anda dapat melengkapi otomatis hingga 100 item.

    Untuk melengkapi item secara otomatis, buat fungsi yang mengkueri sumber data eksternal dan menampilkan item setiap kali pengguna mengetik di menu multi-pilihan. 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 kolom externalDataSource.
    • Jika fungsi cocok, tampilkan item yang disarankan dari sumber data eksternal. Untuk menyarankan item berdasarkan jenis pengguna, dapatkan nilai untuk kunci autocomplete_widget_query. Nilai ini mewakili apa yang diketik pengguna di menu.

    Kode berikut akan melengkapi item secara otomatis dari resource data eksternal. Menggunakan contoh sebelumnya, aplikasi Chat menyarankan item berdasarkan kapan fungsi getContacts dipicu:

    Apps Script

    apps-script/selection-input/on-widget-update.gs
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              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
                },
              ]
            }
          }
        }
      };
    }
    

    Node.js

    node/selection-input/on-widget-update.js
    /**
     * Widget update event handler.
     *
     * @param {Object} event The event object from Chat API.
     * @return {Object} Response from the Chat app.
     */
    function onWidgetUpdate(event) {
      const actionName = event.common["invokedFunction"];
      if (actionName !== "getContacts") {
        return {};
      }
    
      return {
        actionResponse: {
          type: "UPDATE_WIDGET",
          updatedWidget: {
            suggestions: {
              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
                },
              ]
            }
          }
        }
      };
    }
    

    Tambahkan kolom tempat pengguna dapat memasukkan teks

    Widget TextInput menyediakan kolom tempat pengguna dapat memasukkan teks. Widget mendukung saran, yang membantu pengguna memasukkan data seragam, dan tindakan atas perubahan, yaitu Actions yang berjalan saat terjadi perubahan di kolom input teks, seperti pengguna yang 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.

    Untuk memproses teks yang dimasukkan pengguna, lihat Menerima data formulir.

    Berikut adalah kartu yang terdiri dari widget TextInput:

    Memungkinkan pengguna memilih tanggal dan 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, alat pilih akan menampilkan error yang meminta pengguna untuk memasukkan informasi dengan benar.

    Untuk memproses nilai tanggal dan waktu yang dimasukkan pengguna, lihat bagian Menerima data formulir.

    Berikut adalah kartu yang terdiri dari tiga jenis widget DateTimePicker yang berbeda:

    Memecahkan masalah

    Saat aplikasi atau kartu Google Chat menampilkan error, antarmuka Chat akan menampilkan pesan yang menyatakan "Terjadi masalah". atau "Tidak dapat memproses permintaan Anda". Terkadang UI Chat tidak menampilkan pesan error apa pun, tetapi aplikasi atau kartu Chat memberikan hasil yang tidak diharapkan; 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.