Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

สร้างหน้าแรกสำหรับแอป Google Chat

หน้านี้อธิบายวิธีสร้างหน้าแรกสำหรับข้อความส่วนตัวด้วยแอป Google Chat ของคุณ หน้าแรกซึ่งเรียกว่าหน้าแรกของแอปใน Google Chat API คืออินเทอร์เฟซการ์ดที่ปรับแต่งได้ซึ่งจะปรากฏในแท็บหน้าแรกของพื้นที่ข้อความส่วนตัวแบบ 1:1 ระหว่างผู้ใช้กับแอปใน Chat

การ์ดหน้าแรกของแอปที่มีวิดเจ็ต 2 รายการ — **รูปที่ 1**: ตัวอย่างหน้าแรกที่ปรากฏในข้อความส่วนตัวกับแอปใน Chat

ส่วนเสริมที่ขยาย Chat จะไม่แสดงหน้าแรกในแผงเข้าถึงด่วนทางด้านขวาและจะไม่ใช้ addOns.common.homepageTrigger ในไฟล์ Manifest ซึ่งแตกต่างจากแอปพลิเคชันโฮสต์อื่นๆ ของ Google Workspace แต่ Chat จะแสดงหน้าแรกเป็นการ์ดในแท็บหน้าแรก ของข้อความส่วนตัวแบบ 1:1 กับแอป Chat และได้รับการกำหนดค่าในคอนโซล Google Cloud

คุณสามารถใช้หน้าแรกของแอปเพื่อแชร์เคล็ดลับในการโต้ตอบกับ แอป Chat แสดงแดชบอร์ดผู้ใช้ที่ปรับเปลี่ยนในแบบของคุณ หรือ ให้ผู้ใช้เข้าถึงและกำหนดค่าบริการหรือเครื่องมือภายนอกจาก Chat ได้

ใช้เครื่องมือสร้างการ์ดเพื่อออกแบบและแสดงตัวอย่างการรับส่งข้อความและอินเทอร์เฟซผู้ใช้สำหรับแอป Chat โดยทำดังนี้

เปิดเครื่องมือสร้างการ์ด

ข้อกำหนดเบื้องต้น

HTTP

แอป Google Chat ที่รับและตอบสนองต่อการโต้ตอบของผู้ใช้ หากต้องการสร้าง ให้ทำตามการเริ่มต้นใช้งาน HTTP

Apps Script

แอป Google Chat ที่รับและตอบสนองต่อการโต้ตอบของผู้ใช้ หากต้องการสร้าง ให้ทำตามการเริ่มต้นใช้งาน Apps Script อย่างรวดเร็ว

กำหนดค่าหน้าแรกของแอปสำหรับแอป Chat

หากต้องการรองรับ App Home ให้เปิดใช้รองรับ App Home และกำหนดค่าApp Home ทริกเกอร์ใน คอนโซล Google Cloud แอป Chat จะได้รับเหตุการณ์ทริกเกอร์หน้าแรกของแอป ทุกครั้งที่ผู้ใช้เปิดแท็บหน้าแรกในข้อความส่วนตัวแบบ 1:1 กับแอป Chat

วิธีกำหนดค่า App Home ในคอนโซล Google Cloud

ในคอนโซล Google Cloud ให้ไปที่เมนู > API และบริการ > API และบริการที่เปิดใช้ > Google Chat API > การกำหนดค่า

ไปที่การกำหนดค่า Chat API
ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้ตรวจสอบว่าได้เปิดเปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟแล้ว จากนั้นในส่วนฟังก์ชันการทำงาน ให้เลือกช่องทําเครื่องหมายรองรับหน้าแรกของแอป
ในส่วนการตั้งค่าการเชื่อมต่อ > ทริกเกอร์ ให้ระบุตัวแฮนเดิลหน้าแรกของแอปในช่องหน้าแรกของแอปตาม สถาปัตยกรรมของแอป Chat
- HTTP: ป้อน URL ของปลายทาง HTTPS ที่จัดการคำขอหน้าแรกของแอป (หรือเลือกใช้ URL ของปลายทาง HTTP ทั่วไปสำหรับทริกเกอร์ทั้งหมดเพื่อให้ URL ของปลายทาง HTTP ทั่วไปรับเหตุการณ์ทั้งหมด)
- Google Apps Script: ป้อนชื่อฟังก์ชัน Callback ของ Google Apps Script ที่สร้างและแสดงการ์ดหน้าแรก (ค่าเริ่มต้นคือ onAppHome)
คลิกบันทึก

จัดการออบเจ็กต์เหตุการณ์หน้าแรกของแอป

เมื่อผู้ใช้เปิดแท็บหน้าแรกของข้อความส่วนตัวแบบ 1:1 กับแอป Chat ของคุณ Chat จะส่งออบเจ็กต์เหตุการณ์ไปยังปลายทางหน้าแรกของแอปหรือฟังก์ชัน Callback

ออบเจ็กต์เหตุการณ์ App Home เริ่มต้น จะไม่มีเพย์โหลดการโต้ตอบแบบรวม (เช่น messagePayload) ซึ่งแตกต่างจากเหตุการณ์การโต้ตอบในพื้นที่หรือข้อความ แต่จะมีฟิลด์ต่อไปนี้

commonEventObject: ประกอบด้วย clientPlatform, hostApp ("CHAT"), userLocale และ userTimezone
chat.user: ผู้ใช้ Chat ที่ เปิดแท็บหน้าแรก
chat.eventTime: การประทับเวลาเมื่อผู้ใช้เปิดแท็บหน้าแรก

สร้างการ์ดหน้าแรกของแอป

เมื่อผู้ใช้เปิดแท็บหน้าแรก ให้จัดการเหตุการณ์ทริกเกอร์หน้าแรกของแอปโดย ส่งคืนออบเจ็กต์ RenderActions ที่มีpushCard การดำเนินการนำทางและ Card หากต้องการสร้างประสบการณ์แบบอินเทอร์แอกทีฟ การ์ดอาจมีวิดเจ็ตแบบอินเทอร์แอกทีฟ เช่น ปุ่มหรือช่องป้อนข้อความ

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                },
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "Refresh",
                        "onClick": {
                          "action": {
                            "function": "https://example.com/updateAppHome"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Builds and returns the App Home card when a user opens the Home tab.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response pushing the homepage card.
 */
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.'))
              .addWidget(
                  CardService.newButtonSet().addButton(
                      CardService.newTextButton()
                          .setText('Refresh')
                          .setOnClickAction(
                              CardService.newAction().setFunctionName(
                                  'updateAppHome')))))
      .build();

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

ตอบสนองต่อการโต้ตอบในหน้าแรกของแอป

หากการ์ดหน้าแรกของแอปมีวิดเจ็ตแบบอินเทอร์แอกทีฟ เช่น ปุ่มหรืออินพุตแบบฟอร์ม การคลิกปุ่มจะส่งออบเจ็กต์เหตุการณ์ที่มี chat.buttonClickedPayload (พร้อมด้วย commonEventObject.parameters และ commonEventObject.formInputs) ไปยังฟังก์ชันการทำงานหรือปลายทางที่กำหนดค่าไว้ของปุ่ม

หากต้องการอัปเดตการ์ดหน้าแรกของแอปเพื่อตอบสนองต่อการโต้ตอบของผู้ใช้ ให้ส่งออบเจ็กต์ RenderActions ที่มีupdateCard การดำเนินการนำทาง ดูข้อมูลเพิ่มเติมเกี่ยวกับการอ่านข้อมูลที่ป้อนในแบบฟอร์มจากวิดเจ็ตแบบอินเทอร์แอกทีฟได้ที่อ่านข้อมูลแบบฟอร์มที่ผู้ใช้ป้อนในบัตร

HTTP

{
  "action": {
    "navigations": [
      {
        "updateCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Last updated: 2026-10-02T23:00:00Z"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Updates the App Home card when a user clicks the Refresh button.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response updating the homepage card.
 */
function updateAppHome(event) {
  const updatedCard = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Last updated: ' + new Date().toTimeString())))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();
}

เปิดกล่องโต้ตอบจากหน้าแรกของแอป

แอป Chat ยังตอบกลับการโต้ตอบใน App Home ได้ด้วยการเปิดกล่องโต้ตอบ

กล่องโต้ตอบที่มีวิดเจ็ตต่างๆ — **รูปที่ 2**: กล่องโต้ตอบที่แจ้งให้ผู้ใช้เพิ่มรายชื่อติดต่อ

ดูวิธีเปิด อัปเดต และปิดกล่องโต้ตอบโดยใช้ RenderActions (pushCard, updateCard และ endNavigation: "CLOSE_DIALOG") ได้ที่ เปิดกล่องโต้ตอบแบบอินเทอร์แอกทีฟ

แอป Chat ที่ไม่ใช่ส่วนเสริม: สร้างหน้าแรกสำหรับแอป Chat

หากคุณดูแลแอป Chat ที่ไม่ใช่ส่วนเสริมของ Google Workspace อยู่ Chat จะส่งAPP_HOMEเหตุการณ์การโต้ตอบ เมื่อผู้ใช้เปิดแท็บหน้าแรก และจะส่งเหตุการณ์การโต้ตอบ CARD_CLICKED หรือ SUBMIT_FORM เมื่อผู้ใช้โต้ตอบกับวิดเจ็ตในการ์ดหน้าแรกของแอป

หากต้องการอัปเกรดแอป Chat ที่ไม่ใช่ส่วนเสริมเป็นเฟรมเวิร์กส่วนเสริมของ Google Workspace โปรดดูหัวข้อแปลงแอป Google Chat เป็นส่วนเสริมของ Google Workspace

สร้างการ์ดหน้าแรกของแอปในแอป Chat ที่ไม่ใช่ส่วนเสริม

ในแอป Chat ที่ไม่ใช่ส่วนเสริม ให้จัดการAPP_HOMEเหตุการณ์การโต้ตอบโดย การส่งคืนการตอบกลับที่มีฟิลด์renderActionsระดับบนสุดพร้อม pushCardการนำทาง

Node.js

node/app-home/index.js

ดูใน GitHub

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

ดูใน GitHub

@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

ดูใน GitHub

// Process Google Chat events
@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() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

Apps Script

ตัวอย่างนี้จะส่งข้อความการ์ดโดยการส่งคืน JSON ของการ์ด คุณยังใช้บริการการ์ด Apps Script ได้ด้วย

apps-script/app-home/app-home.gs

ดูใน GitHub

/**
 * 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"
      }}
    }]}}
  ]}]};
}

ตอบกลับการโต้ตอบในหน้าแรกของแอปในแอป Chat ที่ไม่ใช่ส่วนเสริม

ในแอป Chat ที่ไม่ใช่ส่วนเสริม ให้จัดการเหตุการณ์การโต้ตอบ CARD_CLICKED หรือ SUBMIT_FORM จากการ์ดหน้าแรกของแอปโดยแสดงผลการตอบกลับที่มีฟิลด์ renderActions ระดับบนสุดพร้อมการนำทาง updateCard ดังนี้

Node.js

node/app-home/index.js

ดูใน GitHub

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

Python

python/app-home/main.py

ดูใน GitHub

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

ดูใน GitHub

// 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

apps-script/app-home/app-home.gs

ดูใน GitHub

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

ข้อกำหนดเบื้องต้น

HTTP

Apps Script

กำหนดค่าหน้าแรกของแอปสำหรับแอป Chat

จัดการออบเจ็กต์เหตุการณ์หน้าแรกของแอป

สร้างการ์ดหน้าแรกของแอป

HTTP

Apps Script

ตอบสนองต่อการโต้ตอบในหน้าแรกของแอป

HTTP

Apps Script

เปิดกล่องโต้ตอบจากหน้าแรกของแอป

หัวข้อที่เกี่ยวข้อง

แอป Chat ที่ไม่ใช่ส่วนเสริม: สร้างหน้าแรกสำหรับแอป Chat

สร้างการ์ดหน้าแรกของแอปในแอป Chat ที่ไม่ใช่ส่วนเสริม

Node.js

Python

Java

Apps Script

ตอบกลับการโต้ตอบในหน้าแรกของแอปในแอป Chat ที่ไม่ใช่ส่วนเสริม

Node.js

Python

Java

Apps Script