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

Tiện ích bổ sung của Google Workspace giúp mở rộng Gmail có thể tạo ra một giao diện người dùng khi người dùng đang đọc thư. Điều này cho phép Tiện ích bổ sung của Google Workspace 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 thị, 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 thông báo của tiện ích bổ sung

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

Cả hai trường hợp đều khiến 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 sẽ tạo giao diện người dùng cho thông báo đó và sau đó Gmail sẽ hiển thị cho người dùng.

Xây dựng tiện ích bổ sung 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 thông báo. Hãy nhớ thêm trường điều kiện 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 giúp 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 kết cần thiết để phản hồi hoạt động 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 tin nhắn, các 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 (với tiện ích bổ sung đang mở) đáp ứng các tiêu chí của trình 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 trình kích hoạt theo ngữ cảnh tạo giao diện người dùng 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.

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 của bạn. Định nghĩa trình kích hoạt cho Gmail biết hàm kích hoạt nào kích hoạt theo đ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 không có điều kiện để gọi hàm trình 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 trình kích hoạt theo ngữ cảnh phải có một hàm trình 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 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 trình kích hoạt theo ngữ cảnh kích hoạt cho một thư nhất định trên Gmail, hàm đó sẽ gọi hàm này và truyền hàm đó là 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ã nhận dạng thông báo do đối tượng sự kiện này cung cấp để lấy 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ể thao tác 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 doanh số bán hàng có thể thu thập doanh số bán hàng trong nội dung thông báo và sắp xếp chúng để hiển thị trong 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 tạo tiện ích bổ sung bằng 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];
  }