نصب و اتصال

این صفحه نحوه نصب افزونه وردپرس Pitchbar در یک سایت جدید وردپرس، اتصال آن به فضای کاری Pitchbar و تأیید بارگذاری ویجت در فرانت‌اند را توضیح می‌دهد.

زمان کل: حدود ۳ دقیقه در یک نصب ساده وردپرس + ووکامرس. افزونه کاملاً مستقل است — بدون نیاز به composer install، بدون مرحله ساخت، بدون وابستگی به CDN خارجی.

پیش‌نیازها

• یک فضای کاری Pitchbar (در آدرس فضای کاری خود ثبت‌نام کنید یا از مدیر پلتفرم خود بخواهید یکی ایجاد کند).
• وردپرس ۶.۴ یا جدیدتر که روی PHP ۷.۴ یا جدیدتر اجرا می‌شود.
• نقش مدیر یا مالک فضای کاری در Pitchbar (صفحه توکن‌های API فقط برای مدیران قابل دسترسی است؛ بیننده/ویرایشگر مسدود هستند).
• بایگانی pitchbar-{version}.zip — بخش "از کجا فایل زیپ را دریافت کنم؟" را در زیر مشاهده کنید.

از کجا فایل زیپ را دریافت کنم؟

سه مسیر، هر کدام را که با تنظیمات شما مطابقت دارد انتخاب کنید:

1. از فضای کاری Pitchbar خود — یک مدیر ارشد /admin/integrations/wordpress را باز می‌کند، روی ساخت آخرین نسخه و سپس دانلود کلیک می‌کند. بایگانی در سمت سرور در storage/app/private/wp-plugin-builds/pitchbar-{version}.zip قرار دارد.
2. از خط فرمان در میزبان Pitchbar: php artisan pitchbar:build-wp-plugin فایل زیپ را نوشته و مسیر آن را چاپ می‌کند.
3. از یک نصب فضای کاری موجود — اگر مالک پلتفرم قبلاً بایگانی را برای شما توزیع کرده است، همان فایل زیپ است. نیازی به بازسازی نیست.

مرحله ۱. آپلود و فعالسازی

1. در مدیریت وردپرس، افزونه‌ها ← افزودن جدید ← آپلود افزونه را باز کنید.
2. pitchbar-{version}.zip را انتخاب کرده و روی نصب اکنون کلیک کنید.
3. روی فعالسازی افزونه کلیک کنید.
4. یک اعلان آبی در بالای هر صفحه مدیریت ظاهر می‌شود: "Pitchbar نصب شده است اما هنوز پیکربندی نشده است. برای اتصال، تنظیمات ← Pitchbar را باز کنید."

افزونه تا مرحله ۳ هیچ رفتاری در فرانت‌اند ندارد — تا زمانی که یک آدرس فضای کاری + توکن را ذخیره نکنید، ویجت هرگز نمایش داده نمی‌شود.

مرحله ۲. ایجاد توکن API فضای کاری در Pitchbar

1. وارد فضای کاری Pitchbar خود شوید.
2. تنظیمات ← توکن‌های API را باز کنید.
3. روی ایجاد توکن کلیک کنید. آن را به نام سایت وردپرس نام‌گذاری کنید (مثلاً shop.example.com).
4. قابلیت wp:integration را اعطا کنید.
5. Pitchbar توکن ساده را دقیقاً یک بار نمایش می‌دهد. فرمت: pbar_ + ۴۸ کاراکتر الفبایی. آن را همین حالا کپی کنید — فقط هش SHA-256 ذخیره می‌شود، بنابراین اگر توکن ساده را گم کنید، باید آن را لغو کرده و دوباره صادر کنید.

همین صفحه همچنین در زمان ایجاد توکن، یک shopper_signing_secret تولید می‌کند که افزونه به‌طور خودکار در اولین دست دادن آن را دریافت می‌کند (هرگز نیازی به چسباندن آن ندارید). برای مشاهده کاربرد این کلید مخفی، به مرجع REST API مراجعه کنید.

مرحله ۳. اتصال وردپرس به Pitchbar

