دامنه‌های مجاز

اسکریپت ویجت عمداً عمومی است — هر کسی می‌تواند /widget/widget.js را دریافت کند. به همین دلیل، دامنه‌های مجاز مرز اعتماد را تعیین می‌کنند تا از نصب قطعه‌کد شما در سایت شخص ثالث و مصرف سهمیه‌تان جلوگیری کنند.

قرارداد

هر درخواست POST /v1/widget/init هدر Origin درخواست (یا Referer به‌عنوان جایگزین) را خوانده و آن را با لیست allowed_origins دستیار فروش مقایسه می‌کند. قوانین به این صورت هستند:

1. لیست خالی → ۴۰۳. همه‌جا رد می‌شود. دستیارهای جدید تا زمانی که حداقل یک دامنه اضافه کنید، خالی شروع می‌شوند.
2. علامت عام "*" → مجاز. یک راه فرار اختیاری برای ابزارهای داخلی و دموها. هرگز به‌عنوان پیش‌فرض تنظیم نشود.
3. در غیر این صورت → تطابق دقیق scheme://host. هیچ استنباط زیردامنه‌ای وجود ندارد. https://example.com به https://app.example.com اجازه نمی‌دهد.

هر فراخوانی با مجوز، دوباره Origin را بررسی می‌کند

نقطه‌ی پایانی init جایی است که JWT صادر می‌شود — اما JWT یک توکن حامل است و توکن‌های حامل ممکن است نشت کنند (لاگ نشتی، ابزارهای توسعه‌دهنده مرورگر، XSS در سایت قربانی، MITM در ارتباطات غیررمزگذاری‌شده). برای جلوگیری از استفاده‌ی مجدد از JWT دزدیده‌شده از attacker.example، تمام نقاط پایانی ویجت با مجوز از طریق میان‌افزار VerifyWidgetOrigin عبور می‌کنند که در هر فراخوانی، Origin درخواست را در برابر allowed_origins دستیار فروش متصل به JWT دوباره تأیید می‌کند:

• POST /v1/widget/messages
• POST /v1/widget/messages/stream (SSE)
• POST /v1/widget/leads
• POST /v1/widget/request-human
• POST /v1/widget/events
• POST /v1/widget/typing
• POST /v1/widget/satisfaction
• POST /v1/widget/coupon/apply
• POST /v1/widget/conversation/clear
• GET /v1/widget/conversation/messages
• DELETE /v1/widget/me

سیاست مشابه /v1/widget/init است — لیست خالی = رد، "*" = مجاز (شامل بدون Origin)، ورودی‌های خاص = تطابق دقیق نرمال‌شده — بنابراین درخواستی که init تأیید کرده باشد، هرگز توسط میان‌افزار پس از init رد نمی‌شود و درخواستی که init رد کرده باشد، هرگز نمی‌تواند از آن عبور کند.

تطابق دقیق زیردامنه

این قانونی است که معمولاً افراد را غافلگیر می‌کند، بنابراین شایسته‌ی یک توضیح جداگانه است:

اگر واقعاً همه‌ی زیردامنه‌ها را می‌خواهید، آنها را جداگانه لیست کنید:

https://example.com
https://www.example.com
https://app.example.com
https://docs.example.com

افزودن دامنه‌ها

از صفحه‌ی تنظیمات دستیار فروش (/app/agents/{id}/settings)، کارت دامنه‌های مجاز دارای یک textarea است — هر دامنه در یک خط. ذخیره، دستیار را بلافاصله به‌روز می‌کند؛ درخواست‌های جدید init در عرض چند ثانیه از لیست جدید استفاده می‌کنند.

دامنه‌ها باید شامل پروتکل باشند:

تست محلی

در زمان توسعه، http://localhost:3000 (یا هر پورتی که استفاده می‌کنید) را به دامنه‌های مجاز دستیار اضافه کنید. برای این کار از "*" استفاده نکنید — باقی ماندن آن به‌طور تصادفی در محیط تولید، دستیار را باز می‌گذارد.

در صورت رد شدن چه اتفاقی می‌افتد

یک درخواست از دامنه‌ی غیرمجاز، یک پاسخ JSON ۴۰۳ دریافت می‌کند:

{
    "error": {
        "code": "origin_forbidden",
        "message": "Origin is not allowed for this agent."
    }
}

