פתרון בעיות ותיקון כרטיסים ותיבות דו-שיח

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

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

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

איך שגיאות בכרטיסים מופיעות

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

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

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

לעיון: הודעה ודיאלוג תקינים בכרטיס, ללא שגיאות

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

הודעה בכרטיס שלא כוללת שגיאות

הנה הודעה תקינה בכרטיס עם פרטים ליצירת קשר, שכוללת כותרת, קטעים ווידג'טים כמו טקסט מעוצב ולחצנים:

שיחה ללא שגיאות

דיאלוג תקין שיוצר איש קשר על ידי איסוף מידע מהמשתמשים, כולל כותרת תחתונה ווידג'טים שניתנים לעריכה כמו שדות להזנת טקסט, מתגים ולחצנים:

שגיאה: חלק מהכרטיס לא מופיע

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

  • חסר שדה חובה ב-JSON.
  • שגיאת כתיב בשדה JSON או שימוש שגוי באותיות רישיות.

הסיבה: חסר שדה חובה ב-JSON

בדוגמה הזו לשגיאה, חסר שדה חובה ב-JSON,‏ title. כתוצאה מכך, הכרטיס מוצג, אבל חלקים ממנו שאמורים להופיע לא מוצגים. קשה לחזות איך הכרטיסים יוצגו כששדות החובה לא מלאים.

כדי לפתור את השגיאה הזו, צריך להוסיף את שדה ה-JSON הנדרש. בדוגמה הזו, השדה הוא title.

כדי לדעת אם שדה JSON הוא שדה חובה, אפשר לעיין במסמכי העזרה בנושא Cards v2. בדוגמה הזו, אפשר לעיין בתיאור של השדה title בדף CardHeader.

להלן שתי דוגמאות:

דוגמה 1: אם מציינים subtitle אבל לא מציינים את title הנדרש, כל הכותרת תופיע ריקה:

הכותרת של הכרטיס הזה לא מוצגת כי חסר שדה חובה – הכותרת.
איור 1: הכותרת של הכרטיס הזה לא מוצגת כי חסר שדה חובה, title.

צפייה בקטע JSON של כרטיס עם שגיאה

שגיאה: חסר שדה חובה, title, ב-header.

    . . .
    "header": {

            "subtitle": "Software Engineer"
          }
    . . .

צפייה בקטע JSON נכון של כרטיס

תוקן: שדה החובה title הוא חלק מהמפרט header.

    . . .
    "header": {
            "title": "Sasha",
            "subtitle": "Software Engineer"
          }
    . . .

דוגמה 2: אם מציינים את הדגלים subtitle,‏ imageUrl,‏ imageType ו-imageAltText, אבל משמיטים את הדגל הנדרש title, התמונה תוצג כצפוי, אבל הכתוביות לא יוצגו:

הכותרת של הכרטיס הזה לא מוצגת כי חסר שדה חובה – הכותרת.
איור 2: הכותרת של הכרטיס הזה לא מציגה את כותרת המשנה כי חסר שדה חובה, title, אבל התמונה מוצגת כמו שצריך.

צפייה בקטע JSON של כרטיס עם שגיאה

שגיאה: חסר שדה חובה, title, ב-header.

    . . .
    "header": {

            "subtitle": "Software Engineer",
            "imageUrl":
            "https://developers.google.com/chat/images/quickstart-app-avatar.png",
            "imageType": "CIRCLE",
            "imageAltText": "Avatar for Sasha",
          }
    . . .

צפייה בקטע JSON נכון של כרטיס

תוקן: שדה החובה title הוא חלק מהמפרט header.

    . . .
    "header": {
            "title": "Sasha",
            "subtitle": "Software Engineer",
            "imageUrl":
            "https://developers.google.com/chat/images/quickstart-app-avatar.png",
            "imageType": "CIRCLE",
            "imageAltText": "Avatar for Sasha",
          }
    . . .

הסיבה: איות שגוי או שימוש שגוי באותיות רישיות בקובץ JSON

בדוגמה הזו לשגיאה, קובץ ה-JSON של הכרטיס כולל את כל השדות הנדרשים, אבל אחד מהשדות, imageUrl, נכתב באותיות רישיות בצורה שגויה כ-imageURL (R באותיות רישיות, L באותיות רישיות), ולכן מתרחשת שגיאה: התמונה שאליה הוא מפנה לא מוצגת.

כדי לתקן את השגיאה הזו ושגיאות דומות, צריך להשתמש בפורמט JSON הנכון. במקרה הזה, imageUrl היא התשובה הנכונה. אם יש לכם ספק, כדאי לבדוק את ה-JSON של הכרטיס מול מסמך ההפניה של הכרטיס.

הכותרת של הכרטיס הזה לא מוצגת כי חסר שדה חובה – הכותרת.
איור 3: הכותרת של הכרטיס הזה לא מציגה את כותרת המשנה כי חסר שדה חובה, title, אבל התמונה מוצגת כמו שצריך.

צפייה בקטע JSON של כרטיס עם שגיאה

שגיאה: האותיות בשדה imageURL לא תקינות. הוא אמור להיות imageUrl.

    . . .
    "header": {
      "title": "Sasha",
      "subtitle": "Software Engineer",
      "imageURL":
      "https://developers.google.com/chat/images/quickstart-app-avatar.png",
      "imageType": "CIRCLE",
      "imageAltText": "Avatar for Sasha",
    }
    . . .

צפייה בקטע JSON נכון של כרטיס

תוקן: השדה imageUrl נכתב עם אותיות רישיות בצורה נכונה.

    . . .
    "header": {
            "title": "Sasha",
            "subtitle": "Software Engineer",
            "imageUrl":
            "https://developers.google.com/chat/images/quickstart-app-avatar.png",
            "imageType": "CIRCLE",
            "imageAltText": "Avatar for Sasha",
          }
    . . .

שגיאה: כרטיס שלם לא מופיע

לפעמים הכרטיס עצמו לא מופיע. הסיבות האפשריות לכך הן:

הסיבה: צוין ערך שגוי של buttonList או cardFixedFooter

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

כדי לפתור את השגיאה הזו, צריך לבדוק את קובץ ה-JSON של הכרטיס בהשוואה למסמך העזר בנושא כרטיסים. בפרט, כדאי להשוות בין הווידג'טים של ButtonList לבין ButtonListהמדריך לווידג'טים.

דוגמה: במדריך לווידג'ט ButtonList, העברת פעולה לא מלאה של onClick בלחצן הראשון מונעת את העיבוד של הכרטיס כולו.

צפייה בקטע JSON של כרטיס עם שגיאה

שגיאה: לא צוינו שדות באובייקט onClick, ולכן הכרטיס כולו לא מופיע.

    . . .
    {
      "buttonList": {
        "buttons": [
          {
            "text": "Share",
            "onClick": {


              }
            }
          },
          {
            "text": "Edit",
            "onClick": {
              "action": {
                "function": "goToView",
                "parameters": [
                  {
                    "key": "viewType",
                    "value": "EDIT",
                  }
                ],
              }
            }
          },
        ],
      },
    }
    . . .

צפייה בקטע JSON נכון של הכרטיס

תוקן: לאובייקט onClick יש עכשיו שדה openLink, כך שהכרטיס מופיע כמצופה.

    . . .
    {
      "buttonList": {
        "buttons": [
          {
            "text": "Share",
            "onClick": {
              "openLink": {
                "url": "https://example.com/share",
              }
            }
          },
          {
            "text": "Edit",
            "onClick": {
              "action": {
                "function": "goToView",
                "parameters": [
                  {
                    "key": "viewType",
                    "value": "EDIT",
                  }
                ],
              }
            }
          },
        ],
      },
    }
    . . .

שגיאה: תיבת דו-שיח נסגרת, נתקעת או לא נפתחת

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

אלה הסיבות הנפוצות ביותר:

הסיבה: ל-CardFixedFooter אין primaryButton

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

כדי לתקן את השגיאה הזו, צריך לוודא שווידג'ט CardFixedFooter כולל primaryButton שצוין בצורה נכונה.

צפייה בקטע JSON של כרטיס עם שגיאה

שגיאה: לא צוין שדה primaryButton באובייקט fixedFooter, ולכן תיבת הדו-שיח לא נטענת או לא נפתחת.

    . . .
    "fixedFooter": {

        "onClick": {
          . . .
      },
      "secondaryButton": {
        . . .
        }
      }
    }
    . . .

צפייה בקטע JSON נכון של הכרטיס

