Objek peristiwa

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

Objek peristiwa adalah struktur JSON yang otomatis dibuat dan diteruskan sebagai parameter untuk memicu atau fungsi callback saat pengguna berinteraksi dengan {i>add-on<i}. 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 menerima peristiwa saat fungsi pemicu halaman beranda diaktifkan. Anda dapat menggunakan objek ini pada fungsi pemicu halaman beranda untuk mengidentifikasi aplikasi {i>host<i} aktif, konfigurasi 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 saat 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 pemicu pengaktifan 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 yang sama, Objek Action, dan tindakan yang dihasilkan. 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.

• Pemicu link pratinjau. 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 diaktifkan, dan objek peristiwa yang berisi link diteruskan ke fungsi callback. Add-on Anda dapat menggunakan objek peristiwa ini untuk membuat dan kartu yang menampilkan informasi tentang link dalam host aplikasi. Anda juga dapat membangun tindakan widget yang memungkinkan pengguna berinteraksi dengan kartu pratinjau dan isinya.

Struktur objek peristiwa

Tabel berikut menjelaskan struktur tingkat atas dari Objek peristiwa Add-on Google Workspace. Acara struktur objek mencakup commonEventObject {i>top-level<i} untuk informasi yang tidak bergantung pada {i>host<i}. 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, Add-on Google Workspace juga mencakup semua bidang 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 di 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 halaman beranda dan pemicu 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 Widget TextInput di Objek eventObject.commentEventObject.formInputs.

Input formulir pemilih tanggal dan waktu

Fungsi callback tindakan dapat menerima nilai widget saat ini di kolom commonEventObject.formInputs. Ini mencakup nilai tanggal atau waktu yang dipilih pengguna di pemilih tanggal atau waktu widget. 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. Itu hanya ada dalam objek acara jika aplikasi host adalah Google Kalender.

Tabel berikut mencantumkan kolom yang ada di calendarEventObject kolom objek peristiwa. Kolom yang ditandai sebagai Data buatan pengguna adalah ada di objek acara jika dan hanya jika data tersebut ada di Kalender peristiwa, dan add-on menetapkan addOns.calendar.currentEventAccess manifes kolom 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 acara Kalender dan add-on menetapkan addOns.calendar.currentEventAccess manifes kolom ke READ atau READ_WRITE.

Data konferensi

Objek data konferensi membawa informasi tentang konferensi yang dilampirkan ke acara Google Kalender. Solusi ini bisa berupa solusi konferensi Google, seperti Google Meet, atau konferensi pihak ketiga. Informasi ini tersedia di jika dan hanya jika data ada dalam acara Kalender dan add-on menetapkan addOns.calendar.currentEventAccess manifes kolom 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 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 beserta kontennya. Itu hanya ada di 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. Hanya ada dalam objek peristiwa jika aplikasi {i>host<i} 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 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 isinya. Ini hanya ada di peristiwa jika aplikasi host adalah Google Sheets.

"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 jika aplikasi host adalah Google Slides.

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