Mengonversi aplikasi Google Chat interaktif menjadi add-on Google Workspace

Jika Anda telah membuat dan memublikasikan aplikasi Google Chat yang menggunakan peristiwa interaksi Google Chat API, seperti yang didasarkan pada panduan memulai aplikasi Google Chat, halaman ini menunjukkan cara mengonversinya menjadi add-on Google Workspace yang memperluas Google Chat.

Dengan mengonversi, aplikasi Google Chat Anda dapat menggunakan framework add-on Google Workspace, sehingga membuka kemungkinan baru untuk integrasi dan fitur dalam Google Chat dan di seluruh Google Workspace. Misalnya, alih-alih dua distribusi—satu aplikasi Google Chat dan satu add-on Google Workspace—Anda dapat mendistribusikan satu add-on Google Workspace melalui Google Workspace Marketplace yang memperluas aplikasi Chat bersama dengan aplikasi host Google Workspace lainnya, seperti Gmail, Kalender, dan Dokumen.

Batasan

Sebelum memulai konversi, tinjau Batasan add-on Google Workspace yang memperluas Google Chat untuk memastikan aplikasi Google Chat Anda dapat dikonversi tanpa kehilangan fungsi penting.

Langkah 1: Salin kode aplikasi Google Chat yang ada

Proses konversi memerlukan perubahan kode. Untuk menghindari pengaruh pada aplikasi Google Chat aktif Anda, buat dan kerjakan salinan kode Anda.

Apps Script

  1. Buka project Google Apps Script aplikasi Google Chat yang sudah ada.
  2. Di sebelah kiri, klik Ringkasan .
  3. Di sebelah kanan, klik Buat salinan .
  4. Di sebelah kiri, klik Project Settings .
  5. Di bagian Project Google Cloud, klik Ubah project.
  6. Masukkan nomor project yang sama yang terkait dengan project aplikasi Google Chat yang ada.
  7. Klik Set project.

HTTP

Buat fork atau salinan codebase yang ada dan deploy sebagai layanan baru, terpisah dari aplikasi Google Chat aktif Anda.

Jika aplikasi Anda di-deploy di Google Cloud dan mengandalkan fitur yang terkait dengan project Google Cloud (misalnya, identitas App Engine default), kode baru harus di-deploy di layanan yang terkait dengan project aplikasi Google Chat yang ada.

Langkah 2: Ubah kode yang disalin

Add-on Google Workspace yang memperluas Google Chat menggunakan struktur permintaan dan respons yang berbeda dibandingkan dengan aplikasi Google Chat yang dibuat dengan peristiwa interaksi Chat API. Anda harus memperbarui kode untuk menggunakan add-on Google Workspace EventObject alih-alih Event Google Chat API untuk permintaan dan respons. Gunakan Panduan konversi kode untuk mengubah kode Anda.

Langkah 3: Aktifkan konfigurasi add-on Google Workspace untuk pengguna uji coba

Gunakan konsol Google Cloud untuk mengonfigurasi setelan add-on Google Workspace untuk aplikasi Google Chat Anda:

  1. Buka halaman konfigurasi Google Chat API di konsol Google Cloud.

    Buka halaman konfigurasi Google Chat API

  2. Di bagian Fitur Interaktif, klik Konversi menjadi add-on.

  3. Aktifkan Turn on add-on configuration settings.

  4. Di bagian Visibilitas, tambahkan alamat email pengguna pengujian Anda.

  5. Jika perlu, perbarui Setelan Koneksi dengan URL endpoint deployment atau ID deployment Apps Script dari kode aplikasi Google Chat yang disalin dan diubah dari Langkah 2.

  6. Klik Simpan dan uji.

Langkah 4: Uji aplikasi yang dikonversi

Uji fungsi add-on Google Workspace secara menyeluruh menggunakan akun pengguna uji coba yang dikonfigurasi di Langkah 3. Verifikasi semua fitur dan interaksi.

Langkah 5: Selesaikan konversi untuk semua pengguna

Setelah Anda memverifikasi bahwa add-on Google Workspace yang dikonversi berfungsi dengan benar, Anda dapat menyediakannya untuk semua pengguna.

  1. Buka halaman konfigurasi Google Chat API di konsol Google Cloud.

    Buka halaman konfigurasi Google Chat API

  2. Di bagian Fitur Interaktif, klik Konversi ke add-on. Panel samping akan terbuka.

  3. Di panel samping, klik Konversi menjadi add-on.

  4. Ketik Project ID Anda, lalu klik Convert.

Aplikasi Google Chat Anda kini menjadi add-on Google Workspace yang memperluas Google Chat.

Opsional: Membersihkan atau membebaskan resource Google Cloud yang tidak digunakan

