مستندات نصب

نصب ویجت روی سایتت

راهنمای کامل نصب ویجت ونوک — از نصب ساده تا ورود خودکار مشتری و مدیریت Login/Logout.

شروع سریع

نصب ویجت در کمتر از یک دقیقه

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

نصب پایه
html
<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 می‌گوییم.

نصب با Auto Login
html
<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
html
data-customer-phone="09123456789"

شماره موبایل مشتری فعلی. این شماره باید متعلق به کاربری باشد که در همان لحظه داخل سایت لاگین کرده است. پیشنهاد می‌شود شماره با فرمت ثابت 09XXXXXXXXX ارسال شود.

⚠️

از ارسال شماره با فرمت‌های متفاوت مانند +989XXXXXXXXX یا 00989XXXXXXXXX خودداری کنید، مگر اینکه فرمت مورد انتظار قبلاً با تیم ونوک هماهنگ شده باشد.

data-customer-name
html
data-customer-name="علی رضایی"

نام نمایشی مشتری است. این نام در پنل پشتیبانی و بخش‌های مربوط به گفتگو نمایش داده می‌شود. اگر نام واقعی کاربر در دسترس نیست، می‌توان یک نام نمایشی تولید کنید مانند «مشتری 09123456789».

data-external-user-id
html
data-external-user-id="customer-1024"

شناسه‌ی پایدار مشتری در سیستم سایت شما. این مقدار باید همان شناسه‌ای باشد که سایت شما برای شناسایی دائمی کاربر استفاده می‌کند.

  • مقدار باید برای هر مشتری یکتا باشد
  • مقدار یک مشتری نباید در ورودهای مختلف تغییر کند
  • از شماره ردیف موقت، session ID یا access token استفاده نکنید
  • بهتر است این مقدار شناسه داخلی کاربر در دیتابیس سایت شما باشد
  • یک externalUserId نباید به چند کاربر متفاوت اختصاص داده شود

نصب پویا (Runtime)

ساخت ویجت در زمان اجرا با اطلاعات کاربر فعلی

در سایت‌های واقعی، بهتر است اسکریپت ویجت به‌صورت ثابت همراه با اطلاعات hard-code شده در HTML قرار نگیرد. ابتدا باید اطلاعات کاربر فعلی از backend دریافت شود و سپس ویجت در Runtime ساخته شود.

ابتدا یک endpoint محافظت‌شده در backend خود بسازید که اطلاعات کاربر لاگین‌شده را برمی‌گرداند:

پاسخ backend برای کاربر لاگین‌شده
json
{
  "phoneNumber": "09123456789",
  "name": "علی رضایی",
  "externalUserId": "customer-1024"
}
پاسخ backend برای کاربر مهمان
json
null

سپس در frontend، ابتدا اطلاعات کاربر را دریافت کرده و سپس ویجت را mount کنید:

نصب پویا با JavaScript
javascript
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 قبلی ویجت حذف و مجدداً ساخته شود.

مدیریت کامل Login و Logout
javascript
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"