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ông báo. Điều này cho phép Tiện ích bổ sung của Google Workspace giúp tự động hoá những tác vụ cần phản hồi vào nội dung thư, chẳng hạn như hiển thị, truy xuất hoặc gửi đ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 cho thông báo

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ông báo trong khi tiện ích bổ sung đang 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à khởi động tiện ích bổ sung trong khi xem thư.

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

Tạo tiện ích bổ sung cho tin nhắn

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

Điều kiện kích hoạt theo ngữ cảnh

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

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

{
  ...
  "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 để xây dựng giao diện người dùng của tiện ích bổ sung. Bạn chỉ định hàm này trong onTriggerFunction của tệp kê khai . Bạn triển khai hàm này để chấp nhận một đối tượng sự kiện hành động và trả về một đối số duy nhất. Card hoặc một mảng Card.

Khi 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 này sẽ gọi và truyền hàm đó đối tượng sự kiện hành động. Thường thì các hàm kích hoạt sử dụng mã nhận dạng thông báo do đối tượng sự kiện này cung cấp để lấy nội dung tin nhắn và các thông tin chi tiết khác bằng Apps Script Dịch vụ Gmail. Ví dụ: trình 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ể hành động dựa trên dữ liệu này để trích xuất thông tin mà nó cần cho giao diện. Ví dụ: tiện ích bổ sung tóm tắt doanh số có thể thu thập doanh số bán hàng từ nội dung thư và sắp xếp chúng theo hiển thị trong một thẻ.

Hàm kích hoạt phải tạo và trả về một mảng Card . Ví dụ: sau đây là một tiện ích bổ sung có một thẻ duy nhất chỉ liệt kê chủ đề 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.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }