Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Trang chủ

Trang chủ là một tính năng của tiện ích bổ sung Google Workspace, cho phép bạn xác định một hoặc nhiều thẻ không theo bối cảnh. Thẻ không theo bối cảnh sẽ hiển thị giao diện người dùng khi người dùng không ở trong một bối cảnh cụ thể, chẳng hạn như khi xem hộp thư đến của Gmail mà không có thư hoặc bản nháp nào đang mở.

Trang chủ cho phép bạn hiển thị nội dung không theo bối cảnh, tương tự như các ứng dụng Google trong bảng điều khiển bên truy cập nhanh (Google Keep, Lịch Google và Google Tasks). Trang chủ cũng có thể là nơi bắt đầu ban đầu khi người dùng mở tiện ích bổ sung của bạn lần đầu tiên và hữu ích cho việc hướng dẫn người dùng mới cách tương tác với tiện ích bổ sung của bạn.

Xác định trang chủ cho tiện ích bổ sung bằng cách chỉ định trang chủ đó trong tệp kê khai dự án và triển khai một hoặc nhiều hàm homepageTrigger (xem phần Cấu hình trang chủ). Nếu tiện ích bổ sung của bạn mở rộng Google Chat, thì trang chủ của tiện ích đó sẽ xuất hiện trong thẻ Trang chủ của tin nhắn trực tiếp 1:1 với ứng dụng Chat và được định cấu hình trong Google Cloud Console thay vì tệp kê khai (xem phần Định cấu hình trang chủ cho Chat).

Bạn có thể có nhiều trang chủ, mỗi trang chủ dành cho một ứng dụng lưu trữ mà tiện ích bổ sung của bạn mở rộng. Bạn cũng có thể xác định một trang chủ mặc định chung duy nhất được dùng trong những máy chủ lưu trữ mà bạn chưa chỉ định trang chủ tuỳ chỉnh.

Trang chủ của tiện ích bổ sung sẽ xuất hiện trong những trường hợp sau:

Khi tiện ích bổ sung được mở lần đầu tiên trong ứng dụng lưu trữ (sau khi được uỷ quyền) hoặc khi người dùng mở thẻ Trang chủ trong tin nhắn trực tiếp 1:1 với ứng dụng Chat của bạn trong Chat.
Khi người dùng chuyển từ ngữ cảnh theo bối cảnh sang ngữ cảnh không theo bối cảnh trong khi tiện ích bổ sung đang mở. Ví dụ: từ việc chỉnh sửa một sự kiện trên Lịch cho đến Lịch chính.
Khi người dùng nhấp vào nút quay lại đủ số lần để đẩy mọi thẻ khác ra khỏi ngăn xếp nội bộ.
Khi một hoạt động tương tác trên giao diện người dùng trong thẻ không theo ngữ cảnh dẫn đến lệnh gọi Navigation.popToRoot.

Bạn nên thiết kế trang chủ. Nếu bạn không xác định thẻ nào, thì một thẻ chung chứa tên tiện ích bổ sung của bạn sẽ được dùng bất cứ khi nào người dùng chuyển đến trang chủ.

Cấu hình trang chủ

Tiện ích bổ sung của Google Workspace sử dụng trường addOns.common.homepageTrigger để định cấu hình nội dung mặc định trên trang chủ (không theo bối cảnh) của tiện ích bổ sung cho các ứng dụng lưu trữ trong tệp kê khai của tiện ích bổ sung:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

runFunction: Tên của hàm Google Apps Script mà khung tiện ích bổ sung Google Workspace gọi để kết xuất thẻ tiện ích bổ sung trên trang chủ. Hàm này là hàm kích hoạt trang chủ. Hàm này phải tạo và trả về một mảng các đối tượng Card tạo nên giao diện người dùng trang chủ. Nếu có nhiều thẻ được trả về, ứng dụng lưu trữ sẽ hiển thị tiêu đề thẻ trong một danh sách mà người dùng có thể chọn (xem phần Trả về nhiều thẻ).
enabled: Liệu có nên bật thẻ trang chủ cho phạm vi này hay không. Trường này không bắt buộc và mặc định là true. Nếu bạn đặt giá trị này thành false, các thẻ trên trang chủ sẽ bị vô hiệu hoá đối với tất cả các máy chủ lưu trữ (trừ phi bị ghi đè đối với máy chủ lưu trữ đó; hãy xem cấu hình dành riêng cho máy chủ lưu trữ).

Để máy chủ lưu trữ sử dụng trang chủ chung, cả addOns.common.homepageTrigger và tài nguyên cấp cao nhất của máy chủ lưu trữ đều phải có trong tệp kê khai của tiện ích bổ sung. Ví dụ: nếu addOns.gmail không có trong tệp kê khai, thì tiện ích bổ sung sẽ bị vô hiệu hoá đối với Gmail và sẽ không hiển thị trang chủ hoặc chức năng khác trong máy chủ lưu trữ đó.

Ngoài cấu hình chung, các chế độ ghi đè trên mỗi máy chủ có cấu trúc giống hệt nhau có trong cấu hình của từng ứng dụng lưu trữ, tại addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger và các trình kích hoạt dành riêng cho máy chủ lưu trữ khác.

Ví dụ sau đây cho thấy một tệp kê khai trong đó một trình kích hoạt trang chủ chung được xác định nhưng bị ghi đè bằng các hàm tuỳ chỉnh cho Lịch và Drive, đồng thời bị vô hiệu hoá cho Gmail. Trong cấu hình này, hàm buildHomePage chung không bao giờ thực thi vì hàm này bị ghi đè hoặc máy chủ lưu trữ bị vô hiệu hoá.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

