نصب ویجت

نصب قطعه‌کد

ویجت یک تگ <script> ساده است. آن را در هر صفحه‌ای قرار دهید، یک شناسه دستیار فروش را وارد کنید و ویجت فعال می‌شود. حجم بسته ≤۵۰ کیلوبایت gzip شده است، در یک Shadow DOM اجرا می‌شود تا توسط سایت شما استایل‌دهی نشود و هرگز بارگذاری صفحه را مسدود نمی‌کند (async است).

قطعه کد

این قطعه را درست قبل از </body> قرار دهید:

<script
    src="https://your-app.test/widget/widget.js?v=ab12cd34"
    data-agent-id="01HXY..."
    async></script>

قطعه کامل (با شناسه دستیار فروش و هش شکستن کش فعلی) در صفحه تنظیمات هر دستیار فروش، کنار دکمه کپی قرار دارد.

محتوای آدرس

src — به /widget/widget.js در استقرار Pitchbar شما اشاره می‌کند. پسوند ?v=<hash> هش محتوای بسته است؛ هر بار که ویجت بازسازی می‌شود تغییر می‌کند، بنابراین مشتریان روی نسخه‌های قدیمی کش‌شده توسط CDN گیر نمی‌کنند.
data-agent-id — شناسه ULID دستیار فروش منتشرشده. بارگذار ویجت این ویژگی را خوانده و در هر فراخوانی /v1/widget/init از آن استفاده می‌کند.
async — غیرمسدودکننده. ویجت پس از اتمام دانلود بسته ظاهر می‌شود؛ معیارهای بارگذاری صفحه شما تحت تأثیر قرار نمی‌گیرند.

چه چیزی تزریق می‌کند

در زمان راه‌اندازی، بارگذار:

یک <div> در پایین <body> ایجاد کرده و یک Shadow DOM به آن متصل می‌کند.
راه‌انداز (دکمه کوچک) را درون ریشه سایه نمایش می‌دهد.
برای دریافت پیکربندی دستیار فروش + JWT + تاریخچه اخیر، POST /v1/widget/init را فراخوانی می‌کند.
شنونده‌های محرک (اسکرول، بیکاری، قصد خروج) را براساس قوانین رفتار دستیار فروش متصل می‌کند.
یک anon_id کوچک در localStorage ذخیره می‌کند تا همان مرورگر مکالمه را در بارگذاری‌های مجدد حفظ کند.

سفارشی‌سازی راه‌انداز

ظاهر کاملاً توسط دستیار فروش هدایت می‌شود — مشاهده کنید شخصیت، ظاهر و راهنماها. ویجت theme.position، theme.primary، theme.accent، theme.radius و theme.launcher_label را از پاسخ راه‌اندازی خوانده و براساس آن نمایش می‌دهد.

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

کنترل برنامه‌نویسی

ویجت یک متغیر سراسری واحد، window.Pitchbar.mount() را در معرض دید قرار می‌دهد که بارگذار برای راه‌اندازی از آن استفاده می‌کند. ویژگی async تگ اسکریپت و بارگذاری خودکار، حالت رایج را برای شما مدیریت می‌کند، بنابراین معمولاً نیازی به فراخوانی مستقیم این تابع ندارید.

// نصب ویجت در یک عنصر میزبان سفارشی (نادر).
window.Pitchbar.mount(document.getElementById('chat-host'));

هنوز API عمومی open / close / send / on وجود ندارد — این موارد به تعویق افتاده‌اند. اگر امروز نیاز به ارسال تحلیل‌های تبدیل در زمان جذب مشتری دارید، به‌جای آن در وب‌هوک lead.captured مشترک شوید (مشاهده کنید وب‌هوک‌های خروجی).

برنامه‌های تک صفحه‌ای

ویجت در هر بار بارگذاری صفحه یک بار بارگذاری می‌شود، اما مکالمه تا زمانی که تگ اسکریپت در DOM باقی بماند، در بین ناوبری‌های درون برنامه‌ای حفظ می‌شود. زمانی که مسیریاب شما مسیرها را تغییر می‌دهد، نیازی به نصب مجدد آن ندارید — Shadow DOM و JWT باقی می‌مانند.

اگر برنامه تک صفحه‌ای شما در تغییر مسیرها کاملاً دوباره نصب می‌شود (مثلاً بدنه را حذف می‌کنید)، ویجت دوباره راه‌اندازی شده و مکالمه بازدیدکننده را از ۲۴ ساعت تاریخچه اخیر ادامه می‌دهد.

در هر راه‌اندازی چه چیزی ارسال می‌شود

یک درخواست POST /v1/widget/init شامل موارد زیر است:

agent_id — مقدار از data-agent-id.
page_url — location.href فعلی، برای تقویت "صفحه فعلی" در بازیابی استفاده می‌شود.
anon_id — شناسه پایدار بازدیدکننده از localStorage که در اولین بازدید تولید شده است.

سرور همچنین هدرهای Origin، Referer و Accept-Language را می‌خواند — Origin برای بررسی دامنه مجاز، Accept-Language برای تشخیص زبان پیش‌فرض.

نسخه‌گذاری و کش

بخش مسیر /widget/widget.js در همه استقرارها پایدار است. مشتریان قطعه را یک بار قرار می‌دهند و هرگز نیازی به لمس مجدد آن ندارند — به‌روزرسانی‌های بسته به‌صورت شفاف ارسال می‌شوند. پرسش ?v=<hash> در هر ساخت تغییر می‌کند، که کش مرورگر را در صفحات موجود بدون تغییر آدرسی که مشتری در سایت خود قرار داده است، می‌شکند.

در داخل، /widget/widget.js توسط WidgetBundleController ارائه می‌شود که آخرین بسته هش‌شده را که در public/widget/manifest.json نامگذاری شده است، با Cache-Control: no-cache, must-revalidate و یک ETag قوی پخش می‌کند. فایل هش‌شده (widget.<hash>.js) ساخته‌شده روی دیسک است؛ آدرس پایدار، قرارداد عمومی است.

قبل از رفع (۲۰۲۶-۰۵-۲۹)، قطعه نصب، نام فایل هش‌شده را مستقیماً نمایش می‌داد (مثلاً widget.abc123.js)؛ هر ساخت جدید آدرس را تغییر می‌داد و تگ‌های <script> چسبانده‌شده مشتریان با خطای ۴۰۴ مواجه می‌شدند. رفع در AgentController::widgetUrl() و OnboardingController::buildWidgetSrc() انجام شد.