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

Tiện ích bổ sung 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á những tác vụ phản hồi nội dung tin nhắn, chẳng hạn như hiển thị, truy xuất hoặc gửi thông tin bổ sung liên quan đến tin nhắn.

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

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 đã 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ư.

Trong cả hai trường hợp, tiện ích bổ sung đều 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. Sự kiện kích hoạt cũng sẽ 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 bối cảnh sẽ tạo giao diện người dùng cho tin nhắn đó, 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 nhắn tin vào một 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ổ trợ, bao gồm cả các phạm vi cần thiết cho chức năng nhắn tin. Đừng quên thêm một 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 một hàm kích hoạt theo bối cảnh để tạo giao diện người dùng 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 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 với giao diện người dùng.

Hành động kích hoạt theo bối cảnh

Để hỗ trợ người dùng khi đọc thư, tiện ích bổ sung Google Workspace có thể xác định một điều kiện kích hoạt theo bối cảnh trong tệp kê khai của chúng. Khi người dùng mở một thư Gmail (có tiện ích bổ sung đang mở) đáp ứng tiêu chí kích hoạt*, thì sự kiện kích hoạt sẽ diễn ra. Một điều kiện kích hoạt đã được kích hoạt sẽ thực thi một hàm điều kiện kích hoạt theo bối cảnh. Hàm này 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.

Các điều kiện kích hoạt theo bối cảnh được xác định trong tệp kê khai dự án của tiện ích bổ sung. Định nghĩa về đ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ẽ được kích hoạt trong những đ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 điều kiện kích hoạt onGmailMessageOpen() khi một thông báo được mở:

{
  ...
  "addOns": {

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

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

Mỗi điều kiện kích hoạt theo bối 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 một đối số đối tượng sự kiện thao tác và trả về một đối tượng Card duy nhất hoặc một mảng các đối tượng Card.

Khi một điều kiện kích hoạt theo bối cảnh được kích hoạt cho một thư Gmail nhất định, điều kiện này sẽ gọi hàm này và truyền cho hàm đó một đối tượng sự kiện hành động. 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 nội dung thư và các thông tin chi tiết khác bằ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 dựa 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ụ: nội dung 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];
  }