Pemicu untuk Add-on Editor

Pemicu Apps Script menyebabkan fungsi skrip tertentu (fungsi pemicu) dijalankan setiap kali peristiwa tertentu terjadi. Hanya peristiwa tertentu yang dapat menyebabkan pemicu diaktifkan, dan setiap aplikasi Google Workspace mendukung kumpulan peristiwa yang berbeda.

Saat pemicu diaktifkan, objek peristiwa akan dibuat. Struktur JSON ini berisi detail tentang peristiwa yang terjadi. Informasi dalam struktur objek peristiwa diatur secara berbeda berdasarkan jenis pemicu.

Setelah objek peristiwa dibuat, Apps Script akan meneruskannya sebagai parameter ke fungsi pemicu. Fungsi pemicu adalah fungsi callback yang harus Anda terapkan sendiri, untuk mengambil tindakan apa pun yang sesuai untuk merespons peristiwa tersebut. Misalnya, di Add-on Editor, pemicu digunakan untuk membuat item menu add-on saat dokumen dibuka. Dalam hal ini, Anda menerapkan fungsi pemicu onOpen(e) untuk membuat item menu yang diperlukan add-on, yang mungkin menggunakan data dalam objek peristiwa.

Halaman ini memberikan panduan tentang penggunaan pemicu di project add-on editor.

Jenis pemicu Add-on Editor

Anda dapat menggunakan sebagian besar jenis pemicu umum yang tersedia untuk project Apps Script di Add-on Editor, termasuk pemicu sederhana dan sebagian besar pemicu yang dapat diinstal. Kumpulan jenis pemicu yang tersedia secara tepat bergantung pada aplikasi yang diperluas.

Tabel berikut menunjukkan jenis pemicu sederhana dan yang dapat diinstal yang dapat digunakan Add-on Editor, serta memberikan link ke objek peristiwa yang sesuai:

Event	Objek peristiwa	Pemicu sederhana	Pemicu yang dapat diinstal
Buka File editor akan terbuka.	Dokumen peristiwa onOpen Objek peristiwa onOpen Objek peristiwa onOpen pada Spreadsheet Objek peristiwa onOpen Slide	Dokumen Formulir* Spreadsheet Slide function onOpen(e)	Dokumen Formulir Spreadsheet
Instal Add-on sudah diinstal.	Objek peristiwa onInstall	Dokumen Formulir Spreadsheet Slide function onInstall(e)
Edit Konten sel spreadsheet diubah.	Spreadsheet onEdit objek peristiwa	Spreadsheet function onEdit(e)	Spreadsheet
Ubah Konten dalam sheet diedit atau diformat.	Objek peristiwa onChange Spreadsheet		Spreadsheet
Pengiriman formulir Formulir Google dikirimkan.	Objek peristiwa pengiriman formulir Formulir Objek peristiwa pengiriman formulir Spreadsheet		Formulir Spreadsheet
Berdasarkan waktu (jam) Pemicu diaktifkan pada waktu atau interval yang ditentukan.	Objek peristiwa berbasis waktu		Dokumen Formulir Spreadsheet Slide

* Peristiwa terbuka untuk Google Formulir tidak terjadi saat pengguna membuka formulir untuk merespons, tetapi saat editor membuka formulir untuk mengubahnya.

Pemicu sederhana di add-on

Pemicu sederhana menggunakan kumpulan nama fungsi yang dicadangkan, tidak dapat menggunakan layanan yang memerlukan otorisasi, dan otomatis diaktifkan untuk digunakan. Dalam beberapa kasus, peristiwa pemicu sederhana dapat ditangani oleh pemicu yang dapat diinstal.

Anda dapat menambahkan pemicu sederhana ke add-on cukup dengan mengimplementasikan fungsi menggunakan salah satu nama yang dicadangkan berikut:

