Membuka dialog interaktif

Halaman ini menjelaskan cara aplikasi Google Chat dapat membuka dialog untuk menampilkan antarmuka pengguna (UI) dan merespons pengguna.

Di Google Chat, add-on akan muncul kepada pengguna sebagai aplikasi Google Chat. Untuk mempelajari lebih lanjut, lihat Ringkasan memperluas Google Chat.

Dialog adalah antarmuka berbasis kartu dengan jendela yang terbuka dari ruang atau pesan Chat. Dialog dan kontennya hanya dapat dilihat oleh pengguna yang membukanya.

Aplikasi Chat dapat menggunakan dialog untuk meminta dan mengumpulkan informasi dari pengguna Chat, termasuk formulir multi-langkah. Untuk mengetahui detail selengkapnya tentang cara membuat input formulir, lihat Mengumpulkan dan memproses informasi dari pengguna.

Prasyarat

Node.js

Add-on Google Workspace yang memperluas Google Chat. Untuk membuatnya, selesaikan panduan memulai HTTP.

Apps Script

Add-on Google Workspace yang memperluas Google Chat. Untuk membuatnya, selesaikan panduan memulai Apps Script.

Membuka dialog

Dialog yang menampilkan berbagai widget.
Gambar 1: Aplikasi Chat yang membuka dialog untuk mengumpulkan informasi kontak.

Bagian ini menjelaskan cara merespons dan menyiapkan dialog dengan melakukan hal berikut:

  1. Memicu permintaan dialog dari interaksi pengguna.
  2. Tangani permintaan dengan menampilkan dan membuka dialog.
  3. Setelah pengguna mengirimkan informasi, proses pengiriman dengan menutup dialog atau menampilkan dialog lain.

Memicu permintaan dialog

Aplikasi Chat hanya dapat membuka dialog untuk merespons interaksi pengguna, seperti perintah garis miring atau klik tombol dari pesan dalam kartu.

Untuk merespons pengguna dengan dialog, aplikasi Chat harus membuat interaksi yang memicu permintaan dialog, seperti berikut:

  • Merespons perintah garis miring. Untuk memicu permintaan dari perintah garis miring, Anda harus mencentang kotak Membuka dialog saat mengonfigurasi perintah.
  • Merespons klik tombol dalam pesan, baik sebagai bagian dari kartu maupun di bagian bawah pesan. Untuk memicu permintaan dari tombol dalam pesan, Anda mengonfigurasi tindakan onClick tombol dengan menetapkan interaction-nya ke OPEN_DIALOG.
Tombol yang memicu dialog
Gambar 2: Aplikasi Chat mengirim pesan yang meminta pengguna untuk menggunakan perintah garis miring /addContact.
Pesan juga menyertakan tombol yang dapat diklik pengguna untuk memicu perintah.

JSON berikut menunjukkan cara memicu permintaan dialog dari tombol dalam pesan kartu. Untuk membuka dialog, tetapkan kolom onClick.action.interaction tombol ke OPEN_DIALOG:

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

Dengan BUTTON_TEXT adalah teks yang ditampilkan di tombol dan ACTION_FUNCTION adalah fungsi yang berjalan untuk membuka dialog awal.

Membuka dialog awal

Saat pengguna memicu permintaan dialog, aplikasi Chat Anda akan menerima objek peristiwa dengan payload yang menentukan bahwa objek dialogEventType sebagai REQUEST_DIALOG.

Untuk membuka dialog, aplikasi Chat Anda dapat merespons permintaan dengan menampilkan objek RenderActions dengan navigasi pushCard untuk menampilkan kartu. Kartu harus berisi elemen antarmuka pengguna (UI), termasuk satu atau beberapa widget sections[]. Untuk mengumpulkan informasi dari pengguna, Anda dapat menentukan widget input formulir dan widget tombol. Untuk mempelajari lebih lanjut cara mendesain input formulir, lihat Mengumpulkan dan memproses informasi dari pengguna.

JSON berikut menunjukkan cara aplikasi Chat menampilkan respons yang membuka dialog:

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

Dengan BUTTON_TEXT adalah teks yang ditampilkan di tombol (seperti Next atau Submit), WIDGETS mewakili satu atau beberapa widget input formulir, dan ACTION_FUNCTION adalah fungsi callback tindakan yang berjalan saat pengguna mengklik tombol.

Menangani pengiriman dialog

Saat pengguna mengklik tombol yang mengirimkan dialog, aplikasi Chat Anda akan menerima objek peristiwa dengan objek ButtonClickedPayload. Dalam payload, dialogEventType disetel ke SUBMIT_DIALOG.

Aplikasi Chat Anda harus menangani objek peristiwa dengan melakukan salah satu tindakan berikut:

  • Tampilkan dialog lain untuk mengisi kartu atau formulir lain.
  • Tutup dialog setelah memvalidasi data yang dikirimkan pengguna, dan jika perlu, kirim pesan konfirmasi.

Opsional: Menampilkan dialog lain

Setelah pengguna mengirimkan dialog awal, aplikasi Chat dapat menampilkan satu atau beberapa dialog tambahan untuk membantu pengguna meninjau informasi sebelum mengirimkan, menyelesaikan formulir multi-langkah, atau mengisi konten formulir secara dinamis.

Untuk memproses data yang dimasukkan pengguna, aplikasi Chat akan menangani data dalam objek commonEventObject.formInputs peristiwa. Untuk mempelajari lebih lanjut cara mengambil nilai dari widget input, lihat Mengumpulkan dan memproses informasi dari pengguna.

Untuk melacak data apa pun yang dimasukkan pengguna dari dialog awal, Anda harus menambahkan parameter ke tombol yang membuka dialog berikutnya. Untuk mengetahui detailnya, lihat Mentransfer data ke kartu lain.

Dalam contoh ini, aplikasi Chat membuka dialog awal yang mengarah ke dialog kedua untuk konfirmasi sebelum mengirimkan:

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

Apps Script

Contoh ini mengirim pesan kartu dengan menampilkan JSON kartu. Anda juga dapat menggunakan layanan kartu Apps Script. 

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

Dengan WIDGETS mewakili widget input formulir lainnya.

Tutup dialog

Saat pengguna mengklik tombol kirim pada dialog, aplikasi Chat Anda akan mengeksekusi tindakan terkait dan memberikan objek peristiwa dengan buttonClickedPayload yang ditetapkan ke hal berikut:

  • isDialogEvent adalah true.
  • dialogEventType adalah SUBMIT_DIALOG.

Aplikasi Chat akan menampilkan objek RenderActions dengan EndNavigation ditetapkan ke CLOSE_DIALOG.

Opsional: Menampilkan notifikasi

Saat menutup dialog, Anda juga dapat menampilkan notifikasi teks.

Untuk menampilkan notifikasi, tampilkan objek RenderActions dengan menetapkan kolom notification.

Contoh berikut memeriksa apakah parameter valid dan menutup dialog dengan notifikasi teks, bergantung pada hasilnya:

Node.js

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Apps Script

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Untuk mengetahui detail tentang meneruskan parameter di antara dialog, lihat Mentransfer data ke kartu lain.

Opsional: Mengirim pesan konfirmasi

Saat menutup dialog, Anda juga dapat mengirim pesan baru, atau memperbarui pesan yang sudah ada.

Untuk mengirim pesan baru, tampilkan objek DataActions dengan kolom CreateMessageAction yang ditetapkan dengan pesan baru. Misalnya, untuk menutup dialog dan mengirim pesan teks, tampilkan hal berikut:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

Untuk memperbarui pesan setelah pengguna mengirimkan dialog, tampilkan objek DataActions yang berisi salah satu tindakan berikut:

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.