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

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

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

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

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

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

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

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

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

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

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

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

תיבת דו-שיח ללא שגיאות

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

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

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

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

הסיבה: חסר שדה JSON נדרש

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

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

כדי לבדוק אם שדה JSON נדרש או לא, עיינו במאמרי העזרה של כרטיסים 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

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

    . . .
    "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

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

    . . .
    {
      "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 זמין במאמרים פתרון בעיות באפליקציית Google Chat וניפוי באגים באפליקציות ל-Chat.