תוקן: עכשיו יש ל-fixedFooter שדה primaryButton שצוין, כך שתיבת הדו-שיח פועלת כמצופה.

    . . .
    "fixedFooter": {
      "primaryButton": {
        "text": "Submit",
        "color": {
          "red": 0,
          "blue": 1,
          "green": 0
        },
        "onClick": {
          . . .
      },
      "secondaryButton": {
        . . .
        }
      }
    }
    . . .

הסיבה: הגדרה שגויה של onClick ב-FixedFooter

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

כדי לתקן את השגיאה הזו, צריך לוודא שכל לחצן כולל הגדרה של onClick שצוינה בצורה נכונה.

צפייה בקטע JSON של כרטיס עם שגיאה

שגיאה: לאובייקט primaryButton יש שדה onClick עם מערך 'parameters' שמאוית בצורה שגויה, ולכן תיבת הדו-שיח לא נטענת או לא נפתחת.

    . . .
    "fixedFooter": {
      "primaryButton": {
        "text": "Submit",
        "color": {
          "red": 0,
          "blue": 1,
          "green": 0
        },
        "onClick": {
          "action": {
            "function": "setLanguageType",
            "parrammetters": [
              {
                "key": "languageType",
                "value": "C++"
              }
            ]
          }
        }
      },
      "secondaryButton": {
        "text": "Cancel",
        "onClick": {
          "action": {
            "function": "reset"
          }
        }
      }
    }
    . . .

צפייה בקטע JSON נכון של הכרטיס

תוקן: לאובייקט primaryButton יש שדה onClick עם מערך `parameters` שמאוית בצורה נכונה, כך שתיבת הדו-שיח פועלת כמצופה.

    . . .
    "fixedFooter": {
      "primaryButton": {
        "text": "Submit",
        "color": {
          "red": 0,
          "blue": 1,
          "green": 0
        },
        "onClick": {
          "action": {
            "function": "setLanguageType",
            "parameters": [
              {
                "key": "languageType",
                "value": "C++"
              }
            ]
          }
        }
      },
      "secondaryButton": {
        "text": "Cancel",
        "onClick": {
          "action": {
            "function": "reset"
          }
        }
      }
    }
    . . .

הסיבה: ל-TextInput אין name

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

כדי לתקן את השגיאה הזו, צריך לוודא שכל ווידג'ט TextInput כולל שדה name מתאים. מוודאים שכל שדה name בכרטיס הוא ייחודי.

צפייה בקטע JSON של כרטיס עם שגיאה

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

    . . .
    {
      "textInput": {
        "label": "Name",
        "type": "SINGLE_LINE",

      }
    }
    . . .

צפייה בקטע JSON נכון של הכרטיס

תוקן: עכשיו יש ל-textInput שדה name שצוין, כך שתיבת הדו-שיח פועלת כמצופה.

    . . .
    {
      "textInput": {
        "label": "Name",
        "type": "SINGLE_LINE",
        "name": "contactName"
      }
    }
    . . .

פעולות של פתיחה, שליחה או ביטול של תיבת דו-שיח נכשלות בארכיטקטורת אפליקציה אסינכרונית

אם אפליקציית Chat מחזירה את הודעת השגיאה Could not load dialog. Invalid response returned by bot. כשעובדים עם תיבות דו-שיח, יכול להיות שהסיבה לכך היא שהאפליקציה משתמשת בארכיטקטורה אסינכרונית, כמו Cloud Pub/Sub או שיטת ה-API‏ Create Message.

כדי לפתוח תיבת דו-שיח, לשלוח אותה או לבטל אותה, צריך לקבל תגובה סינכרונית מאפליקציית Chat עם אובייקט RenderActions (לדוגמה, action.navigations עם pushCard או endNavigation). לכן, אפליקציות שנבנו עם ארכיטקטורה אסינכרונית לא תומכות בתיבות דו-שיח.

כפתרון עקיף, אפשר להשתמש בהודעה בכרטיס במקום בתיבת דו-שיח.

שגיאות אחרות בכרטיסים ובתיבות דו-שיח

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

לקבלת עזרה בתיקון שגיאות באפליקציית Google Chat, אפשר לעיין במאמרים פתרון בעיות באפליקציית Google Chat וניפוי באגים באפליקציות ל-Chat.

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

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

באפליקציות Chat שהן לא תוספים, כדי לפתוח תיבת דו-שיח, לשלוח אותה או לבטל אותה, צריך לבצע ActionResponse סינכרוני עם DialogEventType.