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 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 dengan memulai add-on saat melihat pesan.

Kedua kasus tersebut 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.

Mem-build 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. 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 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 akan menjalankan fungsi pemicu kontekstual yang membuat antarmuka pengguna add-on dan menampilkannya untuk ditampilkan Gmail. Pada tahap tersebut, pengguna dapat mulai berinteraksi dengannya.

Pemicu kontekstual ditentukan dalam manifes project add-on Anda. 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 Anda. 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 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 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 bertindak berdasarkan data ini, mengekstrak informasi yang diperlukan untuk antarmuka. Misalnya, add-on yang meringkas 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 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];
  }