במדריך הזה מוסבר איך אפליקציות ל-Google Chat יכולות לאסוף ולעבד מידע ממשתמשים באמצעות יצירת קלט של טפסים בממשקים שמבוססים על כרטיסים.
האפליקציות ל-Chat יכולות לבקש מהמשתמשים מידע כדי לבצע פעולות ב-Chat או מחוץ לו, כולל בדרכים הבאות:
- קובעים את ההגדרות. לדוגמה, כדי לאפשר למשתמשים להתאים אישית את הגדרות ההתראות או להגדיר ולהוסיף את האפליקציה ל-Chat למרחב אחד או יותר.
- ליצור או לעדכן מידע באפליקציות אחרות של Google Workspace. לדוגמה, לאפשר למשתמשים ליצור אירוע ביומן Google.
- לאפשר למשתמשים לגשת למשאבים באפליקציות או בשירותי אינטרנט אחרים ולעדכן אותם. לדוגמה, אפליקציה ל-Chat יכולה לעזור למשתמשים לעדכן את הסטטוס של כרטיס תמיכה ישירות ממרחב ב-Chat.
דרישות מוקדמות
HTTP
אפליקציה ל-Google Chat שמקבלת אינטראקציות של משתמשים ומגיבה להן. כדי ליצור פונקציה כזו, צריך להשלים את המדריך למתחילים בנושא HTTP.
Apps Script
אפליקציה ל-Google Chat שמקבלת אינטראקציות של משתמשים ומגיבה להן. כדי ליצור פרויקט, מבצעים את השלבים במדריך למתחילים של Apps Script.
יצירת טפסים באמצעות כרטיסים
כדי לאסוף מידע, אפליקציות ל-Chat מעצבות טפסים ואת הקלט שלהם, ויוצרות מהם כרטיסים. כדי להציג כרטיסים למשתמשים, אפליקציות צ'אט יכולות להשתמש בממשקי הצ'אט הבאים:
- הודעות שמכילות כרטיס אחד או יותר.
- דפי בית, כרטיס שמופיע בכרטיסייה דף הבית בצ'אטים אישיים עם האפליקציה ל-Chat.
- תיבות דו-שיח, שהן כרטיסים שנפתחים בחלון חדש מהודעות ומדפי בית.
אפליקציות צ'אט יכולות ליצור את הכרטיסים באמצעות הווידג'טים הבאים:
ווידג'טים של שדות קלט בטפסים שמבקשים מידע מהמשתמשים. אפשר גם להוסיף אימות לווידג'טים של קלט בטופס, כדי לוודא שהמשתמשים מזינים את המידע בפורמט הנכון. אפליקציות צ'אט יכולות להשתמש בווידג'טים הבאים של קלט בטופס:
- שדות קלט טקסט (
textInput) לפריסה גמישה או טקסט מוצע. - רכיבי קלט לבחירה (
selectionInput) הם רכיבים בממשק המשתמש שאפשר לבחור, כמו תיבות סימון, כפתורי בחירה ותפריטים נפתחים. ווידג'טים של קלט בחירה יכולים גם לאכלס ולהציע פריטים מנתוני Google Workspace (כמו מרחב משותף ב-Chat) או ממקור נתונים דינמי. לפרטים נוספים, עיינו בקטעים הבאים: הוספת תפריט נפתח והוספת תפריט לבחירה מרובה. - בוררי תאריך ושעה (
dateTimePicker) להזנת תאריך ושעה.
- שדות קלט טקסט (
כפתור כדי שהמשתמשים יוכלו לשלוח את הערכים שהם הזינו בכרטיס. אחרי שהמשתמש לוחץ על הכפתור, אפליקציית הצ'אט יכולה לעבד את המידע שהיא מקבלת.
בדוגמה הבאה, כרטיס אוסף פרטים ליצירת קשר באמצעות קלט טקסט, חלונית לבחירת תאריך ושעה וקלט בחירה:
דוגמאות נוספות לווידג'טים אינטראקטיביים שאפשר להשתמש בהם כדי לאסוף מידע מופיעות במאמר עיצוב כרטיס או תיבת דו-שיח אינטראקטיביים.
הוספת תפריט נפתח
כדי להתאים אישית את הפריטים לבחירה או לאפשר למשתמשים לבחור פריט אחד ממקור נתונים דינמי, אפליקציות ל-Chat יכולות להשתמש בתפריטים נפתחים, שהם סוג של ווידג'ט SelectionInput. לדוגמה, בכרטיס הבא מוצג תפריט נפתח שבו המשתמשים יכולים לבחור באופן דינמי מתוך רשימה של אנשי קשר:
אתם יכולים לאכלס פריטים בתפריט נפתח ממקורות הנתונים הבאים:
- נתונים מ-Google Workspace, כולל משתמשים או מרחבים משותפים ב-Chat.
- מקורות נתונים חיצוניים, כמו מסד נתונים רלציוני.
אכלוס פריטים ממקור נתונים של Google Workspace
כדי לאכלס פריטים ממקורות נתונים של Google Workspace, כמו משתמשי Google Workspace, צריך לציין את השדה platformDataSource בתוך אובייקט DataSourceConfig. בניגוד לסוגים אחרים של רכיבי בחירה, אתם משמיטים אובייקטים מסוג SelectionItem, כי הפריטים האלה לבחירה נשלפים באופן דינמי מ-Google Workspace.
הקוד הבא מציג תפריט נפתח של משתמשי Google Workspace:
JSON
{
"sections": [
{
"header": "Section Header",
"widgets": [
{
"selectionInput": {
"name": "contacts",
"type": "DROPDOWN",
"label": "Select contact from organization",
"dataSourceConfigs": [
{
"platformDataSource": {
"commonDataSource": "USER"
},
"minCharactersTrigger": 1
}
]
}
}
]
}
]
}
אכלוס פריטים ממקור נתונים חיצוני
תפריטים נפתחים יכולים גם לאכלס פריטים ממקור נתונים חיצוני או של צד שלישי. כדי להשתמש במקור נתונים חיצוני, מציינים את השדה remoteDataSource בתוך אובייקט DataSourceConfig שמכיל את הפונקציה ששולחת שאילתות ומחזירה פריטים ממקור הנתונים.
כדי לצמצם את הבקשות למקור נתונים חיצוני, אתם יכולים לכלול פריטים מוצעים שמופיעים בתפריט הנפתח לפני שהמשתמשים מקלידים בתפריט. כדי לאכלס פריטים מוצעים ממקור נתונים חיצוני, צריך לציין אובייקטים סטטיים מסוג SelectionItem.
הקוד הבא מציג תפריט נפתח ששולח שאילתה לפריטים ממקור נתונים חיצוני ומאכלס אותם:
JSON
{
"sections": [
{
"header": "Section Header",
"widgets": [
{
"selectionInput": {
"name": "crm_leads",
"type": "DROPDOWN",
"label": "Select CRM Lead",
"dataSourceConfigs": [
{
"remoteDataSource": {
"function": "getCrmLeads"
},
"minCharactersTrigger": 2
}
],
"items": [
{
"text": "Suggested Lead 1",
"value": "lead-1"
}
]
}
}
]
}
]
}
בקטע הצעת פריטים לבחירה מופיעה דוגמה מלאה שמראה איך להחזיר פריטים מוצעים.
הוספת תפריט לבחירת כמה אפשרויות
כדי להתאים אישית את הפריטים לבחירה או לאפשר למשתמשים לבחור פריטים ממקור נתונים דינמי, אפליקציות ל-Chat יכולות להשתמש בתפריטים לבחירה מרובה, שהם סוג של ווידג'ט SelectionInput. לדוגמה, בכרטיס הבא מוצג תפריט לבחירה מרובה שבו המשתמשים יכולים לבחור באופן דינמי מתוך רשימה של אנשי קשר:
אתם יכולים לאכלס פריטים בתפריט לבחירה מרובה ממקורות הנתונים הבאים:
- נתונים מ-Google Workspace, כולל משתמשים או מרחבים משותפים ב-Chat שהמשתמש חבר בהם. בתפריט מופיעים רק פריטים מאותו ארגון ב-Google Workspace.
- מקורות נתונים חיצוניים, כמו מסד נתונים רלציוני. לדוגמה, אתם יכולים להשתמש בתפריטים לבחירה מרובה כדי לעזור למשתמש לבחור מתוך רשימה של לידים למכירות ממערכת לניהול קשרי לקוחות (CRM).
אכלוס פריטים ממקור נתונים של Google Workspace
כדי להשתמש במקורות נתונים של Google Workspace, צריך לציין את השדה platformDataSource בווידג'ט SelectionInput. בניגוד לסוגים אחרים של רכיבי קלט לבחירה, אתם משמיטים אובייקטים מסוג SelectionItem, כי הפריטים האלה לבחירה נשלפים באופן דינמי מ-Google Workspace.
הקוד הבא מציג תפריט לבחירה מרובה של משתמשי Google Workspace.
כדי לאכלס משתמשים, קלט הבחירה מגדיר את commonDataSource ל-USER:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
הקוד הבא מציג תפריט לבחירה מרובה של מרחבים משותפים ב-Chat. כדי לאכלס את המרחבים, קלט הבחירה מציין את השדה hostAppDataSource. בתפריט הבחירה המרובה, הערך של defaultToCurrentSpace מוגדר גם כ-true, כך שהמרחב המשותף הנוכחי הוא ברירת המחדל שנבחרת בתפריט:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
אכלוס פריטים ממקור נתונים חיצוני
תפריטים לבחירה מרובה יכולים גם לאכלס פריטים ממקור נתונים חיצוני או של צד שלישי. כדי להשתמש במקור נתונים חיצוני, מציינים את השדה externalDataSource בווידג'ט SelectionInput שמכיל את הפונקציה ששולחת שאילתות ומחזירה פריטים ממקור הנתונים.
כדי לצמצם את הבקשות למקור נתונים חיצוני, אתם יכולים לכלול פריטים מוצעים שיופיעו בתפריט הבחירה המרובה לפני שהמשתמשים מקלידים בתפריט. לדוגמה, אתם יכולים לאכלס את אנשי הקשר שהמשתמש חיפש לאחרונה. כדי לאכלס פריטים מוצעים ממקור נתונים חיצוני, צריך לציין אובייקטים סטטיים מסוג SelectionItem.
בדוגמת הקוד הבאה מוצג תפריט לבחירה מרובה ששולח שאילתה לפריטים ממקור נתונים חיצוני ומאכלס אותם:
Node.js
מחליפים את FUNCTION_URL בנקודת הקצה של ה-HTTP ששולחת שאילתות למקור הנתונים החיצוני.
Python
מחליפים את FUNCTION_URL בנקודת הקצה של ה-HTTP ששולחת שאילתות למקור הנתונים החיצוני.
Java
מחליפים את FUNCTION_URL בנקודת הקצה של ה-HTTP ששולחת שאילתות למקור הנתונים החיצוני.
Apps Script
בדוגמה הזו, ההודעה נשלחת באמצעות החזרת קובץ JSON של כרטיס. אפשר גם להשתמש בשירות הכרטיסים של Apps Script.
בקטע הצעת פריטים לבחירה מופיעה דוגמה מלאה שמראה איך להחזיר פריטים מוצעים.
קבלת נתונים מווידג'טים אינטראקטיביים
בכל פעם שמשתמשים לוחצים על כפתור, הפעולה של האפליקציה ל-Chat מופעלת עם מידע על האינטראקציה. בשדה commonEventObject של המטען הייעודי (payload) של האירוע, האובייקט formInputs מכיל את הערכים שהמשתמש מזין.
אפשר לאחזר את הערכים מהאובייקט event.commonEventObject.formInputs.WIDGET_NAME, כאשר WIDGET_NAME הוא השדה name שציינתם לווידג'ט.
הערכים מוחזרים כסוג נתונים ספציפי לווידג'ט.
הדוגמה הבאה מציגה חלק מאובייקט של אירוע שבו המשתמש הזין ערכים לכל ווידג'ט:
{
"commonEventObject": { "formInputs": {
"contactName": { "stringInputs": {
"value": ["Kai 0"]
}},
"contactBirthdate": { "dateInput": {
"msSinceEpoch": 1000425600000
}},
"contactType": { "stringInputs": {
"value": ["Personal"]
}}
}}
}
כדי לקבל את הנתונים, אפליקציית הצ'אט מטפלת באובייקט האירוע כדי לקבל את הערכים שהמשתמשים מזינים בווידג'טים. בטבלה הבאה מוסבר איך לקבל את הערך של ווידג'ט נתון של קלט בטופס. בטבלה מוצגים סוג הנתונים שהווידג'ט מקבל, המקום שבו הערך מאוחסן באובייקט של האירוע וערך לדוגמה.
| ווידג'ט של קלט בטופס | סוג נתוני הקלט | ערך קלט מהאובייקט של האירוע | ערך לדוגמה |
|---|---|---|---|
textInput |
stringInputs |
event.commonEventObject.formInputs.contactName.stringInputs.value[0] |
Kai O |
selectionInput |
stringInputs |
כדי לקבל את הערך הראשון או היחיד, event.commonEventObject.formInputs.contactType.stringInputs.value[0] |
Personal |
dateTimePicker שאפשר להזין בו רק תאריכים. |
dateInput |
event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. |
1000425600000 |
אחרי שהאפליקציה ל-Chat מקבלת את הנתונים, היא יכולה:
- בכרטיסים שכוללים תפריט לבחירת כמה אפשרויות, אכלסו או הציעו פריטים על סמך מה שהמשתמש מקליד בתפריט.
- מעבירים את הנתונים לכרטיס אחר, כדי שהמשתמש יוכל לבדוק את המידע או להמשיך לחלק הבא בטופס.
- משיבים למשתמש כדי לאשר שהוא מילא את הטופס בהצלחה.
הצעת פריטים לבחירה
אם הכרטיס מכיל תפריט לבחירת כמה אפשרויות או תפריט נפתח שמאכלס פריטים ממקור נתונים חיצוני, אפליקציית Chat יכולה להציע פריטים על סמך מה שהמשתמשים מקלידים בתפריט. לדוגמה, אם משתמש מתחיל להקליד Atl בתפריט שמאכלס ערים בארצות הברית, האפליקציה ל-Chat יכולה להציע באופן אוטומטי את Atlanta לפני שהמשתמש מסיים להקליד. אפליקציית Chat יכולה להציע עד 100 פריטים.
כדי להציע ולאכלס באופן דינמי פריטים בשדה קלט לבחירה, הווידג'ט SelectionInput בכרטיס צריך לציין פונקציה ששולחת שאילתה למקור הנתונים החיצוני. בתפריטים לבחירה מרובה, מציינים את השדה externalDataSource. בתפריטים נפתחים, מציינים את השדה remoteDataSource בתוך אובייקט DataSourceConfig.
אפשר גם להגדיר את מספר התווים שהמשתמש צריך להקליד לפני שהתפריט יציג הצעות. בתפריטים עם אפשרות לבחירה מרובה, מגדירים את השדה multiSelectMinQueryLength. בתפריטים נפתחים, מגדירים את השדה min_characters_trigger בתוך DataSourceConfig.
כדי להחזיר פריטים מוצעים, הפונקציה צריכה לבצע את הפעולות הבאות:
- לטפל באובייקט של אירוע, שאפליקציית Chat מקבלת כשהמשתמשים מקלידים בתפריט.
- מאובייקט האירוע, מקבלים את הערך שהמשתמש מקליד, שמיוצג בשדה
event.commonEventObject.parameters["autocomplete_widget_query"]. - שולחים שאילתה למקור הנתונים באמצעות ערך הקלט של המשתמש כדי לקבל
SelectionItemsאחד או יותר שאפשר להציע למשתמש. - כדי להחזיר פריטים מוצעים, מחזירים את הפעולה
RenderActionsעם אובייקטmodifyCard.
בדוגמת הקוד הבאה אפשר לראות איך אפליקציה ל-Chat מציעה פריטים באופן דינמי בתפריט לבחירה מרובה בכרטיס. כשהמשתמש מקליד בתפריט, הפונקציה או נקודת הקצה שצוינו בשדה externalDataSource של הווידג'ט שולחות שאילתה למקור נתונים חיצוני ומציעות פריטים שהמשתמש יכול לבחור.
Node.js
מחליפים את FUNCTION_URL בנקודת הקצה של ה-HTTP ששולחת שאילתות למקור הנתונים החיצוני.
Python
מחליפים את FUNCTION_URL בנקודת הקצה של ה-HTTP ששולחת שאילתות למקור הנתונים החיצוני.
Java
מחליפים את FUNCTION_URL בנקודת הקצה של ה-HTTP ששולחת שאילתות למקור הנתונים החיצוני.
Apps Script
בדוגמה הזו, ההודעה נשלחת באמצעות החזרת קובץ JSON של כרטיס. אפשר גם להשתמש בשירות הכרטיסים של Apps Script.
העברת נתונים לכרטיס אחר
אחרי שמשתמש שולח מידע מכרטיס, יכול להיות שתצטרכו להחזיר כרטיסים נוספים כדי לבצע את הפעולות הבאות:
- כדי לעזור למשתמשים למלא טפסים ארוכים יותר, כדאי ליצור קטעים נפרדים.
- תנו למשתמשים אפשרות לראות תצוגה מקדימה של המידע מהכרטיס הראשוני ולאשר אותו, כדי שהם יוכלו לבדוק את התשובות שלהם לפני השליחה.
- לאכלס באופן דינמי את שאר חלקי הטופס. לדוגמה, כדי לבקש מהמשתמשים לקבוע פגישה, אפליקציית Chat יכולה להציג כרטיס ראשוני שמבקש את הסיבה לפגישה, ואז לאכלס כרטיס אחר שמספק זמנים זמינים על סמך סוג הפגישה.
כדי להעביר את הקלט מהכרטיס הראשוני, אפשר ליצור את הווידג'ט button עם actionParameters שמכילים את ה-name של הווידג'ט ואת הערך שהמשתמש מזין, כמו בדוגמה הבאה:
Node.js
מחליפים את הערך FUNCTION_URL בנקודת הקצה (endpoint) של HTTP שמטפלת בלחיצות על הכפתורים.
Python
מחליפים את הערך FUNCTION_URL בנקודת הקצה (endpoint) של HTTP שמטפלת בלחיצות על הכפתורים.
Java
מחליפים את הערך FUNCTION_URL בנקודת הקצה (endpoint) של HTTP שמטפלת בלחיצות על הכפתורים.
Apps Script
בדוגמה הזו, ההודעה נשלחת באמצעות החזרת קובץ JSON של כרטיס. אפשר גם להשתמש בשירות הכרטיסים של Apps Script.
כשמשתמש לוחץ על הכפתור, אפליקציית הצ'אט מקבלת אובייקט של אירוע שממנו אפשר לקבל נתונים.
איך מגיבים לטופס שנשלח
אחרי שהאפליקציה ל-Chat מקבלת את הנתונים מהודעה עם כרטיס או מתיבת דו-שיח, היא משיבה באישור קבלה או מחזירה שגיאה.
בדוגמה הבאה, אפליקציית Chat שולחת הודעת טקסט כדי לאשר שהיא קיבלה בהצלחה טופס שנשלח מהודעה עם כרטיס.
Node.js
Python
Java
Apps Script
בדוגמה הזו, ההודעה נשלחת באמצעות החזרת קובץ JSON של כרטיס. אפשר גם להשתמש בשירות הכרטיסים של Apps Script.
כדי לעבד ולסגור תיבת דו-שיח, מחזירים אובייקט RenderActions שמציין אם רוצים לשלוח הודעת אישור, לעדכן את ההודעה או הכרטיס המקוריים או פשוט לסגור את תיבת הדו-שיח. איך סוגרים תיבת דו-שיח
פתרון בעיות
בקטע הזה מוסבר איך לפתור בעיות שקשורות לקודי שגיאה ספציפיים ולהתנהגויות בזמן ריצה כשמשתמשים בתיבות דו-שיח ב-Chat.
אינטראקציות בתיבת הדו-שיח מחזירות את השגיאה "שגיאה לא מזוהה מפעילה את התוסף"
כשמקיימים אינטראקציה עם תיבת דו-שיח, אם מופיעים יומני שגיאות עם ההודעה "שגיאה לא מזוהה בהפעלת התוסף" וקוד 13, בדרך כלל זה מצביע על שגיאה פנימית או על כך שנקודת הקצה ל-HTTP של אפליקציית הצ'אט לא הצליחה לעבד את הבקשה או להחזיר תשובה תקינה.
כדי לפתור את השגיאה:
- בודקים אם יש ביומנים של נקודת הקצה ב-HTTP קריסות או חריגות שלא טופלו.
- מוודאים שנקודת הקצה מגיבה לבקשות תוך 30 שניות. אם לוקח יותר מ-30 שניות להפעיל את נקודת הקצה, אפליקציית Chat לא יכולה לעבד את התשובה והאינטראקציה נכשלת. למידע נוסף, ראו מגבלות קצב ושיטות מומלצות.
- מוודאים שנקודת הקצה (endpoint) מחזירה תשובה תקינה. כששולחים תיבת דו-שיח, נקודת הקצה צריכה להחזיר אובייקט
RenderActionsבפורמט JSON תקין. אם התשובה לא תקינה או לא מכילה את השדות הנדרשים, יכול להיות שהאינטראקציה עם תיבת הדו-שיח תיכשל.
כשמוחזרת שגיאה מאפליקציה ל-Google Chat או מכרטיס, בממשק של Chat מופיעה ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים לא מופיעה הודעת שגיאה בממשק המשתמש של Chat, אבל אפליקציית Chat או הכרטיס מניבים תוצאה לא צפויה. לדוגמה, יכול להיות שהודעה בכרטיס לא תופיע.
יכול להיות שלא תופיע הודעת שגיאה בממשק המשתמש של Chat, אבל אם הפעלתם את רישום השגיאות ביומן באפליקציות ל-Chat, תוכלו להיעזר בהודעות השגיאה המפורטות ובנתונים ביומן כדי לתקן את השגיאות. כדי לקבל עזרה בהצגה, בניפוי באגים ובתיקון שגיאות, אפשר לעיין במאמר פתרון בעיות ותיקון שגיאות ב-Google Chat.
נושאים קשורים
- לצפייה בדוגמה של Contact Manager, אפליקציה ל-Chat שמבקשת מהמשתמשים למלא טופס ליצירת קשר מהודעות בכרטיסים ומתיבות דו-שיח.
- פתיחת תיבות דו-שיח אינטראקטיביות
אפליקציות ל-Chat שהן לא תוספים: קריאת נתונים שהמשתמשים הזינו בטפסים בכרטיסים
המסמכים הבאים רלוונטיים לאפליקציות ל-Chat שהן לא תוספים ל-Google Workspace. כדי להעביר אפליקציה ל-Chat שהיא לא תוסף, אפשר לעיין במאמר המרת אפליקציה ל-Google Chat לתוסף ל-Google Workspace.
יצירת טפסים באמצעות כרטיסים
הקוד הבא הוא דוגמה לאפליקציה ל-Chat שהיא לא תוסף, שמשתמשת בטופס ליצירת קשר עם קלט טקסט, בורר תאריך ושעה וקלט בחירה:
Node.js
Python
Java
Apps Script
קבלת נתונים מווידג'טים אינטראקטיביים
בכל פעם שמשתמשים לוחצים על כפתור, אפליקציות ל-Chat שהן לא תוספים מקבלות אירוע אינטראקציה בהתאם למיקום של הכפתור:
אם הלחצן נמצא בהודעה או בתיבת דו-שיח, אפליקציות ל-Chat שהן לא תוספים מקבלות אירוע אינטראקציה מסוג
CARD_CLICKEDשמכיל מידע על האינטראקציה. המטען הייעודי (payload) של אירועי אינטראקציה מסוגCARD_CLICKEDמכיל אובייקטcommon.formInputs(event.common.formInputs) עם כל הערכים שהמשתמש מזין.אפשר לאחזר את הערכים מהאובייקט
common.formInputs.WIDGET_NAME, כאשר WIDGET_NAME הוא השדהnameשציינתם לווידג'ט. הערכים מוחזרים כסוג נתונים ספציפי לווידג'ט (מיוצג כאובייקטInputs).הדוגמה הבאה מציגה חלק מאירוע אינטראקציה של
CARD_CLICKEDשבו משתמש הזין ערכים לכל ווידג'ט:HTTP
{ "type": "CARD_CLICKED", "common": { "formInputs": { "contactName": { "stringInputs": { "value": ["Kai 0"] }}, "contactBirthdate": { "dateInput": { "msSinceEpoch": 1000425600000 }}, "contactType": { "stringInputs": { "value": ["Personal"] }} }} }Apps Script
{ "type": "CARD_CLICKED", "common": { "formInputs": { "contactName": { "": { "stringInputs": { "value": ["Kai 0"] }}}, "contactBirthdate": { "": { "dateInput": { "msSinceEpoch": 1000425600000 }}}, "contactType": { "": { "stringInputs": { "value": ["Personal"] }}} }} }אם הלחצן נמצא בדף הבית, אפליקציות ל-Chat שהן לא תוספים מקבלות אירוע אינטראקציה מסוג
SUBMIT_FORM. המטען הייעודי (payload) של אירוע האינטראקציה מכיל אובייקטcommonEventObject.formInputs(event.commonEventObject.formInputs) עם כל הערכים שהמשתמש מזין.אפשר לאחזר את הערכים מהאובייקט
commonEventObject.formInputs.WIDGET_NAME, כאשר WIDGET_NAME הוא השדהnameשציינתם לווידג'ט. הערכים מוחזרים כסוג נתונים ספציפי לווידג'ט (מיוצג כאובייקטInputs).הדוגמה הבאה מציגה חלק מאירוע אינטראקציה של
SUBMIT_FORMשבו משתמש הזין ערכים לכל ווידג'ט:HTTP
{ "type": "SUBMIT_FORM", "commonEventObject": { "formInputs": { "contactName": { "stringInputs": { "value": ["Kai 0"] }}, "contactBirthdate": { "dateInput": { "msSinceEpoch": 1000425600000 }}, "contactType": { "stringInputs": { "value": ["Personal"] }} }} }Apps Script
{ "type": "SUBMIT_FORM", "commonEventObject": { "formInputs": { "contactName": { "": { "stringInputs": { "value": ["Kai 0"] }}}, "contactBirthdate": { "": { "dateInput": { "msSinceEpoch": 1000425600000 }}}, "contactType": { "": { "stringInputs": { "value": ["Personal"] }}} }} }
כדי לקבל את הנתונים, אפליקציית Chat שהיא לא תוסף מטפלת באירוע האינטראקציה כדי לקבל את הערכים שהמשתמשים מזינים בווידג'טים. בטבלה הבאה מוסבר איך לקבל את הערך של ווידג'ט קלט נתון בטופס. בטבלה הבאה מוצגים סוגי הנתונים שכל ווידג'ט מקבל, המיקום שבו הערך נשמר באירוע האינטראקציה וערך לדוגמה.
| ווידג'ט של קלט בטופס | סוג נתוני הקלט | ערך הקלט מאירוע האינטראקציה | ערך לדוגמה |
|---|---|---|---|
textInput |
stringInputs |
event.common.formInputs.contactName.stringInputs.value[0] |
Kai O |
selectionInput |
stringInputs |
כדי לקבל את הערך הראשון או היחיד, event.common.formInputs.contactType.stringInputs.value[0] |
Personal |
dateTimePicker שאפשר להזין בו רק תאריכים. |
dateInput |
event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. |
1000425600000 |
העברת נתונים לכרטיס אחר
כדי להעביר את הקלט של הנתונים מהכרטיס הראשוני באפליקציה ל-Chat שהיא לא תוסף, יוצרים את הווידג'ט button עם actionParameters שמכילים את ה-name של הווידג'ט ואת הערך שהמשתמש הזין, כמו בדוגמה הבאה:
Node.js
Python
Java
Apps Script
כשמשתמש לוחץ על הכפתור, אפליקציית הצ'אט שהיא לא תוסף מקבלת אירוע אינטראקציה מסוג CARD_CLICKED, שדרכו אפשר לקבל נתונים.
איך מגיבים לטופס שנשלח
בדוגמה הבאה, אפליקציה ל-Chat שהיא לא תוסף שולחת הודעת טקסט כדי לאשר שהיא קיבלה בהצלחה טופס שנשלח מתיבת דו-שיח או מהודעה בכרטיס:
Node.js
Python
Java
Apps Script
כדי לעבד ולסגור תיבת דו-שיח באפליקציה ל-Chat שהיא לא תוסף, מחזירים אובייקט ActionResponse שמציין אם רוצים לשלוח הודעת אישור, לעדכן את ההודעה או הכרטיס המקוריים או פשוט לסגור את תיבת הדו-שיח. איך סוגרים תיבת דו-שיח