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

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

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

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

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

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

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

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

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