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

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

    מעבר אל Google Chat API

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

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

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

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

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

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

בדוגמה הבאה, אפליקציית 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

בדוגמה הזו נשלחת הודעה בכרטיס על ידי החזרת 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" }}]
}}}

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