Mendesain kartu atau dialog interaktif

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

Gunakan Card Builder untuk mendesain dan melihat pratinjau pesan kartu JSON untuk aplikasi Chat:

Prasyarat

Menambahkan tombol

Widget ButtonList menampilkan kumpulan tombol. Tombol dapat 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 untuk 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

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

Kode berikut 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 kumpulan 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 distandardisasi 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 sesuai perubahan, yaitu Actions yang berjalan saat terjadi perubahan 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 Menerima data formulir.

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

• Kotak centang
• Tombol pilihan
• Tombol
• Menu dropdown
• Menu pilihan ganda

Tambahkan kotak centang

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

Menambahkan tombol pilihan

Kode berikut menampilkan 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 bersifat profesional, pribadi, atau keduanya dengan widget SelectionInput yang menggunakan tombol akses:

Menambahkan menu drop-down

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

Menambahkan menu pilihan banyak

Berikut adalah dialog yang meminta pengguna 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 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 menghapus objek SectionItem, karena item pilihan ini bersumber secara dinamis dari Google Workspace.

Kode berikut menunjukkan menu pilihan beberapa pengguna Google Workspace. Untuk mengisi pengguna, input pilihan menetapkan commonDataSource ke USER:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Kode berikut menunjukkan menu multi-pilihan untuk ruang Chat. Untuk mengisi ruang, input pilihan menentukan kolom hostAppDataSource. Menu multi-pilihan juga menetapkan defaultToCurrentSpace ke true, yang menjadikan ruang saat ini menjadi pemilihan default di menu:

{
  "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 multi-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.

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

Kode berikut menampilkan menu item multi-pilihan 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:

{
  "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 melengkapi otomatis item yang mulai diketik oleh 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 otomatis item, Anda harus membuat fungsi yang mengkueri sumber data eksternal dan menampilkan item setiap kali pengguna mengetik di menu multi-pilihan. Fungsi 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 melengkapi otomatis item dari resource data eksternal. Menggunakan contoh sebelumnya, aplikasi Chat menyarankan item berdasarkan waktu fungsi getContacts dipicu:

/**
 * 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
            },
          ]
        }
      }
    }
  };
}

/**
 * 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
            },
          ]
        }
      }
    }
  };
}

Menambahkan kolom tempat pengguna dapat memasukkan teks

Widget TextInput menyediakan kolom tempat pengguna dapat memasukkan teks. Widget mendukung saran, yang membantu pengguna memasukkan data yang seragam, dan tindakan saat berubah, yaitu Actions yang berjalan saat terjadi perubahan dalam kolom input teks, seperti pengguna yang menambahkan atau menghapus teks.

Saat Anda perlu mengumpulkan data abstrak atau yang 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 Menerima data formulir.

Kode berikut menampilkan kartu yang terdiri dari tiga jenis widget DateTimePicker berbeda:

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 berisi sejumlah karakter tertentu.

Menyetel 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 suatu tindakan, semua widget dalam kartu akan diperlukan oleh tindakan ini.

Tetapkan tindakan all_widgets_are_required di multi-pilihan

{
  "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
              }
            ]
          }
        }
      ]
    }
  ]
}

Menyetel tindakan all_widgets_are_required di dateTimePicker

{
  "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"
          }
        }
      ]
    }
  ]
}

Setel tindakan all_widgets_are_required di menu drop-down

{
  "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
              }
            ]
          }
        }
      ]
    }
  ]
}

Menyetel validasi untuk widget input teks

Pada kolom validasi widget textInput, batas karakter dan jenis input dapat ditentukan untuk widget input teks ini.

Menetapkan batas karakter untuk widget input teks

{
  "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

{
  "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 atau kartu Google Chat menampilkan error, antarmuka Chat akan menampilkan pesan yang menyatakan "Terjadi error". 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 dan data log deskriptif akan tersedia untuk membantu Anda memperbaiki error saat logging error untuk aplikasi Chat diaktifkan. Untuk mendapatkan bantuan dalam melihat, melakukan proses debug, dan memperbaiki error, lihat Memecahkan masalah dan memperbaiki error Google Chat.

Topik terkait

• ButtonList
• Button
• Color
• knownIcon
• SelectionInput
• TextInput
• Widget DateTimePicker