Đoạn trích tệp kê khai sau đây tương đương với ví dụ trước, mặc dù homepageTrigger mặc định và cấu hình Gmail bị bỏ qua:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

Bạn không bắt buộc phải điền vào bất kỳ phần nào trong số homepageTrigger. Giao diện người dùng xuất hiện cho một tiện ích bổ sung trong một sản phẩm lưu trữ phụ thuộc vào sự hiện diện của trường tệp kê khai tương ứng và liệu có homepageTrigger được liên kết hay không. Ví dụ sau đây cho thấy những hàm kích hoạt tiện ích bổ sung nào được thực thi để tạo giao diện người dùng trang chủ cho các cấu hình tệp kê khai khác nhau:

Sơ đồ minh hoạ quy trình thực thi hàm kích hoạt trang chủ của tiện ích bổ sung

Định cấu hình trang chủ cho Chat

Không giống như các ứng dụng lưu trữ khác của Google Workspace, những tiện ích bổ sung mở rộng Chat không hiển thị trang chủ trong bảng điều khiển truy cập nhanh ở bên phải và không sử dụng addOns.common.homepageTrigger trong tệp kê khai. Thay vào đó, Chat sẽ hiển thị trang chủ của bạn dưới dạng thẻ trong thẻ Trang chủ của tin nhắn trực tiếp 1:1 với ứng dụng Chat.

Cách bật và định cấu hình một điều kiện kích hoạt Trang chủ ứng dụng cho tiện ích bổ sung Chat trong Cloud Console:

Trong bảng điều khiển Google Cloud, hãy chuyển đến Trình đơn > API và dịch vụ > API và dịch vụ đã bật > API Google Chat > Cấu hình.

Chuyển đến phần Cấu hình Google Chat API
Trong phần Tính năng tương tác, hãy nhớ bật chế độ Bật tính năng tương tác, rồi đánh dấu vào hộp Hỗ trợ Trang chủ của ứng dụng.
Trong phần Connection settings > Triggers (Cài đặt kết nối > Điều kiện kích hoạt), hãy chỉ định trình xử lý Trang chủ ứng dụng trong trường App home (Trang chủ ứng dụng) dựa trên cấu trúc tiện ích bổ sung của bạn:
- HTTP: Nhập URL điểm cuối HTTPS xử lý các yêu cầu Trang chủ ứng dụng (hoặc để trống để URL điểm cuối HTTP chung của bạn nhận được tất cả các sự kiện).
- Google Apps Script: Nhập tên của hàm callback Google Apps Script tạo và trả về thẻ trang chủ của bạn (mặc định là onAppHome).
Nhấp vào Lưu.

Khi người dùng mở thẻ Trang chủ của một tin nhắn trực tiếp bằng ứng dụng Chat của bạn, Chat sẽ gửi một sự kiện kích hoạt Trang chủ của ứng dụng đến điểm cuối hoặc hàm của bạn. Để hiển thị trang chủ, hãy trả về một đối tượng RenderActions có thao tác điều hướng pushCard (hoặc sử dụng updateCard khi cập nhật trang chủ để phản hồi việc nhấp vào một nút trong thẻ trang chủ):

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Google Apps Script

function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Manage your settings and view your dashboard here.')))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Để biết thêm thông tin chi tiết về cách xử lý các điều kiện kích hoạt Chat, trả về các thao tác và tạo thẻ Trang chủ của ứng dụng, hãy xem phần Gửi và cập nhật thẻ Trang chủ của ứng dụng và Nhận và phản hồi hoạt động tương tác của người dùng.

Đối tượng sự kiện trên trang chủ

Khi được gọi, hàm kích hoạt trang chủ (runFunction) hoặc điểm cuối Trang chủ của ứng dụng được mô tả trước đó sẽ được truyền một đối tượng sự kiện chứa dữ liệu từ ngữ cảnh gọi.

Các đối tượng sự kiện trên trang chủ không bao gồm thông tin về tiện ích hoặc thông tin theo bối cảnh. Thông tin được truyền bao gồm các trường đối tượng sự kiện chung sau đây:

commonEventObject.clientPlatform
commonEventObject.hostApp
commonEventObject.userLocale và commonEventObject.userTimezone (xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thông tin về quy định hạn chế).

Trong Chat, đối tượng sự kiện Trang chủ của ứng dụng cũng bao gồm trường chat có thông tin về người dùng và thời gian tương tác:

chat.user: Người dùng Chat đã mở thẻ Trang chủ.
chat.eventTime: Dấu thời gian khi người dùng mở thẻ Trang chủ.

Hãy xem Đối tượng sự kiện để biết thêm thông tin.

Các thẻ không theo bối cảnh khác

Giao diện người dùng của tiện ích bổ sung có thể chứa các thẻ bổ sung không theo ngữ cảnh và không phải là trang chủ. Ví dụ: trang chủ của bạn có thể có một nút mở thẻ "Cài đặt" để điều chỉnh chế độ cài đặt của tiện ích bổ sung (những chế độ cài đặt này thường độc lập với bối cảnh).

Thẻ không theo bối cảnh được tạo giống như mọi thẻ khác; điểm khác biệt duy nhất là hành động hoặc sự kiện nào tạo và hiển thị thẻ. Hãy xem phần Phương thức điều hướng để biết thông tin chi tiết về cách tạo hiệu ứng chuyển đổi giữa các thẻ.

Trang chủ Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.