Mở rộng giao diện người dùng tin nhắn

Các tiện ích bổ sung của Google Workspace mở rộng Gmail có thể cung cấp giao diện người dùng khi người dùng đang đọc thư. Điều này cho phép các tiện ích bổ sung tự động hoá các tác vụ phản hồi nội dung thư, chẳng hạn như hiển thị, truy xuất hoặc gửi thông tin bổ sung liên quan đến thư.

Truy cập vào giao diện người dùng của tiện ích bổ sung Google Workspace

Có 2 cách để xem giao diện người dùng của tiện ích bổ sung. Cách thứ nhất là mở một thư trong khi tiện ích bổ sung đã mở (ví dụ: khi xem trang chủ của tiện ích bổ sung trong cửa sổ hộp thư đến của Gmail). Cách thứ hai là bắt đầu tiện ích bổ sung trong khi xem một thư.

Trong cả hai trường hợp, tiện ích bổ sung sẽ thực thi hàm kích hoạt theo ngữ cảnh tương ứng, được xác định trong tệp kê khai tiện ích bổ sung. Trình kích hoạt cũng thực thi nếu người dùng chuyển sang một thư khác trong khi tiện ích bổ sung vẫn đang mở. Hàm kích hoạt theo ngữ cảnh sẽ tạo giao diện người dùng của thư cho thư đó, sau đó Gmail sẽ hiển thị cho người dùng.

Tạo tiện ích bổ sung cho thư

Bạn có thể thêm chức năng thư vào tiện ích bổ sung bằng cách làm theo các bước chung sau:

1. Thêm các trường thích hợp vào tệp kê khai dự án tập lệnh tiện ích bổ sung, bao gồm cả các phạm vi bắt buộc đối với chức năng thư. Hãy nhớ thêm một trường kích hoạt có điều kiện vào tệp kê khai, với giá trị unconditional là {}.
2. Triển khai một hàm kích hoạt theo ngữ cảnh để tạo giao diện người dùng của thư khi người dùng chọn tiện ích bổ sung trong một thư.
3. Triển khai các hàm liên kết cần thiết để phản hồi hoạt động tương tác của người dùng với giao diện người dùng.

Trình kích hoạt theo ngữ cảnh

Để hỗ trợ người dùng khi đọc thư, các tiện ích bổ sung có thể xác định trình kích hoạt theo ngữ cảnh trong tệp kê khai. Khi người dùng mở một thư Gmail (với tiện ích bổ sung đang mở) đáp ứng tiêu chí kích hoạt*, trình kích hoạt sẽ kích hoạt. Trình kích hoạt đã kích hoạt sẽ thực thi một hàm kích hoạt theo ngữ cảnh để tạo giao diện người dùng của tiện ích bổ sung và trả về giao diện đó để Gmail hiển thị. Tại thời điểm đó, người dùng có thể bắt đầu tương tác với giao diện này.

Trình kích hoạt theo ngữ cảnh được xác định trong tệp kê khai dự án của tiện ích bổ sung . Định nghĩa trình kích hoạt cho Gmail biết hàm kích hoạt nào sẽ kích hoạt trong điều kiện nào. Ví dụ: đoạn mã tệp kê khai này đặt một điều kiện kích hoạt vô điều kiện gọi hàm kích hoạt onGmailMessageOpen() khi một thư được mở:

{
  ...
  "addOns": {

    "common": {
      ...
    },
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ],
      ...
    },
    ...
  }
  ...
}

Hàm kích hoạt theo ngữ cảnh

Mỗi trình kích hoạt theo ngữ cảnh phải có một hàm kích hoạt tương ứng để tạo giao diện người dùng của tiện ích bổ sung. Bạn chỉ định hàm này trong trường onTriggerFunction của tệp kê khai. Bạn triển khai hàm này để chấp nhận đối số đối tượng sự kiện hành động và trả về một đối tượng Card hoặc một mảng đối tượng Card.

Khi một trình kích hoạt theo ngữ cảnh kích hoạt cho một thư Gmail nhất định, trình kích hoạt đó sẽ gọi hàm này và truyền đối tượng sự kiện hành động cho hàm. Các hàm kích hoạt thường sử dụng mã thư do đối tượng sự kiện này cung cấp để lấy văn bản thư và các thông tin chi tiết khác bằng dịch vụ Gmail của Apps Script . Trong hầu hết các trường hợp, bạn phải kích hoạt phạm vi Gmail bằng mã truy cập do đối tượng sự kiện và hàm GmailApp.setCurrentMessageAccessToken(accessToken) cung cấp trước khi sử dụng các hàm dịch vụ Gmail khác. Ví dụ: hàm kích hoạt của bạn có thể trích xuất nội dung thư bằng các hàm sau:

// 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();

Sau đó, hàm kích hoạt có thể hoạt động trên dữ liệu này, trích xuất thông tin cần thiết cho giao diện. Ví dụ: một tiện ích bổ sung tóm tắt số liệu bán hàng có thể thu thập số liệu bán hàng từ nội dung thư và sắp xếp để hiển thị trong một thẻ.

Hàm kích hoạt phải tạo và trả về một mảng các đối tượng đã tạo Card. Ví dụ: đoạn mã sau đây tạo một tiện ích bổ sung có một thẻ duy nhất chỉ liệt kê tiêu đề và người gửi thư:

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];
}