رفع اشکال

راهنمای مبتنی بر علامت برای رایج‌ترین مشکلات افزونه وردپرس. هر راه‌حل براساس مسیر کد واقعی است — بدون توصیه‌های آرمانی.

ویجت در سایت ظاهر نمی‌شود

به ترتیب بررسی کنید:

1. افزونه پیکربندی شده است؟ تنظیمات ← Pitchbar را باز کنید. هر سه فیلد (آدرس پایه، توکن API، دستیار فروش) باید پر شوند. کلید Enabled باید روشن باشد.
2. نوع پست صحیح است؟ چک‌باکس‌های "نوع پست‌ها" مشخص می‌کنند که کدام صفحات تکی ویجت را بارگذاری می‌کنند. به‌طور پیش‌فرض فقط post + page علامت خورده‌اند. صفحات محصول ووکامرس product نیاز به انتخاب صریح دارند.
3. تم wp_footer() را فراخوانی می‌کند؟ افزونه اسکریپت را از طریق add_action('wp_footer', …, 99) تزریق می‌کند. تمی که wp_footer() را از footer.php حذف کند، ویجت را بارگذاری نمی‌کند. بیشتر تم‌های مدرن آن را فراخوانی می‌کنند. تم‌های سفارشی قدیمی گاهی اوقات این کار را نمی‌کنند.
4. افزونه کش یک تصویر قدیمی ارائه می‌دهد؟ WP Rocket، W3 Total Cache، LiteSpeed و Cloudflare APO همگی می‌توانند یک نسخه HTML قبل از ویجت را برای روزها کش کنند. کش صفحه را برای آدرس‌های آسیب‌دیده پاک کنید.
5. مرورگر اسکریپت ویجت را مسدود می‌کند؟ DevTools ← Network را باز کنید. درخواست به {base_url}/widget/widget.js باید ۲۰۰ برگرداند. اگر نقض‌های connect-src را در کنسول می‌بینید، CSP شما نیاز به یک ورودی لیست مجاز دارد. مشاهده کنید دامنه‌های مجاز.

"تست اتصال" ناموفق است

پیام خطا	تشخیص
"اتصال ناموفق بود."	سطح شبکه — میزبان Pitchbar از WP قابل دسترسی نیست. wp shell را اجرا کنید، wp_remote_get('https://app.pitchbar.example/up') را امتحان کنید. دلیل رایج: فایروال خروجی میزبان Pitchbar را مسدود کرده است.
HTTP 401 invalid_token	متن ساده توکن اشتباه است (اشتباه تایپی در چسباندن) یا توکن در /settings/api-tokens لغو شده است. یک توکن جدید صادر کنید.
HTTP 403 insufficient_ability	توکن با قابلیت wp:integration ایجاد نشده است. با حوزه صحیح دوباره صادر کنید.
"هر دو آدرس پایه و توکن API را وارد کنید، سپس دوباره تلاش کنید."	یکی از فیلدهای فرم خالی است. افزونه از سمت کلاینت برای جلوگیری از سوزاندن درخواست دفاع می‌کند.
"آدرس پایه باید با http:// یا https:// شروع شود."	SettingsValidator آدرس‌های بدون پروتکل را رد می‌کند. آدرس پایه کامل را با https:// وارد کنید.
"فرمت توکن API اشتباه به نظر می‌رسد"	افزونه انتظار pbar_ + ۴۸ کاراکتر الفبایی دارد. یا رشته اشتباه چسبانده شده است، یا توکن در کپی برش خورده است.

"همگام‌سازی اکنون" تمام می‌شود اما Pitchbar محتوای جدید را نمی‌بیند

درخواست POST همگام‌سازی با موفقیت برگشت اما صفحه منابع مدیریت Pitchbar هیچ پستی را نشان نمی‌دهد. احتمالات:

1. همگام‌سازی هنوز در حال ازسرگیری است. در یک سایت بزرگ (۵۰۰+ پست)، اولین بار فقط آنچه در ۲۰ ثانیه جا می‌شود را انجام می‌دهد. بقیه ۳۰ ثانیه بعد در یک تیک WP-Cron تمام می‌شود. مدیریت یک اعلان ملایم نشان می‌دهد: "Pitchbar در حال اتمام یک همگام‌سازی سایت بزرگ در پس‌زمینه است." صبر کنید، بازخوانی کنید، تعداد بالا می‌رود.
2. پردازش خودکار در صف است، نه همزمان. Pitchbar آپلود را می‌پذیرد و یک IndexDocumentJob را در Horizon صف‌بندی می‌کند. در یک پردازشگر شلوغ، این می‌تواند ۳۰-۶۰ ثانیه عقب باشد. /admin/system ← وظایف ناموفق را برای هر خطا بررسی کنید.
3. ذخیره‌ساز جستجوی هوشمند در حال تأمین است. یک شاخص Vectorize کاملاً جدید کلودفلر حدود ۲ دقیقه زمان نیاز دارد تا پرس‌وجوها نتایج را برگردانند. درج‌ها بلافاصله موفق می‌شوند. خوانش‌ها ۰ برمی‌گردانند. اولین دسته از درج‌های پس از ایجاد نیز می‌توانند بی‌صدا حذف شوند — همگام‌سازی را دوباره اجرا کنید.
4. هش محتوا مطابقت داشت. اگر قبلاً پست را همگام‌سازی کرده‌اید و چیزی تغییر نکرده است، تعداد skipped_unchanged پاسخ بدون بازپردازش افزایش می‌یابد. سند از قبل وجود دارد. این همانطور که انتظار می‌رود کار می‌کند.

