דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

Node.js

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

Python

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

Java

Apps Script

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

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

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

כדי לעדכן את הגדרות התצורה במסוף Google Cloud:

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

כניסה ל-Google Chat API
לוחצים על Manage (ניהול) ואז לוחצים על הכרטיסייה Configuration (הגדרה).
בקטע תכונות אינטראקטיביות, עוברים לקטע פונקציונליות כדי הגדרת דף הבית של האפליקציה:
1. מסמנים את התיבה קבלת הודעות 1:1.
2. מסמנים את התיבה Support App Home.
אם אפליקציית Chat משתמשת בשירות HTTP, עוברים אל הגדרות החיבור ומציינים נקודת קצה בשדה כתובת ה-URL של דף הבית של האפליקציה. אפשר להשתמש באותה כתובת URL שציינת השדה HTTP endpoint.
לוחצים על שמירה.

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

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

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

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 שמשתמשות בדף הבית של האפליקציה.
פתיחה של תיבות דו-שיח ותשובה להן.

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

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

Node.js

Python

Java

Apps Script

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

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

Node.js

Python

Java

Apps Script

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

Node.js

Python

Java

Apps Script

פתיחה של תיבות דו-שיח

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