ویجت نمایش داده نمی‌شود

ویجت در سایت شما نمایش داده نمی‌شود، یا فقط برای کاربران واردشده نشان داده می‌شود، یا وقتی آن را باز می‌کنید صفحه خالی است. این صفحه یک نمودار جریان علامت → علت → راه‌حل است. مراحل را به ترتیب اجرا کنید؛ اکثر نصب‌ها در مرحله اول مشکل را پیدا کرده و بقیه را رد می‌کنند.

علامت: ویجت فقط برای کاربران واردشده نمایش داده می‌شود

علت: کش صفحه. افزونه‌های کش وردپرس (W3 Total Cache، WP Rocket، LiteSpeed Cache، WP Super Cache)، کش صفحه در سطح هاست (Hostinger، SiteGround، Cloudways، Kinsta) یا Cloudflare APO همگی یک تصویر HTML کش‌شده را به بازدیدکنندگان ناشناس ارائه می‌دهند که قبل از نصب Pitchbar گرفته شده است. کاربران واردشده از کش صفحه عبور می‌کنند، بنابراین همیشه PHP تازه را دریافت کرده و ویجت را می‌بینند.

راه‌حل:

1. مدیریت وردپرس ← افزونه کش شما ← روی پاک‌سازی همه کش کلیک کنید.
2. اگر در Hostinger / SiteGround / Cloudways / Kinsta هستید: کنترل پنل ← کش صفحه ← پاک‌سازی.
3. اگر کلودفلر دامنه شما را پراکسی می‌کند: داشبورد کلودفلر ← کش ← پیکربندی ← پاک‌سازی همه.
4. سایت خود را در حالت ناشناس (پنجره خصوصی جدید) باز کنید ← کلیک راست ← مشاهده منبع ← جستجوی widget.js. وجود دارد = مشکل حل شد.

علامت: ویجت اصلاً نمایش داده نمی‌شود

راهنمای گام‌به‌گام:

1. تأیید کنید که افزونه Pitchbar وردپرس پیکربندی شده است. مدیریت وردپرس ← Pitchbar (نوار کناری سمت چپ). هر سه فیلد باید تنظیم شوند: آدرس پایه، توکن API، شناسه دستیار فروش. عدم وجود هر کدام = درگاه shouldRender() افزونه false برمی‌گرداند و هیچ چیزی نمایش داده نمی‌شود.
2. تأیید کنید که ویجت فعال است. همان صفحه تنظیمات Pitchbar ← چک‌باکس "ویجت فعال". پیش‌فرض روشن است، اما تأیید آن ارزش دارد.
3. تأیید محدوده نوع پست. صفحه تنظیمات ← "نمایش در این نوع پست‌ها". پیش‌فرض post + page است. اگر صفحه اصلی شما یک نوع پست سفارشی است (مثلاً landing، product) و آن را علامت نزده‌اید، ویجت از آن صفحه صرف‌نظر می‌کند. کادر را علامت بزنید.
4. ابزارهای توسعه‌دهنده مرورگر ← برگه شبکه را در صفحه فرانت‌اند خود باز کنید. widget.js را جستجو کنید:
   • موجود + ۲۰۰ OK: اسکریپت بارگذاری شده است. کنسول را برای خطاهای JS بررسی کنید.
   • موجود + ۴۰۴: تنظیم آدرس پایه شما به میزبانی اشاره می‌کند که widget.js را ارائه نمی‌دهد. باید ریشه نصب Pitchbar شما باشد (مثلاً https://pitchbar.your-domain.com).
   • کاملاً وجود ندارد: افزونه تگ را منتشر نمی‌کند. از طریق مشاهده منبع تأیید کنید — به دنبال <script async src=…widget.js…> بگردید. عدم وجود تگ = درگاه shouldRender() ناموفق بوده است. سه مورد قبلی را دوباره بررسی کنید.

علامت: ویجت نمایش داده می‌شود اما می‌گوید "متاسفم — خطایی رخ داد"

ویجت جریان SSE را ۳ بار تلاش مجدد کرده و سپس این حباب عمومی را نشان می‌دهد. خطای واقعی در سمت سرور ثبت می‌شود. حباب عمداً مبهم است تا بازدیدکنندگان خطاهای خام سرویس‌دهنده را نبینند.

در حین بازتولید در ویجت، لاگ‌های لاراول را دنبال کنید:

tail -f storage/logs/laravel.log

الگوهای رایج و راه‌حل‌های آنها:

• Workers AI 401: ... — توکن API کلودفلر رد شده است. راهنمای عیب‌یابی ۴۰۱ کلودفلر را مشاهده کنید.
• Vectorize ... expected N dimensions, got M — عدم تطابق مدل جستجوی هوشمند و ابعاد شاخص. بازیابی ابعاد جستجوی هوشمند را مشاهده کنید.
• Workers AI timeout — کلودفلر ناپایدار است. دوباره تلاش کنید. اگر ادامه داشت، CLOUDFLARE_CHAT_MODEL را به یک نوع کوچکتر تغییر دهید.
• message_quota_exceeded — سقف پلن فضای کاری رسیده است. پلن فضای کاری را ارتقا دهید.
• conversation_not_found — JWT ویجت از conversations.cleared_at روی ردیف مکالمه آن قدیمی‌تر است. بازدیدکننده باید صفحه را بازخوانی کند تا ویجت از طریق /api/v1/widget/init بعدی یک JWT جدید صادر کند.

علامت: ویجت نمایش داده می‌شود اما قرص راه‌انداز هرگز ظاهر نمی‌شود

تداخل تم. برخی تم‌ها iframe { display: none !important } یا یک بازنشانی z-index سراسری تنظیم می‌کنند. ویجت Pitchbar در داخل یک Shadow DOM نمایش داده می‌شود اما نقطه نصب آن یک <div> در صفحه میزبان است.

راه‌حل: این CSS را به CSS اضافی تم خود اضافه کنید:

#pitchbar-root,
#pitchbar-root * {
    display: revert !important;
    visibility: visible !important;
    z-index: 2147483647 !important;
}

هنوز گیر کرده‌اید؟

با support@pitchbar.app تماس بگیرید و موارد زیر را همراه داشته باشید:

• یک اسکرین‌شات از صفحه فرانت‌اند که ویجت در آن نمایش داده نمی‌شود.
• خروجی tail -200 storage/logs/laravel.log (یا خروجی کنسول مرورگر اگر اسکریپت هرگز به سرور شما نرسیده است).
• آدرس صفحه آسیب‌دیده (در صورت عمومی بودن).