همگام‌سازی از سر گرفته شد اما هرگز تمام نمی‌شود

یک داده موقت ازسرگیری (pitchbar_post_sync_resume یا pitchbar_product_sync_resume) در wp_options قرار دارد اما ادامه WP-Cron هرگز فعال نمی‌شود. به احتمال زیاد:

• WP-Cron غیرفعال است. wp-config.php را برای define('DISABLE_WP_CRON', true); بررسی کنید. برخی از میزبان‌ها آن را غیرفعال کرده و کرون را از طریق یک کرون سیستم واقعی اجرا می‌کنند — با میزبان خود تأیید کنید. اگر WP-Cron به‌طور کامل غیرفعال است، "همگام‌سازی اکنون" را دوباره از صفحه تنظیمات به‌صورت دستی اجرا کنید. همگام‌ساز نشانگر ازسرگیری را در اولین فراخوانی خود می‌خواند و از جایی که متوقف شده است، ادامه می‌دهد.
• WP-Cron به‌طور بی‌صدا از کار می‌افتد. wp cron event list را در خط فرمان اجرا کنید. ورودی‌های pitchbar_run_full_sync_event / pitchbar_run_product_sync_event باید با یک زمان‌مهر اجرای بعدی در گذشته ظاهر شوند. wp cron event run --due-now آنها را强制执行 می‌کند.
• سایت هرگز ترافیک دریافت نمی‌کند. WP-Cron فرصت‌طلبانه است — پس از زمان زمان‌بندی‌شده در بازدید بعدی صفحه اجرا می‌شود. یک سایت مرحله‌بندی با بازدیدکننده‌ای که کرون را تیک نمی‌زند. یا از هر صفحه فرانت‌اند بازدید کنید، یا هوک را به‌صورت دستی فعال کنید: wp eval '(new \Pitchbar\Sync\PostSyncer)->runFullSync();'.

پاک‌سازی اجباری یک نشانگر ازسرگیری گیر کرده

اگر می‌خواهید همگام‌سازی بعدی را از صفحه ۱ شروع کنید:

wp transient delete pitchbar_post_sync_resume
wp transient delete pitchbar_product_sync_resume

کلیک بعدی "همگام‌سازی اکنون" سپس دوباره از صفحه ۱ شمارش می‌کند. همگام‌سازی مجدد ارزان است — مسیر کوتاه content_hash Pitchbar از بازپردازش پست‌های بدون تغییر جلوگیری می‌کند.

صفحات Elementor / Bricks / Oxygen به‌عنوان محتوای خالی همگام‌سازی می‌شوند

سه احتمال:

1. نسخه سازنده صفحه امضای نمایش‌دهنده خود را تغییر داده است. افزونه به \Elementor\Plugin::$instance->frontend->get_builder_content_for_display، FLBuilder::render_content_by_id و \Bricks\Frontend::render_content بازتاب می‌کند. یک نسخه اصلی که اینها را تغییر نام می‌دهد، یک رشته خالی برمی‌گرداند و افزونه به مسیر ساده بازمی‌گردد. با موارد زیر تأیید کنید: wp eval '$post = get_post(YOUR_ID); echo (new \Pitchbar\Sync\PageBuilderContent)->detectBuilder($post);'.
2. صفحه واقعاً در سازنده خالی است. پست را در مدیریت وردپرس باز کرده و در سازنده ویرایش کنید — گاهی اوقات یک مهاجرت، postmeta را خراب می‌کند و سازنده یک جای‌گیرنده "محتوای پیش‌فرض" را نشان می‌دهد. در سطح سازنده رفع کنید. همگام‌سازی ذخیره بعدی را دریافت می‌کند.
3. شما پشت یک فیلتر pitchbar_post_content_html سفارشی هستید. اگر کد شما یک رشته خالی از فیلتر برمی‌گرداند، هیچ محتوایی ارسال نمی‌شود. functions.php / mu-plugins / هر افزونه سفارشی را بررسی کنید.

