Memperluas UI pesan

Add-on Google Workspace yang memperluas Gmail dapat menyediakan antarmuka pengguna ketika pengguna membaca pesan. Hal ini memungkinkan Add-on Google Workspace untuk mengotomatiskan tugas yang merespons ke isi pesan, seperti menampilkan, mengambil, atau mengirimkan informasi tambahan yang terkait dengan pesan tersebut.

Mengakses UI pesan add-on

Ada dua cara untuk melihat UI pesan add-on. Cara pertama adalah dengan 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 sambil melihat pesan.

Kedua kasus tersebut menyebabkan add-on mengeksekusi fungsi pemicu kontekstual, yang ditentukan di bagian manifes add-on. Pemicu juga akan dijalankan jika pengguna beralih ke pesan lain saat add-on ini masih terbuka. Fungsi pemicu kontekstual membangun 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. Menambahkan kolom yang sesuai ke project skrip add-on manifes, termasuk cakupan diperlukan untuk fungsi pesan. Pastikan untuk menambahkan kolom pemicu kondisional ke manifes, dengan unconditional senilai {}.
2. Mengimplementasikan fungsi pemicu kontekstual yang membangun UI pesan saat pengguna memilih add-on dalam pesan.
3. Implementasikan fungsi terkait yang diperlukan untuk merespons UI pengguna interaksi.

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 pemicu kriteria* pemicu akan diaktifkan. Pemicu yang diaktifkan mengeksekusi fungsi pemicu kontekstual yang menyusun dan menampilkannya di Gmail. Pada saat itu, pengguna dapat mulai berinteraksi dengan komputer itu.

Pemicu kontekstual ditentukan dalam project add-on Anda manifes. Definisi pemicu memberi tahu Gmail fungsi pemicu mana yang akan diaktifkan kondisi tertentu. Misalnya, cuplikan manifes ini menyetel 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 membangun antarmuka pengguna add-on Anda. Anda menetapkan fungsi ini di onTriggerFunction manifes kolom tersebut. Anda harus mengimplementasikan fungsi ini untuk menerima objek peristiwa tindakan dan mengembalikan satu Objek Card atau array Objek Card.

Saat pemicu kontekstual diaktifkan untuk pesan Gmail tertentu, pemicu akan memanggilnya dan meneruskan objek peristiwa tindakan. Sering kali fungsi pemicu menggunakan ID pesan yang disediakan oleh objek peristiwa ini untuk mendapatkan teks pesan dan detail lainnya menggunakan Layanan Gmail. Misalnya, pemicu Anda dapat mengekstrak isi 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 bertindak pada data ini, mengekstrak informasi yang yang dibutuhkan untuk antarmuka. Misalnya, add-on yang merangkum penjualan angka penjualan dapat mengumpulkan angka penjualan dari isi pesan dan mengaturnya untuk ditampilkan dalam kartu.

Fungsi pemicu harus membangun dan menampilkan array Card objek terstruktur dalam jumlah besar. 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];
  }