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

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

איור 1: דוגמה לדף הבית שמופיע בהודעות ישירות עם אפליקציה ל-Chat.

בניגוד לאפליקציות אחרות של Google Workspace, תוספים שמרחיבים את Chat לא מציגים דף בית בחלונית הגישה המהירה בצד שמאל, ולא משתמשים ב-addOns.common.homepageTrigger במניפסט. במקום זאת, דף הבית מוצג ב-Chat ככרטיס בכרטיסייה דף הבית בצ'אט ישיר 1:1 עם אפליקציית Chat, והוא מוגדר במסוף Google Cloud.

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

---

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

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

---

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

HTTP

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

הערה: דוגמאות הקוד במדריך הזה נכתבו להפעלה כפונקציית Google Cloud Run ל-Node.js.

Apps Script

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

הגדרת דף הבית של האפליקציה ב-Chat

כדי לתמוך בדף הבית של האפליקציה, מפעילים את האפשרות Support App Home ומגדירים את הטריגר של דף הבית של האפליקציה ב-מסוף Google Cloud. אפליקציית Chat מקבלת אירוע הפעלה של דף הבית של האפליקציה בכל פעם שמשתמש פותח את הכרטיסייה דף הבית בצ'אט ישיר 1:1 עם אפליקציית Chat.

כדי להגדיר את דף הבית של האפליקציה במסוף Google Cloud:

1. במסוף Google Cloud, לוחצים על תפריט > APIs & Services > Enabled APIs & Services > Google Chat API > Configuration.

   מעבר להגדרות של Chat API

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

3. בקטע הגדרות חיבור > טריגרים, מציינים את ה-handler של דף הבית של האפליקציה בשדה דף הבית של האפליקציה בהתאם לארכיטקטורה של אפליקציית Chat:

   • ‫HTTP: מזינים את כתובת ה-URL של נקודת הקצה מסוג HTTPS שמטפלת בבקשות של דף הבית של האפליקציה (או בוחרים באפשרות Use common HTTP endpoint URL for all triggers כדי שכל האירועים יתקבלו בכתובת ה-URL המשותפת של נקודת הקצה מסוג HTTP).
   • ‫Google Apps Script: מזינים את שם פונקציית הקריאה החוזרת של Google Apps Script שיוצרת ומחזירה את כרטיס דף הבית (ברירת המחדל היא onAppHome).

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

טיפול באובייקט של אירוע App Home

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

בניגוד לאירועים של אינטראקציה עם מרחב או עם הודעה, אובייקט האירוע הראשוני של דף הבית של האפליקציה לא כולל מטען ייעודי (payload) של אינטראקציה עם איחוד (למשל messagePayload). הוא כולל את השדות הבאים:

• ‫commonEventObject: כולל clientPlatform,‏ hostApp ("CHAT"),‏ userLocale ו-userTimezone.
• ‫chat.user: משתמש Chat שפתח את הכרטיסייה דף הבית.
• ‫chat.eventTime: חותמת הזמן שבה המשתמש פתח את הכרטיסייה דף הבית.

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

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

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 יכולה גם להגיב לאינטראקציות במרכז האפליקציות על ידי פתיחת תיבות דו-שיח.

איור 2: תיבת דו-שיח שמופיעה למשתמש ומבקשת ממנו להוסיף איש קשר.

במאמר פתיחת תיבות דו-שיח אינטראקטיביות מוסבר איך לפתוח, לעדכן ולסגור תיבות דו-שיח באמצעות RenderActions (pushCard, updateCard ו-endNavigation: "CLOSE_DIALOG").

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

• קבלת אינטראקציות של משתמשים ושליחת תגובות אליהן
• פתיחת תיבות דו-שיח אינטראקטיביות
• קריאת נתונים שהמשתמשים הזינו בטפסים בכרטיסים
• דוגמאות לאפליקציות ל-Chat

אפליקציות ל-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 navigation:

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

בדוגמה הזו, הודעת הכרטיס נשלחת על ידי החזרת JSON של הכרטיס. אפשר גם להשתמש בשירות הכרטיסים של Apps Script.

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

הצגת הקוד ב-GitHub

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