• onOpen(e) dijalankan saat pengguna membuka dokumen, spreadsheet, atau presentasi. onOpen(e) juga dapat dijalankan saat formulir dibuka di editor (tetapi tidak saat merespons formulir). Fitur ini hanya dijalankan jika pengguna memiliki izin untuk mengedit file yang dimaksud, dan paling sering digunakan untuk membuat item menu.
• onInstall(e) dijalankan saat pengguna menginstal add-on. Biasanya onInstall(e) hanya digunakan untuk memanggil onOpen(e); ini memastikan bahwa menu add-on segera muncul setelah penginstalan tanpa mengharuskan pengguna memuat ulang halaman.
• onEdit(e) dijalankan saat pengguna mengubah nilai sel di spreadsheet. Pemicu ini tidak diaktifkan sebagai respons terhadap pemindahan sel, pemformatan, atau perubahan lain yang tidak mengubah nilai sel.

Batasan

Pemicu sederhana dalam add-on tunduk pada pembatasan yang sama yang mengatur pemicu sederhana pada jenis project Apps Script lainnya. Perhatikan secara khusus batasan ini saat mendesain add-on:

• Pemicu sederhana tidak akan berjalan jika file dibuka dalam mode hanya baca (lihat atau komentar). Perilaku ini mencegah pengisian menu add-on.
• Dalam situasi tertentu, Add-on Editor menjalankan pemicu sederhana onOpen(e) dan onEdit(e) dalam mode tanpa otorisasi. Mode ini menyajikan beberapa detail tambahan seperti yang diuraikan dalam model otorisasi add-on.
• Pemicu sederhana tidak dapat menggunakan layanan atau melakukan tindakan lain yang memerlukan otorisasi, kecuali seperti yang diuraikan dalam model otorisasi add-on.
• Pemicu sederhana tidak dapat berjalan lebih dari 30 detik. Pastikan untuk meminimalkan jumlah pemrosesan yang dilakukan dalam fungsi pemicu sederhana.
• Pemicu sederhana tunduk pada batas kuota pemicu Apps Script.

Pemicu yang dapat diinstal di add-on

Add-on dapat membuat dan mengubah pemicu yang dapat diinstal secara terprogram dengan layanan Apps Script Script. Pemicu add-on yang dapat diinstal tidak dapat dibuat secara manual. Tidak seperti pemicu sederhana, pemicu yang dapat diinstal dapat menggunakan layanan yang memerlukan otorisasi.

Pemicu yang dapat diinstal di add-on tidak akan mengirim email error kepada pengguna saat mengalami error, karena dalam sebagian besar kasus, pengguna tidak dapat mengatasi masalah tersebut. Karena itu, Anda harus mendesain add-on untuk menangani error dengan baik atas nama pengguna jika memungkinkan.

Add-on dapat menggunakan pemicu yang dapat diinstal berikut:

• Pemicu Buka yang dapat diinstal dijalankan saat pengguna membuka dokumen, spreadsheet, atau saat formulir dibuka di editor (tetapi tidak saat merespons formulir).
• Pemicu Edit yang dapat diinstal akan dijalankan saat pengguna mengubah nilai sel di spreadsheet. Pemicu ini tidak diaktifkan sebagai respons terhadap pemformatan atau perubahan lain yang tidak mengubah nilai sel.
• Pemicu Perubahan yang dapat diinstal dijalankan saat pengguna melakukan perubahan di spreadsheet, termasuk pengeditan dan modifikasi pemformatan pada spreadsheet itu sendiri (seperti menambahkan baris).

• Pemicu pengiriman formulir yang dapat diinstal akan dijalankan saat respons Formulir Google dikirim.

• Pemicu berbasis waktu (disebut juga pemicu jam) diaktifkan pada waktu tertentu atau berulang kali pada interval waktu yang teratur.

Mengizinkan pemicu yang dapat diinstal

Biasanya, jika developer mengupdate add-on untuk menggunakan layanan baru yang memerlukan otorisasi tambahan, pengguna akan diminta untuk memberikan otorisasi ulang add-on tersebut pada waktu berikutnya mereka menggunakannya.

