Memperluas UI pesan

Add-on Google Workspace yang memperluas Gmail dapat menyediakan antarmuka pengguna saat pengguna membaca pesan. Hal ini memungkinkan Add-on Google Workspace mengotomatiskan tugas yang merespons konten pesan, seperti menampilkan, mengambil, atau mengirim informasi tambahan terkait 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.

Kedua kasus tersebut akan menyebabkan add-on menjalankan fungsi pemicu kontekstual yang sesuai, yang ditentukan dalam manifes add-on. Pemicu juga dijalankan 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 oleh 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 dari {}.
  2. Mengimplementasikan fungsi pemicu kontekstual yang mem-build UI pesan saat pengguna memilih add-on dalam pesan.
  3. Mengimplementasikan fungsi terkait yang diperlukan untuk merespons interaksi UI pengguna.

Pemicu kontekstual

Untuk memberikan bantuan kepada pengguna saat membaca pesan, Add-on Google Workspace 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 menampilkannya untuk ditampilkan oleh Gmail. Pada saat itu, pengguna dapat mulai berinteraksi dengan aplikasi.

Pemicu kontekstual ditentukan dalam manifes project add-on Anda. Definisi pemicu memberi tahu Gmail mengenai pemicuan fungsi 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. Anda menentukan fungsi ini di kolom onTriggerFunction manifes. 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 tersebut akan memanggil fungsi ini dan meneruskannya objek peristiwa tindakan. Fungsi pemicu sering kali menggunakan ID pesan yang disediakan 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 berikut:

  // 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 menindaklanjuti data ini, dengan mengekstrak informasi yang diperlukan untuk antarmuka. Misalnya, add-on yang merangkum angka penjualan dapat mengumpulkan angka penjualan dari isi pesan dan mengaturnya untuk ditampilkan dalam kartu.

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