دکمه اعمال کوپن در صفحه سبد خرید کاری نمی‌کند

1. بازدیدکننده کوکی pitchbar_conv_id را ندارد. ویجت آن را در زمان راه‌اندازی می‌نویسد. DevTools ← Application ← کوکی‌ها را برای مبدأ سایت WP بررسی کنید. در صورت عدم وجود، ویجت احتمالاً هرگز در صفحه چت بارگذاری نشده است ("ویجت ظاهر نمی‌شود" را در بالا ببینید).
2. مکالمه قبلاً یک کد متفاوت اعمال کرده است. هوک woocommerce_load_cart_from_session افزونه ابتدا WC()->cart->has_discount($code) را فراخوانی کرده و در صورت اعمال شده، رد می‌کند. ووکامرس فقط اجازه می‌دهد یک کد منحصر‌به‌فرد اعمال شود. تغییر کدها نیاز به حذف کد قبلی دارد.
3. داده موقت منقضی شده است. کوپن‌های در انتظار ۱۵ دقیقه زنده می‌مانند. اگر بازدیدکننده یک کد را مرحله‌بندی کرده، سپس مرورگر را برای یک ساعت قبل از باز کردن سبد خرید بسته باشد، داده موقت از بین رفته است. دوباره در چت روی اعمال کلیک کنید.
4. کوپن در مدیریت ووکامرس حذف شده است. افزونه اعتبار کوپن را در زمان اعمال از طریق new WC_Coupon($code)->get_id() تأیید می‌کند. اگر کد دیگر به یک کوپن نگاشت نشود، فراخوانی اعمال ۴۰۰ invalid_coupon برمی‌گرداند.

محرک سبد خرید رها شده هرگز فعال نمی‌شود

• cart-state.js بارگذاری نشده است. DevTools ← Sources را باز کنید، pitchbar-cart-state را جستجو کنید. اسکریپت فقط زمانی صف‌بندی می‌شود که ووکامرس تشخیص داده شود و افزونه پیکربندی شده باشد.
• localStorage غیرفعال است. مرورگری خصوصی، Safari ITP یا یک پروفایل مرورگر سخت‌شده ممکن است localStorage.setItem را مسدود کند. اسکریپت استثنا را به‌طور بی‌صدا می‌گیرد — هیچ رابط خطایی وجود ندارد. محرک به localStorage نیاز دارد. با افزودن یک قانون فعال متفاوت (مثلاً time یا idle) به‌خوبی از کار بیفتید.
• ووکامرس رویدادهای غیر jQuery را فعال می‌کند. برخی تم‌های سفارشی ووکامرس (نمای سریع Flatsome، افزونه‌های AJAX افزودن به سبد خرید) از رویداد استاندارد jQuery added_to_cart صرف‌نظر می‌کنند. بازگشت کلیک DOM اسکریپت، دکمه‌های با نام‌های کلاس .add_to_cart_button / .single_add_to_cart_button را پوشش می‌دهد — اگر تم شما از نام‌های کلاس متفاوتی استفاده می‌کند، وضعیت سبد خرید ثبت نمی‌شود. یک وصله درون‌خطی اضافه کنید یا یک مسئله باز کنید.
• آستانه idle_minutes محرک برآورده نشده است. ویجت هر ۳۰ ثانیه نظرسنجی کرده و زمانی که now - timestamp > idle_minutes * 60_000 ms باشد، فعال می‌شود. یک آستانه ۵ دقیقه به این معنی است که حداقل ۵ دقیقه بدون رویداد سبد خرید باید بگذرد تا محرک سبد خرید را رها شده در نظر بگیرد. conditions.idle_minutes قانون را دوباره بررسی کنید.
• دوره استراحت محرک سراسری. ویجت یک دوره استراحت ۵ دقیقه‌ای را در تمام قوانین فعال اعمال می‌کند تا بازدیدکننده در هر انتقال صفحه غافلگیر نشود. یک قانون فعال می‌شود، هیچ‌یک از بقیه برای ۵ دقیقه فعال نمی‌شوند.

شکست‌های تأیید HMAC (REST افزونه)

فراخوانی Pitchbar → افزونه ۴۰۱ با { "error": { "code": "signature_mismatch" } } برمی‌گرداند. افزونه زمانی که این اتفاق می‌افتد، "Plugin REST HMAC mismatch" را از طریق error_log ثبت می‌کند. دلایل، به ترتیب:

