عیب‌یابی و رفع کردن کارت‌ها و چارگوش‌های گفتگو

این راهنما خطاهای رایج مربوط به کارت را که ممکن است با آن‌ها مواجه شوید و نحوه رفع آن‌ها را شرح می‌دهد.

از «کارت‌ساز» برای طراحی و پیش‌نمایش پیام‌رسانی و واسط‌های کاربر برای برنامه‌های Chat استفاده کنید:

باز کردن «سازنده کارت»

نحوه نمایش خطاهای کارت

خطاهای کارت به چند روش ظاهر می‌شوند:

  • بخشی از کارت، مانند ابزارک یا عنصر، ظاهر نمی‌شود یا به‌شیوه‌ای غیرمنتظره پرداز می‌شود.
  • کل کارت نشان داده نمی‌شود.
  • کادر گفتگویی بسته می‌شود، باز نمی‌شود، یا بار نمی‌شود.

اگر با چنین رفتاری مواجه شدید، یعنی کارت برنامه‌تان خطا دارد.

برای مرجع: پیام و کادر گفتگوی کارت بدون خطا و کارا

قبل‌از بررسی نمونه‌های کارت اشتباه، ابتدا این پیام و کادر گفتگوی کارت کاری را درنظر بگیرید. برای نشان دادن هر خطای نمونه و اصلاح آن، JSON این کارت با معرفی خطاها اصلاح می‌شود.

پیام کارت بدون خطا

در اینجا پیام کارت کاری و بدون خطایی را می‌بینید که اطلاعات تماس را با جزئیات شامل سرصفحه، بخش‌ها، و ابزارک‌هایی مثل نوشتار تزیین‌شده و دکمه‌ها ارائه می‌دهد:

کادر گفتگوی بدون خطا

در اینجا گفتگوی بدون خطا و کارآمدی را می‌بینید که با جمع‌آوری اطلاعات از کاربران مخاطب ایجاد می‌کند، دارای پانویس و ابزارک‌های ویرایش‌پذیر مثل ورودی نوشتار و کلیدهای تغییر وضعیت و دکمه‌ها است:

خطا: بخشی از کارت نشان داده نمی‌شود

گاهی‌اوقات کارت‌ها پرداز می‌شوند، اما بخشی از کارتی که انتظار داشتید ببینید ظاهر نمی‌شود؛ دلایل احتمالی عبارت‌اند از:

  • فیلد الزامی JSON وجود ندارد.
  • فیلد JSON غلط املایی دارد یا حروف آن به‌درستی بزرگ نشده است.

دلیل: فیلد JSON الزامی وجود ندارد

در این خطای نمونه، فیلد الزامی JSON، title، وجود ندارد. درنتیجه، کارت پردازش می‌شود، اما بخش‌هایی از کارت که انتظار می‌رود ظاهر شوند، ظاهر نمی‌شوند. پیش‌بینی نحوه پرداز کارت‌ها درصورت حذف فیلدهای الزامی می‌تواند دشوار باشد.

برای رفع این خطا، فیلد JSON الزامی را اضافه کنید؛ در این مثال، title.

برای اینکه بدانید فیلد JSON الزامی است یا نه، به مستندات مرجع کارت‌ها نسخه ۲ مراجعه کنید. در این مثال، به شرح فیلد title در CardHeader مراجعه کنید.

در اینجا دو مثال آورده شده است:

مثال ۱: مشخص کردن subtitle اما حذف کردن title الزامی باعث می‌شود کل سرایند خالی نشان داده شود:

سرایند این کارت نمایش داده نمی‌شود زیرا فیلد الزامی، عنوان، وجود ندارد.
شکل ۱: سرصفحه این کارت نمایش داده نمی‌شود زیرا فیلد الزامی title وجود ندارد.

مشاهده تکه‌کد JSON کارت اشتباه

خطا: فیلد الزامی title در header وجود ندارد.

    . . .
    "header": {

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

مشاهده تکه‌کد JSON کارت صحیح

رفع شد: فیلد الزامی، title، بخشی از مشخصات header است.

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

مثال ۲: مشخص کردن subtitle، imageUrl، imageType، و imageAltText اما حذف کردن title الزامی باعث می‌شود تصویر همان‌طور که انتظار می‌رود پرداز شود، اما زیرنویس این‌گونه نیست:

سرایند این کارت نمایش داده نمی‌شود زیرا فیلد الزامی، عنوان، وجود ندارد.
شکل ۲: سرایند این کارت زیرعنوان را نمایش نمی‌دهد زیرا فیلد الزامی، 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، وجود ندارد، اما تصویر طبق انتظار پرداز می‌شود.

مشاهده تکه‌کد 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 به‌اشتباه مشخص شده است

اگر پیام کارت یا چارگوش گفتگویی شامل 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 کارت اشتباه

خطا: شیء 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 با RenderActions شیء (برای نمونه، action.navigations با pushCard یا endNavigation) است. بنابراین، کادرهای گفتگو در برنامه‌هایی که با معماری ناهم‌زمان ساخته شده‌اند پشتیبانی نمی‌شوند.

به‌عنوان راهکار موقت، به‌جای پیام کارت از چارگوش گفتگو استفاده کنید.

خطاهای دیگر کارت و کادر گفتگو

اگر اصلاحاتی که در این صفحه توضیح داده شده است خطای مربوط به کارت را که برنامه شما با آن مواجه است برطرف نکرد، گزارش‌های خطای برنامه را پُرسمان کنید. پُرسمان کردن گزارش‌ها می‌تواند به یافتن خطاها در JSON کارت یا کد برنامه کمک کند، و گزارش‌ها شامل پیام‌های خطای توصیفی است تا به شما در رفع آن‌ها کمک کند.

برای دریافت راهنمایی درباره رفع خطاهای برنامه Google Chat، به عیب‌یابی و رفع مشکلات برنامه Google Chat و عیب‌زدایی برنامه‌های Chat مراجعه کنید.

برنامه‌های گپ که برافزا نیستند: عیب‌یابی و اصلاح کارت‌ها و کادرهای گفتگو

مستندات زیر برای برنامه‌های Chat که برافزاهای Google Workspace نیستند اعمال می‌شود. برای انتقال برنامه Chat که برافزا نیست، تبدیل برنامه Chat به برافزای Google Workspace را ببینید.

برای برنامه‌های Chat که برافزا نیستند، باز کردن، ارسال، یا لغو کردن کادر گفتگو نیاز به ActionResponse هم‌زمان با DialogEventType دارد.