איך יוצרים דף בית לאפליקציית Google Chat

הדף הזה מסביר איך לבנות דף בית אפליקציית Google Chat. דף הבית של האפליקציה הוא ממשק כרטיסים שניתן להתאים אישית שאפליקציית Chat שולחת למשתמש כשהוא פותח הודעה עם אפליקציית Chat.

לדוגמה, אפשר: להגדיר את ההודעה של כרטיס הבית של האפליקציה כך שתכלול טיפים לאינטראקציה עם אפליקציית Chat משתמשת פקודות דרך שורת הפקודות. למשתמשי הקצה, דף הבית של האפליקציה זמינה בצ'אט אישי של אפליקציית Chat רק אם מפעיל אפליקציות מפעיל את התכונה.

---

אתם יכולים להשתמש בכלי ליצירת כרטיסים כדי לעצב הודעות של כרטיסי JSON ולהציג אותן בתצוגה מקדימה בשביל אפליקציות ל-Chat:

לפתיחת הכלי ליצירת כרטיסים

---

דרישות מוקדמות

Python

אפליקציית Google Chat שמופעלת בה תכונות אינטראקטיביות. כדי ליצור להשתמש בשירות HTTP באפליקציית Chat האינטראקטיבית. במדריך למתחילים מוסבר איך עושים את זה.

Apps Script

אפליקציית Google Chat שמופעלת בה תכונות אינטראקטיביות. כדי ליצור כדי להשתמש באפליקציית Chat האינטראקטיבית ב-Apps Script, צריך להשלים את המדריך למתחילים.

Node.js

אפליקציית Google Chat שמופעלת בה תכונות אינטראקטיביות. כדי ליצור להשתמש בשירות HTTP באפליקציית Chat האינטראקטיבית. במדריך למתחילים מוסבר איך עושים את זה.

Java

אפליקציית Google Chat שמופעלת בה תכונות אינטראקטיביות. כדי ליצור להשתמש בשירות HTTP באפליקציית Chat האינטראקטיבית. במדריך למתחילים מוסבר איך עושים את זה.

הגדרה של Chat API

כדי לתמוך בדף הבית של האפליקציה, צריך לעדכן את ההגדרה של Chat API במסוף Google Cloud.

Python

1. במסוף Google Cloud, נכנסים אל תפריט > עוד מוצרים > Google Workspace > ספריית המוצרים > Google Chat API.

   כניסה ל-Google Chat API

2. לוחצים על Manage (ניהול) ואז לוחצים על הכרטיסייה Configuration (הגדרה).

3. מסמנים את התיבה Support App Home.

4. בשדה כתובת ה-URL של דף הבית של האפליקציה, מוסיפים כתובת URL. בדרך כלל הערך הזה זהה בתור כתובת ה-URL של האפליקציה. כתובת ה-URL הזו נקראת APP_HOME אירועים.

5. לוחצים על שמירה.

Apps Script

1. במסוף Google Cloud, נכנסים אל תפריט > עוד מוצרים > Google Workspace > ספריית המוצרים > Google Chat API.

   כניסה ל-Google Chat API

2. לוחצים על Manage (ניהול) ואז לוחצים על הכרטיסייה Configuration (הגדרה).

3. מסמנים את התיבה Support App Home.

4. לוחצים על שמירה.

Node.js

1. במסוף Google Cloud, נכנסים אל תפריט > עוד מוצרים > Google Workspace > ספריית המוצרים > Google Chat API.

   כניסה ל-Google Chat API

2. לוחצים על Manage (ניהול) ואז לוחצים על הכרטיסייה Configuration (הגדרה).

3. מסמנים את התיבה Support App Home.

4. בשדה כתובת ה-URL של דף הבית של האפליקציה, מוסיפים כתובת URL. בדרך כלל הערך הזה זהה בתור כתובת ה-URL של האפליקציה. כתובת ה-URL הזו נקראת APP_HOME אירועים.

