Objek peristiwa

Halaman ini menguraikan struktur objek peristiwa add-on Google Workspace.

Objek peristiwa adalah struktur JSON yang dibuat secara otomatis dan diteruskan sebagai parameter untuk memicu atau memanggil balik fungsi saat pengguna berinteraksi dengan add-on. Objek peristiwa membawa informasi sisi klien tentang aplikasi host dan konteks saat ini ke fungsi callback sisi server add-on.

Add-on Google Workspace menggunakan objek peristiwa di tempat berikut:

• Pemicu halaman beranda. Setiap fungsi homepageTrigger yang Anda tentukan akan otomatis diteruskan objek peristiwa saat fungsi pemicu halaman beranda diaktifkan. Anda dapat menggunakan objek ini dalam fungsi pemicu halaman beranda untuk mengidentifikasi aplikasi host aktif, platform klien, lokalitas pengguna, dan informasi lainnya.

  Objek peristiwa yang dibuat saat pemicu halaman beranda diaktifkan tidak berisi semua kolom yang disertakan dalam dua kasus lainnya; kolom yang berkaitan dengan widget dan informasi kontekstual dihilangkan.

• Pemicu kontekstual. Setiap aplikasi host menyediakan kumpulan pemicu kontekstual yang berbeda yang diaktifkan saat pengguna memasuki konteks tertentu. Contoh:

  • Gmail menyediakan pemicu kontekstual saat pengguna membuka pesan dan pemicu lainnya saat pengguna menulis pesan.
  • Google Kalender menyediakan pemicu kontekstual saat pengguna membuka acara.
  • Google Drive menyediakan pemicu kontekstual saat pengguna memilih file Drive.

  Saat pemicu kontekstual diaktifkan, aplikasi host akan memanggil runFunction yang sesuai yang tercantum dalam manifes add-on, dengan meneruskan objek peristiwa sebagai parameter. Objek peristiwa yang dibuat saat pemicu kontekstual diaktifkan berisi semua kolom yang disertakan dalam objek peristiwa pemicu halaman beranda, ditambah kolom yang berisi informasi kontekstual.

• Tindakan widget. Objek peristiwa juga digunakan untuk memberikan interaktivitas widget, menggunakan model tindakan yang sama dengan yang digunakan add-on Gmail. Add-on Google Workspace menggunakan semua fungsi pengendali widget, objek Action, dan respons tindakan yang sama. Namun, di add-on Google Workspace, objek peristiwa tindakan menyertakan lebih banyak informasi yang dapat ditindaklanjuti oleh fungsi callback.

  Objek peristiwa yang dibuat sebagai hasil dari tindakan widget berisi semua kolom yang disertakan dalam objek peristiwa pemicu kontekstual, ditambah kolom yang berisi informasi widget.

• Pratinjau pemicu link. Di Google Dokumen, Spreadsheet, dan Slide, Anda dapat mengonfigurasi pratinjau link untuk layanan pihak ketiga berdasarkan pola URL tertentu. Saat pengguna berinteraksi dengan link yang memenuhi pola, linkPreviewTriggers akan diaktifkan dan objek peristiwa yang berisi link akan diteruskan ke fungsi callback pemicu. Add-on Anda dapat menggunakan objek peristiwa ini untuk membuat chip dan kartu pintar yang menampilkan informasi tentang link dalam aplikasi host. Anda juga dapat mem-build tindakan widget agar pengguna dapat berinteraksi dengan kartu pratinjau dan kontennya.

• Pemicu aplikasi Google Chat (Pratinjau Developer). Di Google Chat, add-on Anda akan muncul kepada pengguna sebagai aplikasi Chat, dan pengguna dapat berinteraksi dengannya dengan menambahkannya ke ruang, mengirim pesan, menggunakan perintah garis miring, dan lainnya. Untuk mem-build fitur interaktif, Anda menyiapkan dan menggunakan berbagai pemicu aplikasi Chat. Setiap pemicu mengirimkan payload objek peristiwa yang berbeda yang membantu Anda memproses atau merespons setiap jenis interaksi.

Struktur objek peristiwa

Tabel berikut menjelaskan struktur tingkat atas objek peristiwa add-on Google Workspace. Struktur objek peristiwa mencakup kolom level atas commonEventObject untuk informasi yang tidak bergantung pada host. Setiap objek peristiwa juga dapat memiliki salah satu kolom tingkat teratas khusus host berikut, yang ditentukan oleh aplikasi host aktif: gmailEventObject, calendarEventObject, atau driveEventObject.

Untuk kompatibilitas mundur, objek peristiwa add-on Google Workspace juga menyertakan semua kolom asli yang digunakan dalam objek peristiwa tindakan add-on Gmail. Kolom ini tercantum dalam tabel di bawah di bagian "Kolom add-on Gmail asli"; informasi dalam kolom ini direproduksi dalam struktur objek baru.

Objek peristiwa umum

Objek peristiwa umum adalah bagian dari keseluruhan objek peristiwa yang membawa informasi umum yang tidak bergantung pada host ke add-on dari klien pengguna. Informasi ini mencakup detail seperti lokalitas, aplikasi host, dan platform pengguna.

Selain pemicu halaman beranda dan kontekstual, add-on membuat dan meneruskan objek peristiwa ke fungsi callback tindakan saat pengguna berinteraksi dengan widget. Fungsi callback add-on Anda dapat membuat kueri objek peristiwa umum untuk menentukan konten widget yang terbuka di klien pengguna. Misalnya, add-on Anda dapat menemukan teks yang dimasukkan pengguna ke dalam widget TextInput di objek eventObject.commentEventObject.formInputs.

Input formulir pemilih tanggal/waktu

Fungsi callback tindakan dapat menerima nilai widget saat ini di kolom commonEventObject.formInputs. Hal ini mencakup nilai tanggal atau waktu yang dipilih pengguna di widget pemilih tanggal atau waktu. Namun, struktur informasinya berbeda-beda, bergantung pada apakah widget dikonfigurasi sebagai pemilih tanggal-waktu, pemilih khusus tanggal, atau pemilih khusus waktu. Perbedaan struktural dijelaskan dalam tabel berikut:

Objek acara kalender

Objek acara Kalender adalah bagian dari keseluruhan objek acara yang membawa informasi tentang kalender dan acara kalender pengguna. Properti ini hanya ada dalam objek peristiwa jika aplikasi host adalah Google Kalender.

Tabel berikut mencantumkan kolom yang ada di kolom calendarEventObject objek peristiwa. Kolom yang ditandai sebagai Data buatan pengguna ada di objek peristiwa jika dan hanya jika data ada di peristiwa Kalender dan add-on menetapkan kolom manifes addOns.calendar.currentEventAccess-nya ke READ atau READ_WRITE.

Tamu

Objek peserta membawa informasi tentang setiap peserta ke acara Google Kalender. Informasi ini ada di objek peristiwa jika dan hanya jika data ada di peristiwa Kalender dan add-on menetapkan kolom manifes addOns.calendar.currentEventAccess-nya ke READ atau READ_WRITE.

Data konferensi

Objek data konferensi membawa informasi tentang konferensi yang dilampirkan ke acara Google Kalender. Solusi ini dapat berupa solusi konferensi Google, seperti Google Meet, atau konferensi pihak ketiga. Informasi ini ada di objek peristiwa jika dan hanya jika data ada di peristiwa Kalender dan add-on menetapkan kolom manifes addOns.calendar.currentEventAccess-nya ke READ atau READ_WRITE.

Titik entri

Objek titik entri membawa informasi tentang cara yang ditetapkan untuk mengakses konferensi tertentu, seperti melalui telepon atau video. Informasi ini ada di objek peristiwa jika dan hanya jika data ada di peristiwa Kalender dan add-on menetapkan kolom manifes addOns.calendar.currentEventAccess-nya ke READ atau READ_WRITE.

Mendorong objek peristiwa

Objek peristiwa Drive adalah bagian dari keseluruhan objek peristiwa yang membawa informasi tentang Google Drive pengguna dan kontennya. Atribut ini hanya ada dalam objek peristiwa jika aplikasi host adalah Google Drive.

Item Drive

Objek item Drive membawa informasi tentang item Drive tertentu, seperti file atau folder.

Objek peristiwa Gmail

Objek peristiwa Gmail adalah bagian dari keseluruhan objek peristiwa yang membawa informasi tentang pesan Gmail pengguna. Ini hanya ada dalam objek peristiwa jika aplikasi host adalah Gmail.

Objek peristiwa Dokumen

Objek peristiwa Dokumen adalah bagian dari keseluruhan objek peristiwa yang membawa informasi tentang dokumen pengguna dan kontennya. Ini hanya ada di objek peristiwa jika aplikasi host adalah Google Dokumen.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Objek peristiwa Spreadsheet

Objek peristiwa Spreadsheet adalah bagian dari keseluruhan objek peristiwa yang membawa informasi tentang dokumen pengguna dan kontennya. Ini hanya ada di objek peristiwa jika aplikasi host adalah Google Spreadsheet.

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Objek peristiwa Slide

Objek peristiwa Slide adalah bagian dari keseluruhan objek peristiwa yang membawa informasi tentang dokumen pengguna dan kontennya. Ini hanya ada di objek peristiwa jika aplikasi host adalah Google Slide.

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}