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

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

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

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


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

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

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

Node.js

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ หากต้องการสร้างแอป Chat แบบอินเทอร์แอกทีฟโดยใช้บริการ HTTP ให้ทําตามการเริ่มต้นใช้งานอย่างรวดเร็วนี้

Python

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ หากต้องการสร้างแอป Chat แบบอินเทอร์แอกทีฟโดยใช้บริการ HTTP ให้ทําตามการเริ่มต้นใช้งานอย่างรวดเร็วนี้

Java

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ หากต้องการสร้างแอป Chat แบบอินเทอร์แอกทีฟโดยใช้บริการ HTTP ให้ทําตามการเริ่มต้นใช้งานอย่างรวดเร็วนี้

Apps Script

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ หากต้องการสร้าง แอปใน Chat แบบอินเทอร์แอกทีฟใน Apps Script ให้ทำตามการเริ่มต้นอย่างรวดเร็วนี้ให้เสร็จสมบูรณ์

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

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

หากต้องการอัปเดตการตั้งค่าการกำหนดค่าในคอนโซล Google Cloud ให้ทำดังนี้

  1. ในคอนโซล Google Cloud ให้ไปที่เมนู > ผลิตภัณฑ์เพิ่มเติม > Google Workspace > คลังผลิตภัณฑ์ > Google Chat API

    ไปที่ Google Chat API

  2. คลิกจัดการ แล้วคลิกแท็บการกําหนดค่า

  3. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้ไปที่ส่วนฟังก์ชันการทำงานเพื่อกำหนดค่าหน้าแรกของแอป ดังนี้

    1. เลือกช่องทําเครื่องหมายรับข้อความแบบ 1:1
    2. เลือกช่องทําเครื่องหมายหน้าแรกของแอปการสนับสนุน
  4. หากแอป Chat ใช้บริการ HTTP ให้ไปที่การตั้งค่าการเชื่อมต่อ แล้วระบุปลายทางสำหรับช่องURL หน้าแรกของแอป คุณใช้ URL เดียวกับที่ระบุในช่อง URL ปลายทางของ HTTP ได้

  5. คลิกบันทึก

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

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

ในตัวอย่างต่อไปนี้ แอป Chat จะแสดงการ์ดหน้าแรกของแอปเริ่มต้นที่แสดงเวลาที่สร้างการ์ดและปุ่ม เมื่อผู้ใช้คลิกปุ่ม แอป Chat จะแสดงการ์ดที่อัปเดตแล้วซึ่งแสดงเวลาที่สร้างการ์ดที่อัปเดต

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

ใช้ฟังก์ชัน onAppHome ที่เรียกใช้หลังจากเหตุการณ์การโต้ตอบ APP_HOME ทั้งหมด ดังนี้

ตัวอย่างนี้ส่งข้อความการ์ดโดยแสดงผล JSON ของการ์ด นอกจากนี้คุณยังใช้บริการการ์ด 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"
      }}
    }]}}
  ]}]};
}

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

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

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

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

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

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

เปิดกล่องโต้ตอบ

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

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

หากต้องการเปิดกล่องโต้ตอบจากหน้าแรกของแอป ให้ประมวลผลเหตุการณ์การโต้ตอบที่เกี่ยวข้องโดยแสดงผล renderActions ที่มีการนำทาง updateCard ซึ่งมีออบเจ็กต์ Card ในตัวอย่างต่อไปนี้ แอป Chat จะตอบสนองต่อการคลิกปุ่มจากการ์ดหน้าแรกของแอปด้วยการประมวลผลเหตุการณ์การโต้ตอบ CARD_CLICKED และเปิดกล่องโต้ตอบ

{ 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" }}
  }]}}]
}]}}]}}}

หากต้องการปิดกล่องโต้ตอบ ให้ประมวลผลเหตุการณ์การโต้ตอบต่อไปนี้

  • CLOSE_DIALOG: ปิดกล่องโต้ตอบและกลับไปที่การ์ดหน้าแรกของแอป Chat
  • CLOSE_DIALOG_AND_EXECUTE: ปิดกล่องโต้ตอบและรีเฟรชการ์ดหน้าแรกของแอป

ตัวอย่างโค้ดต่อไปนี้ใช้ CLOSE_DIALOG เพื่อปิดกล่องโต้ตอบและกลับไปที่การ์ดหน้าแรกของแอป

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

หากต้องการรวบรวมข้อมูลจากผู้ใช้ คุณยังสร้างกล่องโต้ตอบตามลำดับได้ด้วย หากต้องการดูวิธีสร้างกล่องโต้ตอบตามลำดับ โปรดดูหัวข้อเปิดและตอบกลับกล่องโต้ตอบ