لینک‌های عمیق ووکامرس

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

در صورتی که ووکامرس بارگذاری نشده باشد، هیچ‌یک از این نقاط پایانی اجرا نمی‌شوند — افزونه هر وابستگی به ووکامرس را به اکشن woocommerce_loaded موکول می‌کند تا ترتیب بارگذاری الفبایی افزونه‌ها تأثیری نداشته باشد.

رقابت ترتیب بارگذاری ووکامرس

بسیاری از یکپارچه‌سازی‌های وردپرس پیش از نسخه‌ی ۲.۰ یک باگ ظریف دارند: تابع class_exists('WooCommerce') را در اولویت ۱۰ اکشن plugins_loaded فراخوانی می‌کنند و وقتی بررسی مقدار false برمی‌گرداند، قابلیت‌های ووکامرس را بی‌صدا غیرفعال می‌کنند. در سایت‌هایی که افزونه‌ی یکپارچه‌سازی از نظر الفبایی پیش از woocommerce/ بارگذاری می‌شود (مثلاً pitchbar < woocommerce)، کلاس اصلی ووکامرس تا اولویت ۱۰ ثبت نشده است → مقدار false → یکپارچه‌سازی خراب بدون هیچ پیام خطایی.

Pitchbar نسخه‌ی ۲.۰.۰ از یک محافظ دولایه استفاده می‌کند:

if (function_exists('did_action') && did_action('woocommerce_loaded') > 0) {
    $this->bootWoo();   // ووکامرس قبلاً بارگذاری شده — بلافاصله متصل شو.
} else {
    add_action('woocommerce_loaded', [$this, 'bootWoo'], 10);
}

اکشن woocommerce_loaded پس از ثبت کامل کلاس اصلی ووکامرس اجرا می‌شود، بنابراین تا زمانی که bootWoo() اجرا می‌شود، تمام بررسی‌های class_exists('WooCommerce') به‌طور قطعی با موفقیت انجام می‌شوند.

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

زمانی که یک مشتری ووکامرس وارد حساب خود شده و صفحه‌ای را بازدید می‌کند که ویجت را بارگذاری می‌کند، افزونه یک توکن امضاشده‌ی data-shopper-token با عمر کوتاه به تگ اسکریپت ویجت متصل می‌کند. ویجت آن را به /api/v1/widget/init ارسال می‌کند؛ Pitchbar آن را تأیید کرده و ادعاهای wp_user_id و email_hash را در JWT ویجت برای جلسه‌ی گفتگو تعبیه می‌کند.

آنچه در توکن رمزگذاری شده است:

• wp_user_id — شناسه‌ی کاربر وردپرس (عدد صحیح، به‌صورت رشته در توکن ارسال می‌شود).
• email_hash — SHA-256 از ایمیل با حروف کوچک. هرگز ایمیل خام ذخیره نمی‌شود.
• source — مقدار ثابت "wordpress".
• exp — زمان‌مهر یونیکس، حدود ۲۴ ساعت بعد تا همان توکن در طول یک جلسه‌ی مرورگری معمولی معتبر باشد.

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

ابزار lookup_order

قابلیت order_status در EcommercePreset به یک ابزار واقعی نگاشت می‌شود. وقتی بازدیدکننده درباره‌ی سفارشات، حمل‌ونقل، بازگشت کالا یا بازپرداخت سؤال می‌کند، مدل زبانی بزرگ (LLM) ممکن است تابع lookup_order(limit, order_number?) را فراخوانی کند. این ابزار:

1. ادعاهای مشتری ذخیره‌شده‌ی گفتگو را می‌خواند (که در /widget/init تنظیم شده‌اند).
2. site_url منبع woocommerce_products دستیار فروش را پیدا می‌کند.
3. shopper_signing_secret را از هر توکن API فعال فضای کاری دریافت می‌کند.
4. بدنه‌ای با امضای HMAC را به آدرس {site_url}/wp-json/pitchbar/v1/orders/lookup با زمان توقف سخت ۵ ثانیه ارسال می‌کند.
5. پاسخ سفارشات را دقیقاً به مدل زبانی بزرگ برمی‌گرداند تا خلاصه‌سازی کند.

مسیرهای رد (بدون فراخوانی پاسخ‌گویی):

• هیچ ادعای مشتری در گفتگو وجود نداشته باشد → not_signed_in. مدل زبانی بزرگ از بازدیدکننده می‌خواهد وارد شود.
• هیچ منبع woocommerce_products وجود نداشته باشد → no_wordpress_source.
• هیچ توکن API فعال با کلید امضا وجود نداشته باشد → no_signing_secret.