1. ساعت سرور وردپرس بیش از ۵ دقیقه با UTC فاصله دارد. date -u را اجرا کنید. با https://time.is مقایسه کنید. اگر انحراف > ۵ دقیقه است، NTP در حال اجرا نیست یا روی میزبان خراب است. در سطح سیستم‌عامل رفع کنید.
2. shopper_signing_secret افزونه با Pitchbar مطابقت ندارد. این اتفاق می‌افتد اگر توکن API را در Pitchbar بازسازی کرده باشید (که یک shopper_signing_secret جدید می‌چرخاند) بدون اینکه "تست اتصال" را در وردپرس دوباره اجرا کنید. دوباره روی تست اتصال کلیک کنید — افزونه کلید مخفی جدید را به‌طور بی‌صدا دریافت می‌کند.
3. کلید مخفی امضا در سمت وردپرس خالی است. به‌عنوان plugin_unconfigured به‌جای signature_mismatch برگردانده می‌شود. نشان می‌دهد که افزونه از یک نصب قبل از نسخه ۱.۱.۰ ارتقا یافته است که در آن کلید مخفی وجود نداشت. دوباره روی تست اتصال کلیک کنید.
4. یک پراکسی معکوس بدنه درخواست را تغییر می‌دهد. بازنویسی‌های HTML Cloudflare، افزونه‌های امنیتی مانند اسکن درون‌خطی Wordfence و برخی قوانین mod_security می‌توانند بدنه JSON را در حین انتقال تغییر دهند. HMAC بر روی بایت‌های خام محاسبه می‌شود، بنابراین هر تغییری امضا را می‌شکند. /wp-json/pitchbar/v1/* را از قوانین بازنویسی/اسکن حذف کنید.

سایت RTL ویجت را در لبه اشتباه نشان می‌دهد

افزونه data-page-dir="rtl" و data-page-locale را روی تگ اسکریپت ویجت منتشر می‌کند. ویجت آنها را خوانده و نوار را به لبه راست نمای دید در زبان‌های عربی، عبری، فارسی و اردو آینه می‌کند.

• محلی اشتباه تشخیص داده شده است؟ تنظیمات وردپرس ← عمومی ← زبان سایت را بررسی کنید. افزونه به determine_locale() (که لغوهای هر کاربر را محترم می‌شمارد) احترام گذاشته و به get_locale() بازمی‌گردد.
• پوسته سفارشی ویجت؟ اگر CSS ویجت را از طریق Customize لغو کرده‌اید، قوانین سفارشی شما ممکن است انواع RTL نداشته باشند. .pitchbar-bar را در DevTools بررسی کنید — زمانی که صفحه RTL است، باید dir="rtl" تنظیم شده باشد.

مدیریت افزونه هشدار "ووکامرس تشخیص داده نشد" را حتی با فعال بودن ووکامرس نشان می‌دهد

در نسخه v2.0.0+ این غیرممکن است — افزونه به woocommerce_loaded موکول می‌شود. اگر این را در یک نصب قدیمی می‌بینید، به نسخه v2.0.0 ارتقا دهید. علائم باگ نسخه v1.x:

• دکمه همگام‌سازی محصول از صفحه تنظیمات وجود ندارد.
• انتشار کوپن خالی است (هیچ کدی هرگز همگام‌سازی نمی‌شود).
• نقطه پایانی REST کوپن سبد خرید ۴۰۰ woocommerce_inactive برمی‌گرداند حتی اگر ووکامرس در /shop به‌خوبی اجرا شود.

خواندن لاگ‌های افزونه

افزونه از طریق Pitchbar\Support\Logger در error_log می‌نویسد. برای دیدن آنها در یک نصب معمولی وردپرس:

1. WP_DEBUG_LOG را در wp-config.php روی true تنظیم کنید.
2. رویدادهای افزونه در wp-content/debug.log با پیشوند [pitchbar] ظاهر می‌شوند.
3. خطوط قابل توجه: "Plugin REST HMAC mismatch"، "PostSyncer batch failed"، "CouponSyncer hydrate failed"، "Lead user create failed".

محل ثبت مسئله

اگر هیچ‌یک از موارد بالا مشکل شما را حل نکرد، یک مسئله با موارد زیر باز کنید:

• نسخه افزونه (قابل مشاهده در بالای wp-plugin/pitchbar/pitchbar.php یا در مدیریت افزونه‌ها).
• نسخه وردپرس + نسخه PHP (قابل مشاهده در ابزارها ← سلامت سایت ← اطلاعات ← وردپرس).
• نسخه ووکامرس (در صورت وجود).
• سازنده صفحه فعال + نسخه آن (در صورت وجود).
• انتهای wp-content/debug.log مربوطه.
• یک بازتولید حداقلی: کدام دکمه را کلیک کرده‌اید، چه انتظاری داشتید، چه اتفاقی افتاد.