Mendesain kartu atau dialog interaktif

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

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

Membuka Card Builder

Prasyarat

  • Akun Google Workspace yang memiliki akses ke Google Chat.
  • Aplikasi Chat yang dipublikasikan. Untuk membangun Aplikasi Chat, ikuti ini panduan memulai.

    • Menambahkan tombol

    Tujuan Widget ButtonList menampilkan satu set tombol. Tombol dapat menampilkan teks, ikon, atau teks dan ikon. Masing-masing Button mendukung Tindakan OnClick yang terjadi ketika pengguna mengeklik tombol. Contoh:

    • Buka hyperlink dengan OpenLink, untuk memberikan informasi tambahan kepada pengguna.
    • Jalankan action yang menjalankan fungsi khusus, 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. Tujuan tombol lain menjalankan fungsi khusus 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 latar belakang tombol {i>color<i}. 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 ikon Widget Button. Satu tombol menggunakan knownIcon untuk menampilkan ikon email bawaan Google Chat. Tombol lainnya menggunakan atribut 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 teks untuk menjalankan fungsi sendEmail.

    Menambahkan elemen UI yang dapat dipilih

    Widget SelectionInput menyediakan seperangkat item yang dapat dipilih, seperti kotak centang, tombol pilihan, tombol, atau menu {i>drop-down.<i} Anda dapat menggunakan widget ini untuk mengumpulkan data yang telah didefinisikan dan distandarisasi dari pengguna. Untuk mengumpulkan data yang tidak terdefinisi dari pengguna, gunakan widget TextInput.

    Widget SelectionInput mendukung saran, yang membantu pengguna memasukkan kolom data, dan tindakan on-change, yaitu Actions yang berjalan saat terjadi perubahan dalam bidang input pilihan, seperti pengguna memilih atau membatalkan pilihan suatu 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 tersebut menggunakan jenis input bagian yang berbeda:

    Tambahkan kotak centang

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

    Menambahkan tombol

    Kode berikut menampilkan dialog yang meminta pengguna untuk menentukan apakah kontak bersifat profesional, pribadi, atau keduanya dengan widget SelectionInput yang menggunakan {i>switch<i}:

    Kode berikut menampilkan dialog yang meminta pengguna untuk menentukan apakah kontak profesional atau pribadi dengan widget SelectionInput yang menggunakan menu {i>drop-down<i}:

    Menambahkan menu pilihan banyak

    Hal berikut menampilkan dialog yang meminta pengguna memilih kontak dari menu pilihan ganda:

    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 data eksternal sumber.

    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 memasukkan item di kotak multi-pilihan hanya dapat melihat dan memilih ruang tempat mereka berada di dalamnya pengaturan Google Workspace Anda.

    Untuk menggunakan sumber data Google Workspace, Anda menentukan platformDataSource kolom tersebut. Tidak seperti jenis {i>input <i}pilihan lain, Anda menghilangkan SectionItem karena item pilihan ini bersumber secara dinamis dari Gemini untuk Google Workspace.

    Kode berikut menunjukkan menu pilihan beberapa 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-pilihan Chat spasi. Untuk mengisi ruang, input pilihan menentukan Kolom hostAppDataSource. Menu {i>multiselect<i} juga menetapkan defaultToCurrentSpace menjadi true, yang menjadikan ruang saat ini sebagai default pilihan di 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 data pihak ketiga atau eksternal sumber. 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 menu. Misalnya, Anda dapat mengisi kontak yang baru-baru ini ditelusuri untuk . Untuk mengisi item yang disarankan dari sumber data eksternal, tentukan SelectionItem objek terstruktur dalam jumlah besar.

    Kode berikut menampilkan menu item dengan beberapa pilihan dari sekumpulan kontak eksternal untuk pengguna. Menu 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 melengkapi otomatis item yang dimulai pengguna mengetik di menu pilihan banyak. Misalnya, jika pengguna mulai mengetik Atl untuk yang memenuhi berbagai kota di Amerika Serikat, Aplikasi Chat dapat menyarankan otomatis Atlanta sebelum pengguna selesai mengetik. Anda dapat melengkapi otomatis hingga 100 item.

    Untuk melengkapi item secara otomatis, Anda membuat fungsi yang mengkueri data eksternal mendapatkan sumber dan menampilkan item setiap kali pengguna mengetik di menu pilihan banyak. Tujuan harus melakukan hal berikut:

    • Meneruskan objek peristiwa yang merepresentasikan interaksi pengguna dengan menu.
    • Identifikasi bahwa peristiwa interaksi invokedFunction cocok dengan fungsi dari kolom externalDataSource.
    • Jika fungsi cocok, tampilkan item yang disarankan dari data eksternal sumber. Untuk menyarankan item berdasarkan apa yang diketik pengguna, dapatkan nilai untuk Tombol autocomplete_widget_query. Nilai ini mewakili apa yang diketik pengguna pada menu.

    Kode berikut melengkapi otomatis item dari resource data eksternal. Menggunakan contoh sebelumnya, aplikasi Chat menyarankan item berdasarkan saat 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
            },
          ]
        }
      }
    }
  };
}

    Menambahkan kolom tempat pengguna dapat memasukkan teks

    Widget TextInput menyediakan kolom tempat pengguna dapat memasukkan teks. Tujuan widget mendukung saran, yang membantu pengguna memasukkan data yang seragam, dan dapat berubah tambahan, yaitu Actions yang berjalan ketika terjadi perubahan di isian {i>input <i}teks, seperti pengguna menambahkan atau menghapus teks.

    Jika Anda perlu mengumpulkan data abstrak atau yang tidak diketahui dari pengguna, gunakan data ini Widget TextInput. Untuk mengumpulkan data yang ditentukan dari pengguna, gunakan SelectionInput widget ini.

    Untuk memproses teks yang dimasukkan pengguna, lihat Memproses informasi yang dimasukkan oleh pengguna.

    Berikut adalah kartu yang terdiri dari widget TextInput:

    Memungkinkan pengguna memilih tanggal dan waktu

    Tujuan Widget DateTimePicker memungkinkan pengguna memasukkan tanggal, waktu, atau tanggal dan waktu tertentu. 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 untuk memasukkan informasi dengan benar.

    Untuk memproses nilai tanggal dan waktu yang dimasukkan pengguna, lihat Memproses informasi yang dimasukkan oleh pengguna.

    Berikut ini menampilkan kartu yang terdiri dari tiga jenis informasi Widget DateTimePicker:

    Memvalidasi data yang dimasukkan ke kartu

    Halaman ini menjelaskan cara memvalidasi data yang dimasukkan ke action kartu dan widget. Misalnya, Anda dapat memvalidasi bahwa {i>field<i} {i>input <i}teks memiliki teks yang dimasukkan oleh pengguna, atau yang berisi sejumlah karakter tertentu.

    Menyetel widget yang diperlukan untuk tindakan

    Sebagai bagian dari action kartu, menambahkan nama widget yang diperlukan tindakan ke daftar requiredWidgets-nya.

    Jika widget yang tercantum di sini tidak memiliki nilai saat tindakan ini dipanggil, maka pengiriman tindakan formulir akan dibatalkan.

    Jika "all_widgets_are_required": "true" ditetapkan untuk suatu tindakan, maka semua widget pada kartu diperlukan oleh tindakan ini.

    Tetapkan tindakan all_widgets_are_required di 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
              }
            ]
          }
        }
      ]
    }
  ]
}

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

    Setel 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
              }
            ]
          }
        }
      ]
    }
  ]
}

    Menyetel validasi untuk widget input teks

    Di textInput tambahan, {i>widget<i}, dapat menentukan batas karakter dan jenis {i>input <i}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 menampilkan pesan yang bertuliskan "Terjadi masalah". atau "Tidak dapat memproses permintaan Anda". Terkadang UI Chat tidak menampilkan pesan error apa pun, tetapi aplikasi Chat atau memberikan hasil yang tidak diharapkan; misalnya, pesan kartu mungkin tidak akan 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 bantuan melihat, men-debug, dan memperbaiki error, melihat Memecahkan masalah dan memperbaiki error Google Chat.