Tindakan universal

Tindakan universal adalah elemen item menu yang memungkinkan pengguna membuka menampilkan kartu UI baru, atau menjalankan fungsi Apps Script tertentu saat dipilih. Operasinya sangat mirip dengan tindakan kartu, kecuali bahwa tindakan universal selalu ditempatkan di setiap kartu dalam add-on Anda, terlepas dari konteks add-on saat ini.

Dengan menggunakan tindakan universal, Anda dapat memastikan pengguna selalu memiliki akses ke fungsi tertentu, terlepas dari bagian add-on Anda yang berinteraksi kami. Berikut adalah beberapa contoh kasus penggunaan untuk tindakan universal:

• Buka halaman web setelan (atau tampilkan kartu setelan).
• Menampilkan informasi bantuan kepada pengguna.
• Memulai alur kerja baru, misalnya 'Tambahkan pelanggan baru'.
• Tampilkan kartu yang memungkinkan pengguna mengirim masukan tentang add-on.

Setiap kali Anda memiliki tindakan yang tidak tergantung pada konteks saat ini, Anda harus mempertimbangkan untuk menjadikannya sebagai tindakan universal.

Menggunakan tindakan universal

Tindakan universal dikonfigurasi di project add-on Anda manifes. Setelah Anda mengonfigurasi tindakan universal, fitur ini selalu tersedia bagi pengguna add-on Anda. Jika pengguna sedang melihat kartu, serangkaian tindakan universal yang telah Anda tentukan akan selalu muncul di menu kartu, setelah tindakan kartu yang telah Anda tetapkan untuk kartu tersebut. Tindakan universal akan muncul di menu kartu di dengan urutan yang sama seperti definisinya di manifes add-on.

Mengonfigurasi tindakan universal

Anda mengonfigurasi tindakan universal dalam manifes add-on; lihat Manifes untuk mengetahui detail selengkapnya.

Untuk setiap tindakan, Anda menentukan teks yang akan muncul di menu untuk tindakan. Anda kemudian dapat menentukan kolom openLink yang menunjukkan bahwa tindakan tersebut akan langsung membuka halaman web di tab baru. Atau, Anda bisa menentukan kolom runFunction yang menentukan fungsi callback Apps Script untuk mengeksekusi ketika tindakan universal dipilih.

Jika runFunction digunakan, fungsi callback yang ditentukan biasanya melakukan satu dari yang berikut ini:

• Membuat kartu UI yang akan segera ditampilkan dengan menampilkan UniversalActionResponse .
• Membuka URL, mungkin setelah melakukan tugas lain, dengan menampilkan Objek UniversalActionResponse.
• Melakukan tugas latar belakang yang tidak beralih ke kartu baru atau membuka URL. Dalam hal ini, fungsi callback tidak menampilkan apa pun.

Saat dipanggil, fungsi callback akan diteruskan objek peristiwa yang berisi informasi tentang kartu yang terbuka dan konteks add-on.

Peringatan: Agar add-on tetap responsif, layanan Kartu membatasi fungsi callback tindakan universal hingga maksimum 30 detik serta waktu eksekusinya. Jika eksekusi memakan waktu lebih lama dari itu, UI add-on Anda mungkin tidak memperbarui tampilannya dengan benar.

Contoh

Cuplikan kode berikut menunjukkan contoh kutipan manifes untuk Add-on Google Workspace yang menggunakan tindakan universal saat memperluas Gmail. Kode secara eksplisit menetapkan cakupan metadata sehingga dapat menentukan siapa yang mengirim pesan terbuka.

  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata"
  ],
  "addOns": {
    "common": {
      "name": "Universal Actions Only Addon",
      "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
      "openLinkUrlPrefixes": [
        "https://www.google.com",
        "https://www.example.com/urlbase"
      ],
      "universalActions": [{
          "label": "Open google.com",
          "openLink": "https://www.google.com"
        }, {
          "label": "Open contact URL",
          "runFunction": "openContactURL"
        }, {
          "label": "Open settings",
          "runFunction": "createSettingsResponse"
        }, {
          "label": "Run background sync",
          "runFunction": "runBackgroundSync"
      }],
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "getContextualAddOn"
        }
      ]
    },
    ...
  },
  ...