Namun, add-on yang menggunakan pemicu mengalami tantangan otorisasi khusus. Bayangkan add-on yang menggunakan pemicu untuk memantau pengiriman formulir: pembuat formulir mungkin mengizinkan add-on saat pertama kali dia menggunakannya, lalu membiarkannya berjalan selama berbulan-bulan atau bertahun-tahun tanpa harus membuka kembali formulir. Jika developer add-on memperbarui add-on untuk menggunakan layanan baru yang memerlukan otorisasi tambahan, pembuat formulir tidak akan pernah melihat dialog otorisasi ulang karena mereka tidak pernah membuka kembali formulir, dan add-on akan berhenti berfungsi.

Tidak seperti pemicu dalam project Apps Script biasa, pemicu pada add-on akan terus diaktifkan meskipun memerlukan otorisasi ulang. Namun, skrip masih gagal jika mencapai baris kode yang memerlukan otorisasi yang tidak dimiliki skrip. Untuk menghindari situasi ini, developer dapat menggunakan metode ScriptApp.getAuthorizationInfo() untuk membuka akses ke bagian kode yang telah berubah antara versi add-on yang dipublikasikan.

Berikut adalah contoh struktur yang direkomendasikan untuk digunakan dalam fungsi pemicu untuk menghindari masalah otorisasi. Contoh fungsi pemicu merespons peristiwa pengiriman formulir dalam add-on Google Spreadsheet dan, jika otorisasi ulang diperlukan, mengirim email pemberitahuan kepada pengguna add-on menggunakan HTML template.

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Batasan

Pemicu yang dapat diinstal di add-on tunduk pada pembatasan yang sama yang mengatur pemicu yang dapat diinstal dalam jenis project Apps Script lainnya.

Selain batasan ini, beberapa batasan berlaku untuk pemicu yang dapat diinstal di add-on, khususnya:

• Setiap add-on hanya dapat memiliki satu pemicu untuk setiap jenis, per pengguna, per dokumen. Misalnya, dalam spreadsheet tertentu, pengguna tertentu hanya dapat memiliki satu pemicu edit, meskipun pengguna tersebut juga dapat memiliki pemicu pengiriman formulir atau pemicu berdasarkan waktu di spreadsheet yang sama. Pengguna yang berbeda dengan akses ke {i>spreadsheet<i} yang sama dapat memiliki kumpulan pemicunya sendiri yang terpisah.
• Add-on hanya dapat membuat pemicu untuk file tempat add-on digunakan. Artinya, add-on yang digunakan di Google Dokumen A tidak dapat membuat pemicu untuk memantau saat Google Dokumen B dibuka.
• Pemicu berbasis waktu tidak dapat berjalan lebih dari sekali per jam.
• Add-on tidak otomatis mengirim email kepada pengguna saat kode yang dijalankan oleh pemicu yang dapat diinstal menampilkan pengecualian. Developer dapat memeriksa dan menangani kasus kegagalan dengan baik.
• Pemicu add-on berhenti diaktifkan dalam salah satu situasi berikut:
  • Jika {i>add-on<i} di-{i>uninstal<i} oleh pengguna,
  • Jika add-on dinonaktifkan dalam dokumen (jika diaktifkan kembali, pemicu akan beroperasi kembali), atau
  • Jika developer membatalkan publikasi add-on atau mengirimkan versi yang rusak ke add-on store.
• Fungsi pemicu add-on akan dijalankan hingga mencapai kode yang menggunakan layanan tidak sah, lalu fungsi tersebut berhenti. Hal ini hanya berlaku jika add-on dipublikasikan; pemicu yang sama dalam project Apps Script reguler atau add-on yang tidak dipublikasikan tidak akan dijalankan sama sekali jika ada bagian skrip yang memerlukan otorisasi.
• Pemicu yang dapat diinstal bergantung pada batas kuota pemicu Apps Script.