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:
- 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{}
. - Mengimplementasikan fungsi pemicu kontekstual yang mem-build UI pesan saat pengguna memilih add-on dalam pesan.
- 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];
}