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

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

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

รูปที่ 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 ให้คลิกเมนู > API และบริการ > API และบริการที่เปิดใช้ > Google Chat API > การกำหนดค่า ไปที่การกำหนดค่า Chat API
2. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้ไปที่ส่วนฟังก์ชันการทำงาน แล้วเลือกรองรับหน้าแรกของแอป
3. หากแอป Chat ใช้บริการ HTTP ให้ไปที่การตั้งค่าการเชื่อมต่อและระบุปลายทางสำหรับช่องURL หน้าแรกของแอป คุณสามารถใช้ URL เดียวกันกับที่ระบุในช่องURL ของปลายทาง HTTP ได้
4. คลิกบันทึก

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

ดูตัวอย่างเพิ่มเติมได้ที่ตัวอย่างแอป Google Chat

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

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

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

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

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

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

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

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

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

ดูใน GitHub

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

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

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

• ดูตัวอย่างแอปใน Chat ที่ใช้หน้าแรกของแอป
• เปิดและตอบกลับกล่องโต้ตอบ