Tiga tindakan universal yang ditentukan dalam contoh sebelumnya melakukan hal berikut:

• Buka google.com akan membuka https://www.google.com di tab baru.
• Buka URL kontak menjalankan fungsi yang menentukan URL yang akan dibuka dan kemudian membukanya di tab baru menggunakan Objek OpenLink. Tujuan kode membuat URL menggunakan alamat email pengirim.
• Buka setelan menjalankan fungsi createSettingsCards() yang ditentukan di ke project skrip add-on. Fungsi ini menampilkan UniversalActionResponse yang berisi kumpulan kartu dengan setelan add-on dan informasi lainnya. Setelah fungsi selesai membangun objek ini, UI akan menampilkan daftar kartu (lihat Mengembalikan beberapa kartu).
• Jalankan sinkronisasi latar belakang menjalankan fungsi runBackgroundSync() yang ditentukan di project skrip add-on Anda. Fungsi ini tidak membuat kartu; itu saja melakukan beberapa tugas latar belakang lain yang tidak mengubah UI. Karena ini tidak mengembalikan UniversalActionResponse, UI tidak menampilkan kartu baru saat fungsi selesai. Sebagai gantinya, UI menampilkan indikator pemuatan dengan indikator lingkaran berputar saat fungsi sedang berjalan.

Berikut adalah contoh cara membuat openContactURL(), Fungsi createSettingsResponse(), dan runBackgroundSync():

/**
 * Open a contact URL.
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function openContactURL(e) {
  // Activate temporary Gmail scopes, in this case so that the
  // open message metadata can be read.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Build URL to open based on a base URL and the sender's email.
  // This URL must be included in the openLinkUrlPrefixes whitelist.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var sender = message.getFrom();
  var url = "https://www.example.com/urlbase/" + sender;
  return CardService.newUniversalActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink()
          .setUrl(url))
      .build();
}

/**
 * Create a collection of cards to control the add-on settings and
 * present other information. These cards are displayed in a list when
 * the user selects the associated "Open settings" universal action.
 *
 * @param {Object} e an event object
 * @return {UniversalActionResponse}
 */
function createSettingsResponse(e) {
  return CardService.newUniversalActionResponseBuilder()
      .displayAddOnCards(
          [createSettingCard(), createAboutCard()])
      .build();
}

/**
 * Create and return a built settings card.
 * @return {Card}
 */
function createSettingCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('Settings'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newSelectionInput()
              .setType(CardService.SelectionInputType.CHECK_BOX)
              .addItem("Ask before deleting contact", "contact", false)
              .addItem("Ask before deleting cache", "cache", false)
              .addItem("Preserve contact ID after deletion", "contactId", false))
          // ... continue adding widgets or other sections here ...
      ).build();   // Don't forget to build the card!
}

/**
 * Create and return a built 'About' informational card.
 * @return {Card}
 */
function createAboutCard() {
  return CardService.newCardBuilder()
      .setHeader(CardService.newCardHeader().setTitle('About'))
      .addSection(CardService.newCardSection()
          .addWidget(CardService.newTextParagraph()
              .setText('This add-on manages contact information. For more '
                  + 'details see the <a href="https://www.example.com/help">'
                  + 'help page</a>.'))
      // ... add other information widgets or sections here ...
      ).build();  // Don't forget to build the card!
}

/**
 * Run background tasks, none of which should alter the UI.
 * Also records the time of sync in the script properties.
 *
 * @param {Object} e an event object
 */
function runBackgroundSync(e) {
  var props = PropertiesService.getUserProperties();
  props.setProperty("syncTime", new Date().toString());

  syncWithContacts();  // Not shown.
  updateCache();       // Not shown.
  validate();          // Not shown.

  // no return value tells the UI to keep showing the current card.
}