Secara opsional, setelah mengonversi aplikasi Google Chat Anda menjadi add-on Google Workspace, untuk menghindari tagihan ke akun Google Cloud Anda atas resource yang digunakan oleh aplikasi Google Chat yang tidak lagi digunakan, pertimbangkan untuk menonaktifkannya.

Panduan konversi kode

Bagian ini menjelaskan pemetaan antara format interaksi Google Chat API Event dan format EventObject add-on Google Workspace.

Pemetaan permintaan

Tabel berikut menunjukkan cara kolom di Google Chat API Event dipetakan ke kolom yang sesuai di add-on Google Workspace EventObject.

Kolom interaksi Event Google Chat API Kolom EventObject add-on Google Workspace Catatan
action.actionMethodName T/A Untuk interaksi kartu, nama metode dapat diteruskan sebagai parameter di commonEventObject.parameters. Lihat Membuka dialog awal.
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Tersedia dalam berbagai payload, bergantung pada jenis peristiwanya.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Tersedia dalam berbagai payload, bergantung pada jenis peristiwanya.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Tersedia dalam berbagai payload, bergantung pada jenis peristiwanya.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Tersedia dalam berbagai payload, bergantung pada jenis peristiwanya.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 Tersedia dalam berbagai payload, bergantung pada jenis peristiwanya.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Tersedia dalam berbagai payload, bergantung pada jenis peristiwanya.
token T/A Verifikasi ditangani secara berbeda, lihat Meminta Verifikasi untuk Aplikasi HTTP.
type T/A Jenis peristiwa dapat disimpulkan dari trigger.
user chat.user

Pemetaan permintaan berdasarkan kasus penggunaan

Tabel berikut menunjukkan perbedaan payload permintaan untuk kasus penggunaan umum antara aplikasi Google Chat yang dibuat dengan peristiwa interaksi Chat API dan add-on Google Workspace yang memperluas Google Chat.

Kasus Penggunaan Interaksi Chat API Event Payload Payload add-on Google Workspace EventObject
Aplikasi ditambahkan ke ruang 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Menghapus aplikasi dari ruang 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
Pengguna @menyebut aplikasi 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
Pengguna menyebutkan aplikasi untuk menambahkannya ke ruang Anda perlu menangani satu permintaan dari Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Anda harus menangani dua permintaan dari Google Chat.

Permintaan pertama:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Permintaan kedua:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Perintah garis miring 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Perintah garis miring untuk menambahkan aplikasi ke ruang Anda perlu menangani satu permintaan dari Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Anda harus menangani dua permintaan dari Google Chat.

Permintaan pertama:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Permintaan kedua:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Pengguna mengklik tombol pada kartu atau dialog 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

Untuk peristiwa dialog, common.formInputs berisi nilai widget. Contoh Google Apps Script:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

Untuk peristiwa dialog, commonEventObject.formInputs berisi nilai widget. Contoh Google Apps Script:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
Pengguna mengirimkan informasi di kartu beranda aplikasi 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
Pengguna memanggil perintah aplikasi menggunakan perintah cepat 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Pratinjau link 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
Pengguna memperbarui widget dalam pesan kartu atau dialog 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Pemetaan respons menurut kasus penggunaan

Add-on Google Workspace yang memperluas Google Chat menampilkan tindakan, bukan objek Message. Tabel berikut memetakan jenis respons Message Google Chat API ke tindakan add-on Google Workspace yang setara.

Kasus Penggunaan Respons Message Google Chat API Respons tindakan Chat add-on Google Workspace
Membuat pesan di ruang yang dipanggil 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse bersifat opsional. Untuk mempelajari lebih lanjut, lihat Merespons perintah garis miring.

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Untuk mempelajari lebih lanjut, lihat Mengirim pesan.
Memperbarui pesan 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Untuk mempelajari lebih lanjut, lihat Memperbarui pesan (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Untuk mempelajari lebih lanjut, lihat Memperbarui pesan (add-on).
Pratinjau link 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Untuk mempelajari lebih lanjut, lihat Melihat pratinjau link (Chat).

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

Untuk mempelajari lebih lanjut, lihat Melihat pratinjau link(add-on).
Membuka dialog awal 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Untuk mempelajari lebih lanjut, lihat Membuka dialog (Chat).

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
Kartu yang Anda kirim dapat berisi widget dengan tindakan onClick. Untuk add-on Google Workspace HTTP, konfigurasi tindakan ini untuk memanggil endpoint fungsi: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Untuk mempelajari lebih lanjut, lihat Membuka dialog (add-on).
Menutup dialog 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Untuk mempelajari lebih lanjut, lihat Menutup dialog (Chat).

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

Untuk mempelajari lebih lanjut, lihat Menutup dialog (add-on).
Menghubungkan ke sistem eksternal (Minta konfigurasi) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Untuk mempelajari lebih lanjut, lihat Menghubungkan ke sistem eksternal.

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

Untuk mempelajari lebih lanjut, lihat Menghubungkan add-on Google Workspace ke layanan pihak ketiga.
Item pelengkapan otomatis pada widget interaktif 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Untuk mempelajari lebih lanjut, lihat Menambahkan menu multiselect.

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Untuk mempelajari lebih lanjut, lihat Mengumpulkan dan memproses informasi dari pengguna Google Chat.

Menangani interaksi kartu pada pesan yang dibuat sebelum konversi

Saat Anda mengonversi aplikasi Google Chat HTTP menjadi add-on Google Workspace, interaksi kartu pada pesan yang dibuat sebelum konversi memerlukan penanganan khusus. Add-on Google Workspace menggunakan URL HTTP lengkap untuk action.function kartu, sedangkan aplikasi Google Chat yang dibuat dengan peristiwa interaksi Google Chat API menggunakan nama fungsi. Tabel berikut merangkum perbedaan ini.

Aplikasi Google Chat yang dibuat dengan peristiwa interaksi Google Chat API Add-on Google Workspace yang memperluas Google Chat
Konfigurasi Anda mengonfigurasi satu endpoint untuk semua peristiwa di konsol Google Cloud. Saat menerapkan interaksi kartu, action kartu hanya berisi nama fungsi yang akan dieksekusi. Endpoint HTTP umum dipanggil untuk peristiwa klik kartu.

Untuk mempelajari lebih lanjut, lihat Membuka dialog (Chat).



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 Anda dapat secara opsional mengonfigurasi endpoint per peristiwa di Konsol Google Cloud, tetapi ini tidak mencakup peristiwa klik kartu. Saat menerapkan interaksi kartu, action kartu harus berisi URL lengkap endpoint HTTP yang akan dipanggil. Anda dapat menetapkan endpoint HTTP unik per tombol, atau menggunakan endpoint umum dan meneruskan tindakan sebagai parameter di action.parameters.

Untuk mempelajari lebih lanjut, lihat Membuka dialog (add-on).



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Untuk memastikan interaksi kartu berfungsi untuk pesan yang dibuat sebelum konversi, konfigurasi URL Interaksi Kartu di halaman konfigurasi Google Chat API.

URL ini hanya digunakan untuk interaksi pada pesan yang dibuat sebelum Anda mengonversi aplikasi. Saat pengguna berinteraksi dengan salah satu pesan ini, nilai action.function asli diteruskan sebagai parameter yang disebut __action_method_name__.

Contoh: Klik kartu

Jika Anda mengonfigurasi URL Interaksi Kartu sebagai https://.../card-interaction-handler, dan pengguna mengklik kartu pada pesan historis dengan tindakan berikut:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Peristiwa dikirimkan ke URL Interaksi Kartu yang dikonfigurasi dengan format berikut:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Contoh: Menu pilihan multipel

Jika pengguna berinteraksi dengan menu pilihan ganda dengan sumber data eksternal:

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Peristiwa dikirimkan ke URL Interaksi Kartu yang dikonfigurasi dengan format berikut:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

Jika Anda mengaktifkan Gunakan URL endpoint HTTP umum untuk semua pemicu untuk pemicu HTTP, URL umum juga digunakan untuk peristiwa Tombol Diklik.

Memverifikasi permintaan untuk add-on Google Workspace HTTP yang memperluas Chat

Untuk aplikasi Google Chat berbasis HTTP, logika untuk memverifikasi bahwa permintaan berasal dari Google perlu diperbarui saat dikonversi menjadi add-on Google Workspace.

Perbedaan utama dalam verifikasi permintaan adalah:

Jenis Aplikasi Audiens yang Didukung Email Akun Layanan
Aplikasi Google Chat yang dibuat dengan peristiwa interaksi Google Chat API Nomor project chat@system.gserviceaccount.com
Add-on Google Workspace yang memperluas Google Chat Khusus endpoint HTTP Email akun layanan per project

Email akun layanan unik untuk add-on Google Workspace Anda dapat ditemukan di bagian Convert to Google Workspace add-ons di halaman konfigurasi Google Chat API di konsol Google Cloud.

Untuk memverifikasi permintaan di add-on Google Workspace yang diupgrade:

  1. Jika menggunakan fungsi Cloud Run, berikan peran roles/cloudfunctions.invoker ke akun layanan per add-on. Lihat Memberikan otorisasi akses dengan IAM.
  2. Perbarui kode verifikasi token Anda untuk menggunakan email akun layanan add-on Google Workspace guna memverifikasi tanda tangan token Bearer. Lihat Memvalidasi permintaan dari Google.