کنترلر OrderLookupController افزونه حداکثر ۱۰ سفارش را برمی‌گرداند (به‌طور پیش‌فرض ۵)، که هر کدام شامل شناسه، شماره، وضعیت، مجموع، واحد پول، آرایه‌ی اقلام، آدرس رهگیری (با بهترین تلاش در AfterShip، رهگیری ST، متادیتای عمومی _tracking_url) و آدرس مشاهده‌ی سفارش مشتری است.

در صورت سؤال بازدیدکننده درباره‌ی سفارش خاص، روی order_number فیلتر کنید — افزونه مجموعه‌ی نتایج را پس از جستجوی شناسه‌ی مشتری فیلتر می‌کند تا هرگز داده‌های مشتری دیگری در معرض دید قرار نگیرد.

بازگردانی مشتری بالقوه

هنگامی که دستیار فروش گفتگو یک مشتری بالقوه را ثبت می‌کند (بازدیدکننده ایمیلی ثبت می‌کند یا فرم مشتری بالقوه را ارسال می‌کند)، Pitchbar آن مخاطب را به سایت وردپرس بازمی‌گرداند:

تیگر	عملیات
LeadCapturedEvent	شنونده‌ی صف‌شده‌ی PushLeadToWordPress اجرا می‌شود. منبع وردپرس یا ووکامرس دستیار فروش را پیدا می‌کند، بدنه‌ای با امضای HMAC را با کلید امضای مشتری فضای کاری امضا کرده و به آدرس /wp-json/pitchbar/v1/leads ارسال می‌کند.
وردپرس فراخوانی را دریافت می‌کند	اگر ووکامرس فعال باشد، افزونه یک مشتری ووکامرس از طریق wc_create_new_customer ایجاد می‌کند. در غیر این صورت یک کاربر مشترک وردپرس می‌سازد. pitchbar_lead_id و pitchbar_conversation_id در متادیتای کاربر ذخیره می‌شوند تا صاحب فروشگاه بتواند کاربر وردپرس را با رونوشت گفتگوی Pitchbar مرتبط کند.

این فرآیند براساس ایمیل توانایی تکرارپذیری دارد: ارسال مجدد برای همان آدرس، به‌جای ایجاد کاربر تکراری، first_name، billing_phone، pitchbar_lead_id و pitchbar_conversation_id کاربر موجود را به‌روزرسانی می‌کند. خطاهای انتقال ثبت شده و نادیده گرفته می‌شوند — شنونده هرگز پاسخ گفتگوی بازدیدکننده را مسدود نمی‌کند.

صدور و اعمال کد تخفیف

دستیاران فروش حوزه‌ی فروشگاهی می‌توانند زمانی که قصد بازدیدکننده با یک کد تخفیف فعال ووکامرس همخوانی دارد، یک بلوک <coupon/> در پاسخ‌های گفتگو صادر کنند. جریان کامل داده:

1. CouponSyncer افزونه پس از هر همگام‌سازی محصول اجرا می‌شود، پست‌های shop_coupon با وضعیت انتشار را شمارش می‌کند، موارد منقضی‌شده یا بیش‌ازحد را فیلتر کرده و تصویر لحظه‌ای را به /api/v1/wp/coupons/sync ارسال می‌کند.
2. Pitchbar لیست را در آرایه‌ی config['coupons'] منبع ذخیره می‌کند (حداکثر ۵۰ مورد).
3. PromptBuilder هنگام ساخت پرامپت سیستمی برای دستیاران فروش فروشگاهی، آنها را می‌خواند. مدل زبانی بزرگ لیست کامل کدها و یک دستورالعمل صریح مبنی بر عدم اختراع کد دریافت می‌کند.
4. هنگامی که مدل زبانی بزرگ تشخیص دهد کد تخفیف به بازدیدکننده کمک می‌کند، یک نشانگر XML صادر می‌کند: <coupon code="WELCOME10" label="10% off your first order" discount="10%"/>.
5. InlineBlockParser نشانگر را پس از جریان استخراج کرده و یک رویداد SSE از نوع block با نوع coupon_card صادر می‌کند.
6. نمایش‌دهنده‌ی blocks.tsx ویجت یک کارت با دکمه‌های کپی (کد را در کلیپ‌بورد می‌نویسد) و اعمال نمایش می‌دهد.
7. دکمه‌ی اعمال یک درخواست POST به /api/v1/widget/coupon/apply در Pitchbar ارسال می‌کند.
8. Pitchbar بدنه را با کلید امضای مشتری فضای کاری امضای HMAC کرده و به /wp-json/pitchbar/v1/cart/coupon در سایت وردپرس ارسال می‌کند.
9. از آنجا که درخواست REST معمولاً WC()->cart بارگذاری‌شده‌ای ندارد، افزونه کد را در یک داده‌ی موقت ۱۵ دقیقه‌ای ذخیره می‌کند: pitchbar_pending_coupon_{conversation_id}.
10. در بارگذاری صفحه‌ی بعدی بازدیدکننده، هوک woocommerce_load_cart_from_session افزونه داده‌ی موقت را از طریق کوکی pitchbar_conv_id (که توسط ویجت در زمان مقداردهی اولیه تنظیم شده) می‌خواند و WC()->cart->apply_coupon($code) را فراخوانی می‌کند.
11. داده‌ی موقت پس از اعمال موفق حذف می‌شود؛ داده‌های موقت منقضی‌شده پس از ۱۵ دقیقه خودپاک‌سازی می‌شوند.

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