1. در مدیریت وردپرس، تنظیمات ← Pitchbar را باز کنید.
2. آدرس پایه فضای کاری Pitchbar خود را (مثلاً https://app.pitchbar.example) در آدرس پایه Pitchbar وارد کنید. اسلش‌های انتهایی به‌طور خودکار حذف می‌شوند.
3. توکن API که تازه ایجاد کرده‌اید را در توکن API وارد کنید.
4. روی تست اتصال کلیک کنید. دکمه غیرفعال می‌شود، خط وضعیت "در حال تست اتصال…" را نشان می‌دهد و در عرض چند ثانیه یا یک تأیید سبز یا یک خطای قرمز دریافت می‌کنید.
5. در صورت موفقیت: منوی کشویی خالی دستیار فروش با لیستی از تمام دستیاران فروش فضای کاری شما پر می‌شود و نام فضای کاری در زیر نمایش داده می‌شود ("متصل به فضای کاری: فروشگاه آکمه"). افزونه همچنین کلید مخفی امضای خریدار را به‌طور بی‌صدا دریافت کرده و در wp_options ذخیره می‌کند.
6. انتخاب کنید کدام دستیار فروش باید در این سایت اجرا شود. هر دستیار فروش یک ورودی جداگانه در منوی کشویی با نوع سایت خود دریافت می‌کند (مثلاً ربات فروشگاه (فروشگاهی)).
7. تأیید کنید که کلید فعال در بخش "نمایش ویجت" علامت‌خورده است.
8. نوع پست‌هایی را که می‌خواهید ویجت روی آنها بارگذاری شود، علامت بزنید. پیش‌فرض‌ها: post + page. نوع‌های پست سفارشی و (در صورت فعال بودن ووکامرس) product به‌عنوان چک‌باکس‌های اضافی ظاهر می‌شوند.
9. روی ذخیره تغییرات کلیک کنید.

مرحله ۴. تأیید نصب فرانت‌اند

1. یک صفحه عمومی در سایت وردپرس خود باز کنید (صفحه اصلی، پست وبلاگ، صفحه محصول — هر چیزی که با نوع پست‌های فعال‌شده مطابقت داشته باشد).
2. نوار Pitchbar در ناحیه فوتر ظاهر می‌شود. به‌طور پیش‌فرض از لبه پایین به داخل انیمیشن می‌شود.
3. برای باز کردن پنل چت، روی نوار کلیک کنید. یک سوال تایپ کنید — دستیار فروش پاسخ را پخش می‌کند.

اگر ویجت هرگز ظاهر نشد، عیب‌یابی را بررسی کنید — رایج‌ترین دلیل، تمی است که wp_footer() را حذف کرده است، یا یک افزونه کش که یک تصویر HTML قدیمی ارائه می‌دهد.

آنچه در سمت سرور ذخیره می‌شود

دو بخش در جدول wp_options وردپرس با کلید pitchbar_settings ذخیره می‌شوند (متن ساده، زیرا گزینه‌های وردپرس در حالت استراحت رمزگذاری نمی‌شوند):

• توکن API — مقدار کامل متن ساده. سطح اعتماد: مشابه یک کلید مخفی wp-config.php. هر زمان که بخواهید آن را باطل کنید، از فضای کاری Pitchbar خود لغو کنید.
• shopper_signing_secret — کلید مخفی ساده به ازای هر توکن که Pitchbar برای امضای HMAC بازخوانی‌ها به سایت WP شما (جستجوی سفارش، اعمال کوپن، ارسال مشتری) استفاده می‌کند. در اولین تست اتصال به‌طور خودکار دریافت می‌شود.
• دستیار فروش انتخاب‌شده، شناسه فضای کاری، نام فضای کاری، نوع پست‌های فعال، پرچم فعال — یک بلوک پیکربندی کوچک.

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

در زمان (باز-)فعالسازی چه اتفاقی می‌افتد

اگر افزونه در زمان فعالسازی قبلاً پیکربندی شده باشد (یک چرخه غیرفعال → فعال در یک نصب موجود)، یک همگام‌سازی کامل یک‌باره ۳۰ ثانیه بعد از طریق wp_schedule_single_event در هوک pitchbar_run_full_sync_event زمان‌بندی می‌شود. زمانی که ووکامرس فعال باشد، یک رویداد دوم برای محصولات ۶۰ ثانیه بعد زمان‌بندی می‌شود (تا پست‌ها اول تمام شوند). این به این معنی است که آپلود یک نسخه جدید افزونه، محتوای قدیمی را سرگردان نمی‌گذارد. تیک بعدی wp-cron، پایگاه دانش دستیار فروش را بازخوانی می‌کند.

غیرفعال کردن افزونه، هر دو هوک زمان‌بندی‌شده را از طریق wp_clear_scheduled_hook پاک می‌کند تا پس از خاموش شدن افزونه، چیزی فعال نشود.

محل نمایش افزونه در مدیریت وردپرس

• تنظیمات ← Pitchbar — صفحه پیکربندی واحد برای همه چیز (اتصال، انتخابگر دستیار فروش، کلیدهای نوع پست، دکمه‌های همگام‌سازی).
• اعلان مدیریت افزونه‌ها — بنر آبی ملایم در حالی که افزونه پیکربندی نشده است، یا در حالی که یک همگام‌سازی تکه‌تکه در پس‌زمینه در حال اتمام است.
• مدیریت کاربران — مشتریان بالقوه ارسال‌شده به‌عنوان کاربران وردپرس (نقش مشترک در غیر ووکامرس، مشتری ووکامرس در ووکامرس) با pitchbar_lead_id + pitchbar_conversation_id در متاداده کاربر ذخیره می‌شوند.

مجوزها

صفحه تنظیمات و تمام اقدامات AJAX نیاز به قابلیت manage_options دارند — همان چیزی که وردپرس برای "تنظیمات عمومی" استفاده می‌کند. ویرایشگران، نویسندگان و مشارکت‌کنندگان نمی‌توانند به آن دسترسی پیدا کنند. مدیران ارشد چندسایتی نیز بررسی را پشت سر می‌گذارند.

نقاط پایانی REST (/wp-json/pitchbar/v1/*) عمداً عمومی هستند (permission_callback => __return_true) و در عوض با امضای HMAC در هر درخواست احراز هویت می‌شوند. مشاهده کنید مرجع REST API.

حذف نصب تمیز

1. افزونه‌ها را در مدیریت وردپرس باز کنید.
2. در کنار Pitchbar روی غیرفعال کردن کلیک کنید. رویدادهای همگام‌سازی زمان‌بندی‌شده پاک می‌شوند.
3. روی حذف کلیک کنید. وردپرس uninstall.php را فراخوانی می‌کند که گزینه pitchbar_settings و پرچم pitchbar_activation_flag را حذف می‌کند.
4. توکن API وردپرس را در /settings/api-tokens در Pitchbar لغو کنید تا متن ساده‌ای که در wp_options بود، بلافاصله از بین برود.

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