Mở rộng giao diện người dùng của thông báo

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 của Google Workspace 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êm thông tin liên quan đến thư.

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

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

Cả hai trường hợp đều khiến tiện ích bổ sung thực thi hàm kích hoạt theo bối cảnh tương ứng, được xác định trong tệp kê khai của 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 điều kiện 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 về tin nhắn

Bạn có thể thêm chức năng tin nhắn 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 của dự án tập lệnh bổ sung, bao gồm cả phạm vi cần thiết cho chức năng thông báo. Hãy nhớ thêm trường điều kiện kích hoạt vào tệp kê khai, với giá trị unconditional là {}.
2. Triển khai hàm điều kiện kích hoạt theo ngữ cảnh để tạo giao diện người dùng tin nhắn khi người dùng chọn tiện ích bổ sung trong tin nhắn.
3. Triển khai các hàm liên kết cần thiết để phản hồi các hoạt động tương tác của người dùng trên 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ủa Google Workspace có thể xác định một trình kích hoạt theo ngữ cảnh trong tệp kê khai của chúng. Khi người dùng mở một thư Gmail (khi tiện ích bổ sung đang mở) đáp ứng các tiêu chí của điều kiện kích hoạt*, điều kiện kích hoạt sẽ kích hoạt. Một trình kích hoạt đã kích hoạt sẽ thực thi hàm trình 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ị. Khi đó, người dùng có thể bắt đầu tương tác với ứng dụng.

Trình kích hoạt theo bối cảnh được xác định trong tệp kê khai của dự án tiện ích bổ sung. Định nghĩa điều kiện kích hoạt cho Gmail biết hàm điều kiện 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ông báo được mở:

{
  ...
  "addOns": {

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

Hàm điều kiện 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 các đố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 vào hàm đó một đối tượng sự kiện hành động. Thông thường, các hàm kích hoạt 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 cách sử dụng dịch vụ Gmail của Apps Script. Ví dụ: hàm kích hoạt có thể trích xuất nội dung tin nhắn 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 các số liệu đó để 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 Card đã tạo. Ví dụ: đoạn mã sau đây sẽ 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 của 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.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }