Memperluas UI pesan

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

Mengakses UI pesan add-on Google Workspace

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.

Kedua kasus ini menyebabkan add-on menjalankan fungsi pemicu kontekstual yang sesuai, yang ditentukan dalam manifes add-on. Pemicu juga dijalankan jika pengguna beralih ke pesan lain saat add-on masih terbuka. Fungsi pemicu kontekstual membuat 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 project skrip add-on manifest, termasuk cakupan yang diperlukan untuk fungsi pesan. Pastikan untuk menambahkan kolom pemicu bersyarat ke manifes, dengan nilai unconditional {}.
2. Terapkan 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, add-on dapat menentukan pemicu kontekstual dalam manifesnya. Saat pengguna membuka pesan Gmail (dengan add-on terbuka) yang memenuhi kriteria pemicu*, pemicu akan diaktifkan. Pemicu yang diaktifkan menjalankan fungsi pemicu kontekstual yang membuat antarmuka pengguna add-on dan menayangkannya agar ditampilkan oleh Gmail. Pada saat itu, pengguna dapat mulai berinteraksi dengannya.

Pemicu kontekstual ditentukan dalam manifes project add-on Anda. Definisi pemicu memberi tahu Gmail fungsi pemicu mana yang harus diaktifkan dalam kondisi apa. 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 untuk menyusun antarmuka pengguna add-on Anda. Anda menentukan 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 pemicu kontekstual diaktifkan untuk pesan Gmail tertentu, pemicu akan memanggil fungsi ini dan meneruskan objek peristiwa tindakan. Fungsi pemicu sering menggunakan ID pesan yang disediakan oleh objek peristiwa ini untuk mendapatkan teks pesan dan detail lainnya menggunakan layanan Gmail Apps Script. Dalam sebagian besar kasus, Anda harus mengaktifkan cakupan Gmail menggunakan token akses yang disediakan oleh objek peristiwa dan fungsi GmailApp.setCurrentMessageAccessToken(accessToken) sebelum menggunakan fungsi layanan Gmail lainnya. 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 berdasarkan data ini, mengekstrak informasi yang dibutuhkan untuk antarmuka. Misalnya, add-on yang meringkas angka penjualan dapat mengumpulkan angka penjualan dari isi pesan dan menyusunnya untuk ditampilkan dalam kartu.

Fungsi pemicu harus membuat dan menampilkan array objek Card yang dibuat. 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.newDecoratedText()
              .setTopLabel('Subject')
              .setText(subject))
          .addWidget(CardService.newDecoratedText()
              .setTopLabel('From')
              .setText(sender)))
      .build();   // Don't forget to build the Card!
  return [exampleCard];
}