5. לוחצים על שמירה.

Java

1. במסוף Google Cloud, נכנסים אל תפריט > עוד מוצרים > Google Workspace > ספריית המוצרים > Google Chat API.

   כניסה ל-Google Chat API

2. לוחצים על Manage (ניהול) ואז לוחצים על הכרטיסייה Configuration (הגדרה).

3. מסמנים את התיבה Support App Home.

4. בשדה כתובת ה-URL של דף הבית של האפליקציה, מוסיפים כתובת URL. בדרך כלל הערך הזה זהה בתור כתובת ה-URL של האפליקציה. כתובת ה-URL הזו נקראת APP_HOME אירועים.

5. לוחצים על שמירה.

דף הבית של האפליקציה ב-Build

דוגמאות נוספות כלולות בדוגמאות לאפליקציות של Google Chat.

כרטיס הבית של האפליקציה מופעל כשמשתמש פותח צ'אט אישי אפשר לעדכן את אפליקציית Chat בתשובה של אירוע אינטראקטיבי, כמו לחיצה על לחצן, שליחת טופס או סגירת תיבת דו-שיח.

בדוגמה הבאה, אפליקציית Chat מציגה כרטיס בית ראשוני של האפליקציה שמציג את השעה שבה נוצר הכרטיס לחצן. כשמשתמש לוחץ על הלחצן, אפליקציית Chat מחזירה כרטיס מעודכן שמציג את השעה שבה נוצר הכרטיס המעודכן.

יצירת הכרטיס הראשוני לדף הבית של האפליקציה

כדי ליצור את דף הבית של האפליקציה, אפליקציית Chat צריכה לעמוד בדרישות הבאות: APP_HOME אירועי אינטראקציה ומחזירים מופע של RenderActions עם ניווט pushCard.

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

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

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

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

הצגת הקוד ב-GitHub

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

איך לעדכן כרטיס בית של אפליקציה

אם כרטיס הבית של האפליקציה הראשונית מכיל ווידג'טים אינטראקטיביים כמו לחצנים או אפשרויות קלט שבחרת, אפליקציית Chat צריכה לטפל את אירועי האינטראקציה הקשורים באמצעות החזרת מופע של RenderActions עם ניווט updateCard. למידע נוסף על טיפול באינטראקטיביות ווידג'טים, עיבוד מידע שמשתמשים מזינים.

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()
  }]}}}

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()
  }]}}};
}

Node.js

node/app-home/index.js

הצגת הקוד ב-GitHub

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

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;
}

מגבלות

באופן כללי, navigation הוא לא זמין לאפליקציות צ'אט. אי אפשר להחזיר ערימה של כרטיסים. רק pushCard (לתגובה ראשונית) ו-updateCard (לעדכונים) זמין לאפליקציות צ'אט.

נושאים קשורים

• הצגת דוגמאות של אפליקציות ל-Chat בדף הבית של האפליקציות.

• כדי לפתוח תיבת דו-שיח, צריך להשתמש באינטראקציה OPEN_DIALOG. לקבלת מידע נוסף, לראות פותחים תיבת דו-שיח בתגובה לכרטיס הבית של האפליקציה.

• כדי לסגור תיבת דו-שיח, אפשר להשתמש באינטראקציה CLOSE_DIALOG כדי לסגור אותה. ולחזור לכרטיס הבית של האפליקציה או להשתמש ב-CLOSE_DIALOG_EXECUTE כדי לסגור את תיבת הדו-שיח ולרענן את כרטיס דף הבית של האפליקציה. עבור מידע נוסף: מענה לתיבת דו-שיח עם הכרטיס הראשי של האפליקציה.

• דוגמה לאופן השימוש בדף הבית של האפליקציה זמינה במאמר אפליקציית Chat לניהול בעיות ב-Codelab אתם יכולים ליצור אפליקציות ל-Google Chat בעזרת Gemini.