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

Google Workspace tiện ích bổ sung 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épGoogle Workspace tiện ích bổ sung tự động hoá các thao tác để phản hồi nội dung tin nhắn, chẳng hạn như hiện, truy xuất hoặc gửi thêm thông tin liên quan đến tin nhắn.

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

Có hai cách để xem giao diện người dùng của thông báo trên tiện ích bổ sung. Cách đầu tiên là mở 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 thông báo.

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

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

Để hỗ trợ người dùng khi đọc thông báo, tiện ích bổ sungGoogle Workspace có thể xác định một trình kích hoạt theo ngữ cảnh trong tệp kê khai. Khi người dùng mở thư Gmail (có tiện ích bổ sung đang mở) đáp ứng các tiêu chí kích hoạt*, trình kích hoạt sẽ kích hoạt. Trình kích hoạt được kích hoạt sẽ thực thi hàm kích hoạt theo ngữ cảnh, hàm này sẽ xây dựng giao diện người dùng bổ sung và trả về để 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 nó.

Trình kích hoạt theo ngữ cảnh được xác định trong tệp kê khai của dự án 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 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ở một thông báo:

{
  ...
  "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 này sẽ gọi hàm này và chuyển hàm đó vào 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ông báo mà đối tượng sự kiện này cung cấp để nhận văn bản thông báo 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 thông báo 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 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ông báo và sắp xếp chúng để 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 đã được tạo. Ví dụ: Dưới đây là tiện ích bổ sung có một thẻ bổ sung chỉ liệt kê chủ đề và người gửi tin nhắn:

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