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 pada fungsi pemicu halaman beranda untuk mengidentifikasi aplikasi {i>host<i} aktif, antarmuka pengguna platform, lokalitas pengguna, dan informasi lainnya.

  Objek peristiwa yang dibuat saat halaman beranda memicu pengaktifan tidak berisi semua {i>field<i} yang ada di dua kasus lainnya; yang berkaitan dengan widget dan informasi kontekstual dihilangkan.

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

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

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

• Tindakan widget. Objek peristiwa juga digunakan untuk menyediakan widget interaktivitas, menggunakan model tindakan yang ditambahkan add-on Gmail gunakan. 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 tindakan widget berisi semua kolom yang disertakan dalam objek peristiwa pemicu kontekstual, serta 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 membangun tindakan widget yang memungkinkan pengguna berinteraksi dengan kartu pratinjau dan isinya.

Struktur objek peristiwa

Tabel berikut menjelaskan struktur tingkat atas objek peristiwa Add-on Google Workspace. Acara struktur objek mencakup commonEventObject {i>top-level<i} untuk informasi {i>host<i} yang tidak bergantung. Setiap objek peristiwa juga dapat memiliki salah satu bidang 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. 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 mengkueri objek peristiwa umum untuk menentukan konten widget yang terbuka di dengan klien besar. 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 tergantung pada apakah telah dikonfigurasi sebagai pemilih tanggal-waktu, pemilih tanggal saja, atau time-only pemilih. 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 addOns.calendar.currentEventAccess manifes ke READ atau READ_WRITE.

Tamu

Objek tamu membawa informasi tentang masing-masing tamu ke Google Kalender peristiwa. 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 tersedia di objek acara jika dan hanya jika data ada dalam acara Kalender dan add-on menetapkan addOns.calendar.currentEventAccess-nya manifes kolom ke READ atau READ_WRITE.

Objek peristiwa Drive

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 isinya. 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 isinya. Ini hanya ada di objek peristiwa jika aplikasi host adalah Google Slide.

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