بارگذار ویجت این خطا را به‌خوبی مدیریت می‌کند — راه‌انداز به‌جای نمایش خطا در کنسول، به‌صورت بی‌صدا ناپدید می‌شود، بنابراین بازدیدکنندگان هرگز یک رابط خراب نمی‌بینند. خطای ۴۰۳ در سمت پلتفرم ثبت می‌شود تا بتوانید الگوهای سوءاستفاده را مشاهده کنید.

دامنه‌های هم‌میزبان چطور؟

بررسی از پروتکل + میزبان استفاده می‌کند، بنابراین http در مقابل https متمایز هستند (همانطور که باید باشند). و پورت‌های مختلف، دامنه‌های متفاوتی هستند (http://localhost:3000 ≠ http://localhost:3001).

علامت‌های عام: چه زمانی استفاده کنیم، چه زمانی نه

"*" برای مواردی وجود دارد که واقعاً از قبل دامنه را نمی‌دانید:

• دستیارهای دموی داخلی که در سایت پیش‌نمایش هر مشتری بالقوه نصب می‌شوند.
• محیط‌های سندباکس / پیش‌نمایش که دامنه‌ها روزانه تغییر می‌کنند.

برای دستیارهای تولید، هرگز. هزینه‌ی فراموش کردن "*" این است که هر کسی که data-agent-id شما را پیدا کند، می‌تواند سهمیه‌ی شما را مصرف کند. هزینه‌ی یک لیست دقیق، یک دقیقه به ازای هر دامنه‌ی جدید است.

مسیرهای محدود — همراه در سطح مسیر

دامنه‌های مجاز مرز اعتماد را در سطح دامنه تعیین می‌کند (فقط https://shop.example.com می‌تواند ویجت را بارگذاری کند). مسیرهای محدود خواهر آن است: لیستی از مسیرهای داخل یک دامنه‌ی از قبل مجاز که ویجت نباید روی آنها نصب شود. از آن برای دور نگه داشتن ربات از /admin، /checkout یا /account خود بدون تغییر کد استفاده کنید.

هر ورودی یک glob است — * تنها علامت عام است و به‌صورت حریصانه در بین اسلش‌ها تطابق داده می‌شود. مقایسه نسبت به window.location.pathname، حساس به حروف بزرگ و کوچک نیست:

نحوه‌ی کار در زمان اجرا

لیست restricted_paths دستیار، در پاسخ POST /v1/widget/init همراه با بقیه‌ی تنظیمات ارسال می‌شود. پس از موفقیت init، ویجت window.location.pathname را با لیست مقایسه می‌کند — اگر هر الگویی مطابقت داشته باشد، نوار هرگز نصب نمی‌شود، موتور محرک هرگز شروع نمی‌شود و هیچ درخواست HTTP دیگری در آن صفحه انجام نمی‌شود. خود فراخوانی init انجام می‌شود (سرور منبع حقیقت است)، بنابراین اگر هزینه‌ی آن مهم است، از allowed_origins در سطح تگ اسکریپت برای میزبان استفاده کنید.

نویسندگی

از صفحه‌ی تنظیمات دستیار، کارت مسیرهای محدود دارای یک textarea است — هر مسیر در یک خط. همان تجربه‌ی کاربری دامنه‌های مجاز. لیست خالی = بدون محدودیت (ویجت در همه‌جا در یک دامنه‌ی مجاز نصب می‌شود). حداکثر ۳۲ ورودی، هر کدام حداکثر ۲۰۰ کاراکتر.

چرا این یک تنظیم جداگانه از احراز هویت است

پلتفرم همچنین ویجت دموی بازاریابی را در مسیرهای مدیریت/مشتری تأییدشده از طریق یک بررسی سمت سرور در طرح‌بندی اصلی اینرسی، به‌طور خودکار غیرفعال می‌کند — این یک تضمین سخت است که به تنظیمات دستیار بستگی ندارد. restricted_paths پسوند سمت خریدار است: حتی در یک سایت بازاریابی کاملاً بدون احراز هویت، /checkout نباید با یک ربات چت فروش شلوغ شود.

نحوه‌ی استفاده از دامنه‌ها در پردازش خودکار

پردازش خودکار از همان لیست مجاز استفاده می‌کند، اما با یک نکته در زمانی که "*" تنظیم شده باشد: آدرس صفحه‌ای که به‌طور خودکار نمایه می‌شود باید با هدر Origin واقعی بازدیدکننده مطابقت داشته باشد. این کار از پردازش صفحات دلخواه شخص ثالث از طریق علامت عام جلوگیری می‌کند.