تعامل مجدد با سبد خرید رها شده

BehaviorRule.kind = "abandoned_cart" به شما امکان می‌دهد با بازدیدکننده‌ای که سبد خریدش مدتی غیرفعال بوده، تعامل مجدد داشته باشید.

ذخیره‌سازی وضعیت سبد خرید در localStorage

افزونه cart-state.js را در هر صفحه‌ی جلوی سایت هنگام فعال‌بودن ووکامرس بارگذاری می‌کند. هر رویداد جی‌کوئری سبد خرید ووکامرس را در localStorage.pitchbar_cart_state ذخیره می‌کند:

{
  "items": 2,           // تعداد جاری
  "timestamp": 1715472000000  // میلی‌ثانیه از زمان آخرین تغییر
}

به رویدادهای زیر گوش می‌دهد:

• رویداد جی‌کوئری added_to_cart → افزایش تعداد، به‌روزرسانی زمان‌مهر.
• رویداد جی‌کوئری removed_from_cart → کاهش تعداد؛ اگر به صفر یا کمتر رسید پاک می‌کند.
• کلیک DOM روی .add_to_cart_button / .single_add_to_cart_button به‌عنوان راهکار جایگزین بدون جی‌کوئری.
• مسیر URL شامل /checkout، /order-received، /order-pay، /thank-you → وضعیت سبد خرید را به‌کلی پاک می‌کند.

خطاهای ذخیره‌سازی (مرورگری خصوصی، فضای پر) بی‌صدا نادیده گرفته می‌شوند — تریگر برای آن بازدیدکننده اجرا نمی‌شود.

پیکربندی تریگر

در صفحه‌ی مدیریت تریگرهای رفتاری دستیار فروش، یک قانون جدید از نوع abandoned_cart اضافه کنید:

{
  "kind": "abandoned_cart",
  "conditions": { "idle_minutes": 5 },
  "action": {
    "kind": "open_with_message",
    "message": "هنوز در حال تصمیم‌گیری هستی؟ خوشحال می‌شیم کمک کنیم تصمیم بهتری بگیری — راهنمایی می‌خوای؟"
  }
}

TriggerEngine ویجت هر ۳۰ ثانیه یکبار ورودی localStorage را بررسی می‌کند (و یکبار بلافاصله پس از بارگذاری). وقتی سبد خرید غیرخالی قدیمی‌تر از آستانه‌ی idle_minutes قانون پیدا کند، اقدام قانون را اجرا می‌کند — معمولاً یک حباب تعامل پیش‌دستانه.

یک محدودیت سراسری ۵ دقیقه‌ای برای تریگرها همچنان اعمال می‌شود، بنابراین بازدیدکننده در هر تغییر صفحه غافلگیر نمی‌شود.

محموله‌ی زمینه‌ی صفحه (برای محصولات ووکامرس)

هنگامی که بازدیدکننده در صفحه‌ی یک محصول خاص است (is_product())، افزونه شیء JSON data-page-context را با یک آبجکت woo غنی‌سازی می‌کند:

{
  "source": "wordpress",
  "page_url": "https://shop.example/product/blue-tee",
  "post_id": 142,
  "post_type": "product",
  "permalink": "…",
  "categories": ["tees", "summer"],
  "tags": [],
  "woo": {
    "id": 142,
    "sku": "T-BLU-M",
    "name": "Blue tee",
    "permalink": "https://shop.example/product/blue-tee",
    "price": "29.00",
    "regular_price": "39.00",
    "sale_price": "29.00",
    "currency": "USD",
    "stock_status": "instock",
    "on_sale": true
  }
}

ویجت این اطلاعات را در پاکت بازیابی اطلاعات قرار می‌دهد تا دستیار فروش محتوای صفحه‌ای را که بازدیدکننده در حال حاضر در آن است ترجیح دهد (افزایش امتیاز صفحه‌ی جاری به میزان ۰.۱۵+ در امتیاز تکه‌ها).

چه نسخه‌هایی از ووکامرس پشتیبانی می‌شوند؟