نصب ویجت روی سایتت
راهنمای کامل نصب ویجت ونوک — از نصب ساده تا ورود خودکار مشتری و مدیریت Login/Logout.
شروع سریع
نصب ویجت در کمتر از یک دقیقه
برای نصب ویجت ونوک، کافی است اسکریپت زیر را قبل از بستهشدن تگ <body> در سایت خود قرار دهید. ویجت بهصورت خودکار لود شده و دکمهی شناور پشتیبانی در گوشهی سایت نمایش داده میشود.
<script
src="https://widget.venok.chat/widget/latest/widget.js"
data-widget-token="wgt_************"
data-api-base-url="https://api.venok.chat"
async
></script>در این حالت، ویجت بدون اطلاعات مشتری لود میشود و کاربر بهعنوان مهمان شناخته خواهد شد. برای ورود خودکار، بخش «ورود خودکار مشتری» را ببینید.
فیلدهای نصب
توضیح کامل تمام attributeهای اسکریپت
اسکریپت نصب ویجت از چند data-attribute برای پیکربندی استفاده میکند. در جدول زیر تمام فیلدها توضیح داده شدهاند:
| فیلد | الزامی | کاربرد |
|---|---|---|
| src | بله | آدرس فایل widget.js |
| data-widget-token | بله | شناسایی سازمان و تنظیمات ویجت |
| data-api-base-url | بله | آدرس API ونوک |
| data-customer-phone | برای Auto Login | شماره موبایل مشتری لاگینشده |
| data-customer-name | خیر، پیشنهاد میشود | نام نمایشی مشتری |
| data-external-user-id | برای Auto Login | شناسه یکتا و پایدار مشتری |
| async | خیر، پیشنهاد میشود | جلوگیری از مسدودشدن لود صفحه |
توکن نصب ویجت (data-widget-token) را از پنل ونوک دریافت کنید. این توکن برای شناسایی محل نصب است و نباید بهعنوان توکن ورود کاربر در نظر گرفته شود.
ورود خودکار مشتری
شناسایی خودکار کاربر لاگینشده بدون نیاز به OTP
اگر کاربر در سایت شما لاگین کرده است، میتوانید اطلاعات او را هنگام لود ویجت ارسال کنید تا کاربر بدون نیاز به وارد کردن مجدد شماره موبایل، مستقیماً از ویجت استفاده کند. به این قابلیت Auto Login میگوییم.
<script
src="https://widget.venok.chat/widget/latest/widget.js"
data-widget-token="wgt_************"
data-api-base-url="https://api.venok.chat"
data-customer-phone="0912*******"
data-customer-name="display"
data-external-user-id="any"
async
></script>با وجود این سه فیلد، ویجت مشتری فعلی را از همان ابتدا میشناسد:
- کاربر برای شروع گفتگو دوباره شماره موبایل وارد نمیکند
- گفتگوی جدید مستقیماً برای مشتری لاگینشده ایجاد میشود
- تاریخچه گفتگوهای همان مشتری قابل بازیابی است
- تجربه ورود مجدد یا فرم شناسایی داخل ویجت حذف میشود
Auto Login به این معنا نیست که رمز عبور کاربر برای ونوک ارسال میشود. فقط Customer Context (شماره موبایل، نام و شناسه) ارسال میشود. اعتماد اصلی باید از session معتبر سایت شما باشد.
فیلدهای مشتری
جزئیات فیلدهای customer-phone، customer-name و external-user-id
این سه فیلد نقش اصلی را در اتصال مشتری سایت شما به هویت او در ونوک دارند. در ادامه هر کدام بهتفصیل توضیح داده شده است.
data-customer-phone="09123456789"شماره موبایل مشتری فعلی. این شماره باید متعلق به کاربری باشد که در همان لحظه داخل سایت لاگین کرده است. پیشنهاد میشود شماره با فرمت ثابت 09XXXXXXXXX ارسال شود.
از ارسال شماره با فرمتهای متفاوت مانند +989XXXXXXXXX یا 00989XXXXXXXXX خودداری کنید، مگر اینکه فرمت مورد انتظار قبلاً با تیم ونوک هماهنگ شده باشد.
data-customer-name="علی رضایی"نام نمایشی مشتری است. این نام در پنل پشتیبانی و بخشهای مربوط به گفتگو نمایش داده میشود. اگر نام واقعی کاربر در دسترس نیست، میتوان یک نام نمایشی تولید کنید مانند «مشتری 09123456789».
data-external-user-id="customer-1024"شناسهی پایدار مشتری در سیستم سایت شما. این مقدار باید همان شناسهای باشد که سایت شما برای شناسایی دائمی کاربر استفاده میکند.
- مقدار باید برای هر مشتری یکتا باشد
- مقدار یک مشتری نباید در ورودهای مختلف تغییر کند
- از شماره ردیف موقت، session ID یا access token استفاده نکنید
- بهتر است این مقدار شناسه داخلی کاربر در دیتابیس سایت شما باشد
- یک externalUserId نباید به چند کاربر متفاوت اختصاص داده شود
نصب پویا (Runtime)
ساخت ویجت در زمان اجرا با اطلاعات کاربر فعلی
در سایتهای واقعی، بهتر است اسکریپت ویجت بهصورت ثابت همراه با اطلاعات hard-code شده در HTML قرار نگیرد. ابتدا باید اطلاعات کاربر فعلی از backend دریافت شود و سپس ویجت در Runtime ساخته شود.
ابتدا یک endpoint محافظتشده در backend خود بسازید که اطلاعات کاربر لاگینشده را برمیگرداند:
{
"phoneNumber": "09123456789",
"name": "علی رضایی",
"externalUserId": "customer-1024"
}nullسپس در frontend، ابتدا اطلاعات کاربر را دریافت کرده و سپس ویجت را mount کنید:
const WIDGET_CONFIG = {
widgetScriptUrl: WIDGET_SCRIPT_URL,
widgetToken: "wgt_************",
apiBaseUrl: API_BASE_URL,
};
async function getCurrentCustomer() {
const response = await fetch("/api/widget-context", {
method: "GET",
credentials: "include",
headers: { Accept: "application/json" },
});
if (response.status === 401) return null;
if (!response.ok) throw new Error("دریافت اطلاعات مشتری ناموفق بود.");
return response.json();
}
function mountVenokWidget(customer) {
const script = document.createElement("script");
script.src = WIDGET_CONFIG.widgetScriptUrl;
script.async = true;
script.dataset.venokWidgetLoader = "runtime";
script.dataset.widgetToken = WIDGET_CONFIG.widgetToken;
script.dataset.apiBaseUrl = WIDGET_CONFIG.apiBaseUrl;
if (customer) {
script.dataset.customerPhone = customer.phoneNumber;
script.dataset.customerName = customer.name;
script.dataset.externalUserId = customer.externalUserId;
}
document.body.appendChild(script);
}
async function initializeVenokWidget() {
try {
const customer = await getCurrentCustomer();
mountVenokWidget(customer);
} catch (error) {
console.error(error);
mountVenokWidget(null); // حالت مهمان
}
}
initializeVenokWidget();تغییر کاربر و Logout
مدیریت ویجت در SPAهای دارای Login و Logout
اگر سایت شما Single Page Application است یا کاربر بدون Refresh کامل صفحه Login و Logout میکند، باید instance قبلی ویجت حذف و مجدداً ساخته شود.
function destroyVenokWidget() {
if (window.VenokWidget && typeof window.VenokWidget.destroy === "function") {
window.VenokWidget.destroy();
}
document
.querySelectorAll("script[data-venok-widget-loader='runtime']")
.forEach((node) => node.remove());
}
function mountVenokWidget(customer) {
destroyVenokWidget();
const script = document.createElement("script");
script.src = WIDGET_SCRIPT_URL;
script.async = true;
script.dataset.venokWidgetLoader = "runtime";
script.dataset.widgetToken = "wgt_************";
script.dataset.apiBaseUrl = API_BASE_URL;
if (customer) {
script.dataset.customerPhone = customer.phoneNumber;
script.dataset.customerName = customer.name;
script.dataset.externalUserId = customer.externalUserId;
}
document.body.appendChild(script);
}
// بعد از Login
mountVenokWidget({
phoneNumber: "09123456789",
name: "علی رضایی",
externalUserId: "customer-1024",
});
// بعد از Logout
mountVenokWidget(null);برای قابلشناسایی بودن script در زمان حذف، هنگام ساخت آن attribute زیر را اضافه کنید: data-venok-widget-loader="runtime"