Memperluas UI pesan

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Google Workspace add-on yang memperluas Gmail dapat menyediakan antarmuka pengguna saat pengguna membaca pesan. Hal ini memungkinkanGoogle Workspace add-on untuk mengotomatiskan tugas yang merespons konten pesan, seperti menampilkan, mengambil, atau mengirim informasi tambahan yang terkait dengan pesan.

Mengakses UI pesan add-on

Ada dua cara untuk melihat UI pesan add-on. Cara pertama adalah membuka pesan saat add-on sudah terbuka (misalnya, saat melihat halaman beranda add-on di jendela kotak masuk Gmail). Cara kedua adalah memulai add-on saat melihat pesan.

Apa pun kasusnya, add-on akan menjalankan fungsi pemicu kontekstual yang sesuai, yang ditentukan dalam manifes add-on. Pemicu juga dieksekusi jika pengguna beralih ke pesan yang berbeda saat add-on masih terbuka. Fungsi pemicu kontekstual mem-build UI pesan untuk pesan tersebut, yang kemudian ditampilkan Gmail kepada pengguna.

Membuat add-on pesan

Anda dapat menambahkan fungsi pesan ke add-on dengan mengikuti langkah-langkah umum berikut:

  1. Tambahkan kolom yang sesuai ke manifes project skrip add-on, termasuk cakupan yang diperlukan untuk fungsi pesan. Pastikan untuk menambahkan kolom pemicu bersyarat ke manifes dengan nilai unconditional {}.
  2. Implementasikan fungsi pemicu kontekstual yang membuat UI pesan saat pengguna memilih add-on dalam pesan.
  3. Terapkan fungsi terkait yang diperlukan untuk merespons interaksi UI pengguna.

Pemicu kontekstual

Untuk memberikan bantuan kepada pengguna saat membaca pesan, Google Workspace add-on dapat menentukan pemicu kontekstual dalam manifes mereka. Saat pengguna membuka pesan Gmail (dengan add-on terbuka) yang memenuhi kriteria pemicu*, pemicu diaktifkan. Pemicu yang diaktifkan menjalankan fungsi pemicu kontekstual yang menyusun antarmuka pengguna add-on dan menampilkannya untuk ditampilkan Gmail. Pada saat itu, pengguna dapat mulai berinteraksi dengannya.

Pemicu kontekstual ditentukan dalam manifes project add-on. Definisi pemicu memberi tahu Gmail fungsi pemicu mana yang akan diaktifkan dalam kondisi tertentu. Misalnya, cuplikan manifes ini menetapkan pemicu tanpa syarat yang memanggil fungsi pemicu onGmailMessageOpen() saat pesan dibuka:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

Fungsi pemicu kontekstual

Setiap pemicu kontekstual harus memiliki fungsi pemicu yang sesuai yang membuat antarmuka pengguna add-on. Tentukan fungsi ini di kolom onTriggerFunction manifes Anda. Anda menerapkan fungsi ini untuk menerima argumen objek peristiwa tindakan dan menampilkan satu objek Card atau array objek Card.

Saat diaktifkan untuk pesan Gmail, pemicu kontekstual akan memanggil fungsi ini dan meneruskan objek peristiwa tindakan. Sering kali fungsi pemicu menggunakan ID pesan yang diberikan oleh objek peristiwa ini untuk mendapatkan teks pesan dan detail lainnya menggunakan layanan Gmail Apps Script. Misalnya, fungsi pemicu Anda dapat mengekstrak konten pesan menggunakan fungsi ini:

  // Activate temporary Gmail scopes, in this case to allow
  // the add-on to read message metadata and content.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Read message metadata and content. This requires the Gmail scope
  // https://www.googleapis.com/auth/gmail.addons.current.message.readonly.
  var messageId = e.gmail.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();

  // Setting the access token with a gmail.addons.current.message.readonly
  // scope also allows read access to the other messages in the thread.
  var thread = message.getThread();
  var threadMessages = thread.getMessages();

  // Using this link can avoid the need to copy message or thread content
  var threadLink = thread.getPermalink();

Fungsi pemicu kemudian dapat bertindak pada data ini, mengekstrak informasi yang diperlukan untuk antarmuka. Misalnya, add-on yang merangkum jumlah penjualan dapat mengumpulkan angka penjualan dari isi pesan dan mengelolanya untuk ditampilkan di kartu.

Fungsi pemicu harus mem-build dan menampilkan array objek Card yang di-build. Misalnya, kode berikut membuat add-on dengan satu kartu yang hanya mencantumkan subjek dan pengirim pesan:

  function onGmailMessageOpen(e) {
    // Activate temporary Gmail scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.gmail.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.gmail.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }