Tạo trang chủ cho ứng dụng Google Chat

Trang này giải thích cách tạo trang chủ cho tin nhắn trực tiếp bằng Ứng dụng Google Chat. Trang chủ, còn được gọi là trang chủ ứng dụng trong API Google Chat là một giao diện thẻ tuỳ chỉnh xuất hiện trong thẻ Trang chủ trong số không gian nhắn tin trực tiếp giữa người dùng và ứng dụng Chat.

Thẻ trên màn hình chính của ứng dụng với hai tiện ích.
Hình 1: Ví dụ về trang chủ xuất hiện trong tin nhắn trực tiếp bằng ứng dụng Chat.

Bạn có thể sử dụng trang chủ ứng dụng để chia sẻ các mẹo tương tác với ứng dụng Chat hoặc cho phép người dùng truy cập và sử dụng một dịch vụ hoặc công cụ bên ngoài từ Chat.


Sử dụng Trình tạo thẻ để thiết kế và xem trước giao diện người dùng cũng như tính năng nhắn tin cho ứng dụng Chat:

Mở Trình tạo thẻ

Điều kiện tiên quyết

Node.js

Một ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn tất hướng dẫn bắt đầu nhanh này.

Python

Ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác bằng dịch vụ HTTP, hãy hoàn tất hướng dẫn bắt đầu nhanh này.

Java

Một ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một tương tác bằng ứng dụng Chat bằng dịch vụ HTTP, hãy hoàn thành phần bắt đầu nhanh này.

Apps Script

Ứng dụng Google Chat đã bật các tính năng tương tác. Để tạo một ứng dụng Chat tương tác trong Apps Script, hãy hoàn thành phần bắt đầu nhanh này.

Định cấu hình trang chủ ứng dụng cho ứng dụng Chat

Để hỗ trợ trang chủ ứng dụng, bạn phải định cấu hình ứng dụng Chat để nhận APP_HOME sự kiện tương tác, Ứng dụng Chat của bạn sẽ nhận được sự kiện này bất cứ khi nào người dùng nhấp vào thẻ Trang chủ trong tin nhắn trực tiếp bằng Ứng dụng Chat.

Để cập nhật chế độ cài đặt cấu hình trong Google Cloud Console, hãy làm như sau:

  1. Trong bảng điều khiển Google Cloud, hãy chuyển đến Trình đơn > Các sản phẩm khác > Google Workspace > Thư viện sản phẩm > Google Chat API.

    Chuyển đến API Google Chat

  2. Nhấp vào Quản lý, rồi nhấp vào thẻ Cấu hình.

  3. Trong phần Tính năng tương tác, hãy chuyển đến phần Chức năng để định cấu hình màn hình chính của ứng dụng:

    1. Đánh dấu vào hộp Nhận tin nhắn 1:1.
    2. Chọn hộp đánh dấu Support App Home (Hỗ trợ trang chủ ứng dụng).
  4. Nếu ứng dụng Chat của bạn sử dụng dịch vụ HTTP, hãy truy cập vào Chế độ cài đặt kết nối và chỉ định điểm cuối cho Trường URL trang chủ của ứng dụng. Bạn có thể sử dụng cùng một URL mà bạn đã chỉ định trong URL điểm cuối HTTP.

  5. Nhấp vào Lưu.

Tạo thẻ màn hình chính của ứng dụng

Khi người dùng mở trang chủ ứng dụng, ứng dụng Chat của bạn phải xử lý sự kiện tương tác APP_HOME bằng cách trả về một thực thể của RenderActions với thao tác điều hướng pushCardCard. Để tạo một trải nghiệm tương tác thì thẻ có thể chứa các tiện ích tương tác như nút hoặc văn bản đầu vào mà ứng dụng Chat có thể xử lý và để trả lời bằng các thẻ bổ sung hoặc một hộp thoại.

Trong ví dụ sau, ứng dụng Chat hiển thị một thẻ trang chủ ứng dụng ban đầu cho biết thời gian tạo thẻ và một nút. Khi người dùng nhấp vào nút đó, ứng dụng Chat sẽ trả về một thẻ đã cập nhật cho thấy thời gian tạo thẻ mới.

Node.js

node/app-home/index.js
app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
/**
 * Process Google Chat events
 *
 * @param event Event from chat.
 * @return GenericJson
 * @throws Exception
 */
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  GoogleAppsCardV1TextParagraph textParagraph = new GoogleAppsCardV1TextParagraph();
  textParagraph.setText("Here is the app home 🏠 It's " + new Date());

  GoogleAppsCardV1Widget textParagraphWidget = new GoogleAppsCardV1Widget();
  textParagraphWidget.setTextParagraph(textParagraph);

  GoogleAppsCardV1Action action = new GoogleAppsCardV1Action();
  action.setFunction("updateAppHome");

  GoogleAppsCardV1OnClick onClick = new GoogleAppsCardV1OnClick();
  onClick.setAction(action);

  GoogleAppsCardV1Button button = new GoogleAppsCardV1Button();
  button.setText("Update app home");
  button.setOnClick(onClick);

  GoogleAppsCardV1ButtonList buttonList = new GoogleAppsCardV1ButtonList();
  buttonList.setButtons(List.of(button));

  GoogleAppsCardV1Widget buttonListWidget = new GoogleAppsCardV1Widget();
  buttonListWidget.setButtonList(buttonList);

  GoogleAppsCardV1Section section = new GoogleAppsCardV1Section();
  section.setWidgets(List.of(textParagraphWidget, buttonListWidget));

  GoogleAppsCardV1Card card = new GoogleAppsCardV1Card();
  card.setSections(List.of(section));

  return card;
}

Apps Script

Triển khai hàm onAppHome được gọi sau tất cả các sự kiện tương tác APP_HOME:

Ví dụ này gửi thông báo thẻ bằng cách quay lại JSON thẻ. Bạn cũng có thể sử dụng dịch vụ thẻ Apps Script.

apps-script/app-home/app-home.gs
/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Phản hồi các lượt tương tác với trang chủ ứng dụng

Nếu thẻ trang chủ ban đầu của ứng dụng chứa các tiện ích tương tác, chẳng hạn như nút hoặc lựa chọn đầu vào, ứng dụng Chat phải xử lý các sự kiện tương tác có liên quan bằng cách trả về một bản sao của RenderActions bằng cách điều hướng updateCard. Để tìm hiểu thêm về cách xử lý quảng cáo tương tác tiện ích, xem Xử lý thông tin do người dùng nhập.

Trong ví dụ trước, thẻ trang chủ ban đầu của ứng dụng có một nút. Bất cứ khi nào người dùng nhấp vào nút, sự kiện tương tác CARD_CLICKED kích hoạt hàm updateAppHome để làm mới thẻ trên màn hình chính của ứng dụng, như minh hoạ trong mã sau:

Node.js

node/app-home/index.js
// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py
def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java
// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

Apps Script

Ví dụ này gửi thông báo thẻ bằng cách trả về JSON thẻ. Bạn cũng có thể sử dụng Dịch vụ thẻ Apps Script.

apps-script/app-home/app-home.gs
/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}

Mở hộp thoại

Ứng dụng Chat cũng có thể phản hồi các hoạt động tương tác trong trang chủ của ứng dụng bằng cách mở hộp thoại.

Hộp thoại có nhiều tiện ích khác nhau.
Hình 3: Hộp thoại nhắc người dùng thêm một người liên hệ.

Để mở một hộp thoại trên trang chủ của ứng dụng, hãy xử lý sự kiện tương tác có liên quan bằng cách trả về renderActions với thành phần điều hướng updateCard chứa Card . Trong ví dụ sau, ứng dụng Chat phản hồi nhấp vào nút trên thẻ trang chủ ứng dụng bằng cách xử lý CARD_CLICKED sự kiện tương tác và mở một hộp thoại:

{ renderActions: { action: { navigations: [{ updateCard: { sections: [{
  header: "Add new contact",
  widgets: [{ "textInput": {
    label: "Name",
    type: "SINGLE_LINE",
    name: "contactName"
  }}, { textInput: {
    label: "Address",
    type: "MULTIPLE_LINE",
    name: "address"
  }}, { decoratedText: {
    text: "Add to favorites",
    switchControl: {
      controlType: "SWITCH",
      name: "saveFavorite"
    }
  }}, { decoratedText: {
    text: "Merge with existing contacts",
    switchControl: {
      controlType: "SWITCH",
      name: "mergeContact",
      selected: true
    }
  }}, { buttonList: { buttons: [{
    text: "Next",
    onClick: { action: { function: "openSequentialDialog" }}
  }]}}]
}]}}]}}}

Để đóng hộp thoại, hãy xử lý các sự kiện tương tác sau:

  • CLOSE_DIALOG: Đóng hộp thoại và quay lại Thẻ trang chủ ứng dụng ban đầu của ứng dụng Chat.
  • CLOSE_DIALOG_AND_EXECUTE: Đóng hộp thoại và làm mới thẻ trang chủ của ứng dụng.

Mã mẫu sau đây sử dụng CLOSE_DIALOG để đóng hộp thoại và quay lại thẻ trang chủ của ứng dụng:

{ renderActions: { action: {
  navigations: [{ endNavigation: { action: "CLOSE_DIALOG" }}]
}}}

Để thu thập thông tin từ người dùng, bạn cũng có thể tạo các hộp thoại tuần tự. Người nhận hãy tìm hiểu cách xây dựng hộp thoại tuần tự, xem Mở và phản hồi hộp thoại.