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

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

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

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

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

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

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

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

לידיעתך: הודעה ותיבת דו-שיח עם כרטיס תקין וללא שגיאות

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

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

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

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

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

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