کنترل ویجت آیوا با جاوااسکریپت: راهنمای توسعه‌دهندگان

برای بیشتر سایت‌ها گذاشتن کد نصب ویجت آیوا کافی است: دکمه چت در گوشه صفحه ظاهر می‌شود و کاربران گفتگو می‌کنند. اما اگر برنامه‌نویس سایت هستید، احتمالاً کارهای بیشتری می‌خواهید؛ مثلاً باز کردن گفتگو با دکمه خودتان، تغییر رنگ ویجت در یک صفحه کمپین، فرستادن نام و موبایل کاربری که وارد سایت شده، یا اینکه کاربر روی گوشی و لپ‌تاپ یک تاریخچه گفتگوی واحد داشته باشد.

همه این کارها با شیء window.AivaChatbotWidget انجام می‌شود. در این راهنما نصب، همه متدها با نمونه‌کد، یک سناریوی کامل ورود و خروج کاربر و جابه‌جایی ویجت با CSS را مرور می‌کنیم. مرجع کامل در صفحه مستندات ویجت است و اگر فقط می‌خواهید ویجت را نصب کنید، راهنمای نصب چت‌بات روی سایت کافی است.

نصب و آماده شدن ویجت

کد نصب را در مرحله انتشار دستیار، از گزینه «HTML/JS» برمی‌دارید. گزینه «API / ویجت» با توضیح «برای توسعه‌دهندگان» هم شناسه دستیار (UUID) را نشان می‌دهد و دکمه‌های «مستندات api» و «مستندات ویجت» را دارد. کد نصب چنین شکلی دارد و بهتر است پیش از بسته شدن تگ body قرار بگیرد:

<script src="https://aivarobot.com/api/public/widget/chatbot-widget.js?apiEndpoint=https://aivarobot.com/api/public&botUUID=YOUR-BOT-UUID"></script>

به‌جای YOUR-BOT-UUID شناسه دستیار خودتان را بگذارید. اگر سایتتان وردپرسی است و افزونه آیوا را نصب کرده‌اید (آیوا هوشمند و بالاتر)، همین اسکریپت را افزونه به پاورقی صفحه‌ها اضافه می‌کند و لازم نیست آن را دستی بگذارید؛ همه متدهای این راهنما آنجا هم کار می‌کنند. جزئیات افزونه در راهنمای افزونه وردپرس آیوا آمده است.

بعد از بارگذاری اسکریپت، این متدها روی window.AivaChatbotWidget در دسترس‌اند:

متد	کار
open()	پنجره گفتگو را باز می‌کند
close()	پنجره گفتگو را می‌بندد
toggle()	پنجره را بسته به وضعیت فعلی باز یا بسته می‌کند
updateConfig({...})	ظاهر و تنظیمات نمایشی را بدون بارگذاری دوباره صفحه تغییر می‌دهد
destroy()	ویجت را کامل از صفحه حذف می‌کند
setUser({...}, callback)	نام، ایمیل و موبایل کاربر واردشده را می‌فرستد
getUser()	اطلاعات کاربر ذخیره‌شده در ویجت را برمی‌گرداند
getUserId()	شناسه فعلی کاربر را برمی‌گرداند
setUserId(id, callback)	شناسه ثابتی برای یکی کردن تاریخچه گفتگو تعیین می‌کند
unsetUserId(callback)	شناسه را هنگام خروج کاربر پاک می‌کند

به زمان‌بندی دقت کنید. سه متد هویتی، یعنی setUser، setUserId و unsetUserId، را می‌توانید بلافاصله بعد از اجرای اسکریپت ویجت صدا بزنید، حتی اگر ویجت هنوز کامل آماده نشده باشد؛ این فراخوانی‌ها در صف می‌مانند و وقتی ویجت آماده شد، به همان ترتیب اجرا می‌شوند. فقط کدتان را بعد از تگ اسکریپت ویجت بگذارید. اما open، close، toggle و updateConfig فقط بعد از آماده شدن ویجت وجود دارند؛ پس پیش از صدا زدن، وجودشان را بررسی کنید. پیش از آماده شدن ویجت، getUserId() هم مقدار null برمی‌گرداند.

متدهایی که callback می‌گیرند، نتیجه را در قالب شیئی با سه فیلد success، userId و error برمی‌گردانند.

باز و بسته کردن ویجت با دکمه‌های خودتان

فرض کنید در صفحه محصول دکمه‌ای با متن «سؤال دارید؟» می‌خواهید که گفتگو را باز کند:

<button type="button" id="ask-aiva">سؤال دارید؟ از دستیار بپرسید</button>
<script>
  document.getElementById("ask-aiva").addEventListener("click", function () {
    var widget = window.AivaChatbotWidget;
    if (widget && typeof widget.open === "function") {
      widget.open();
    }
  });
</script>

اگر پنجره از قبل باز باشد، open() کاری نمی‌کند و صدا زدن چندباره‌اش مشکلی ندارد. close() پنجره را می‌بندد و دکمه گرد چت سر جایش می‌ماند. toggle() برای دکمه‌ای مناسب است که با هر کلیک وضعیت را عوض کند.

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

تغییر ظاهر در لحظه با updateConfig و حذف با destroy

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

window.AivaChatbotWidget.updateConfig({
  primaryColor: "#1e40af",
  accentColor: "#60a5fa",
  botName: "پشتیبانی فروش",
  widgetPosition: "bottom_left"
});

مقدار widgetPosition یکی از bottom_right یا bottom_left است. این تغییرها فقط در همان صفحه‌ای اعمال می‌شوند که کد در آن اجرا شده و تنظیمات ذخیره‌شده در پنل را عوض نمی‌کنند. با رفتن به صفحه دیگر، ویجت دوباره با تنظیمات پنل بارگذاری می‌شود. پس اگر مثلاً رنگ متفاوتی برای صفحه یک کمپین می‌خواهید، کد را فقط در همان صفحه بگذارید. برای تغییر دائمی ظاهر، از پنل استفاده کنید؛ راهنمای شخصی‌سازی ظاهر ویجت چت همه گزینه‌ها را توضیح داده است.

destroy() ویجت را کامل از صفحه برمی‌دارد و همه شنونده‌های رویدادش را هم آزاد می‌کند. تفاوتش با close() این است که بعد از آن، دکمه چت هم دیگر دیده نمی‌شود. این متد برای صفحه‌هایی به کار می‌آید که نمی‌خواهید گفتگو در آن‌ها در دسترس باشد، مثل مرحله پرداخت در یک اپلیکیشن تک‌صفحه‌ای. اگر بعد از آن دوباره ویجت را لازم داشتید، ساده‌ترین راه بارگذاری دوباره صفحه است.

معرفی کاربر واردشده با setUser و getUser

ویجت به‌طور پیش‌فرض برای هر مرورگر یک شناسه ناشناس می‌سازد و کاربر را با همان می‌شناسد. اگر کاربر در سایت شما حساب دارد و وارد شده است، می‌توانید اطلاعاتش را به آیوا بدهید تا در بخش «کاربران فعال» داشبورد و خروجی اکسل آن دیده شود:

window.AivaChatbotWidget.setUser(
  {
    name: "کاربر نمونه",
    email: "user@example.com",
    phone: "09120000000"
  },
  function (result) {
    if (!result.success) {
      console.warn("setUser failed:", result.error);
    }
  }
);

رفتار setUser به‌روزرسانی جزئی است؛ فقط فیلدهایی که می‌فرستید تغییر می‌کنند و بقیه دست نمی‌خورند. اگر در تنظیمات دستیار بخش «اطلاعات ضروری» را فعال کرده‌اید و همه فیلدهای الزامی را با setUser بفرستید، کاربر ثبت‌نام‌شده حساب می‌شود و فرم پیش از گفتگو به او نشان داده نمی‌شود. اگر یکی از فیلدهای الزامی را نفرستید، callback با success برابر false و متن خطا برمی‌گردد.

getUser() اطلاعاتی را که ویجت برای کاربر فعلی نگه داشته برمی‌گرداند؛ شیئی مثل { name, email, phone }. فقط اطلاعاتی را بفرستید که واقعاً برای پیگیری لازم دارید و با سیاست حریم خصوصی سایتتان هم‌خوان است. نکته‌های بیشتر در این زمینه را در مقاله امنیت و حریم خصوصی در چت‌بات نوشته‌ایم.

یکی کردن تاریخچه گفتگو با setUserId و unsetUserId

کاربری را در نظر بگیرید که صبح با گوشی از دستیار سؤالی می‌پرسد و عصر با لپ‌تاپ برمی‌گردد. به‌طور پیش‌فرض این دو مرورگر دو کاربر ناشناس جدا هستند و تاریخچه‌شان یکی نیست. با setUserId یک شناسه ثابت به کاربر واردشده می‌دهید تا ویجت در هر دستگاهی همان تاریخچه را بارگذاری کند.

قواعد شناسه این‌هاست:

• فقط حروف انگلیسی، عدد، خط تیره و زیرخط
• حداکثر ۱۰۰ کاراکتر
• اگر ثبت شناسه ناموفق باشد، شناسه قبلی بدون تغییر می‌ماند و خطا در callback برمی‌گردد

تاریخچه گفتگو با همین شناسه بازیابی می‌شود؛ پس شناسه‌ای بسازید که حدس زدنش ممکن نباشد. شماره موبایل، ایمیل یا شماره ردیف کاربر در پایگاه داده گزینه مناسبی نیست. دو راه امن دارید: یک رشته تصادفی طولانی، مثلاً UUID، بسازید و کنار رکورد کاربر نگه دارید؛ یا در نخستین ورود، مقدار getUserId() را بخوانید و در پایگاه داده خودتان ذخیره کنید.

هنگام خروج کاربر، unsetUserId را صدا بزنید. ویجت شناسه و اطلاعات کاربر را از این مرورگر پاک می‌کند و او را دوباره یک کاربر ناشناس با شناسه تازه در نظر می‌گیرد. پیام‌های قبلی دیگر در ویجت آن مرورگر نمایش داده نمی‌شوند، اما در داشبورد شما باقی می‌مانند.

نمونه کامل ورود و خروج این‌طور است:

// پس از ورود موفق کاربر در سایت شما
function onUserLogin(user) {
  // user.aivaId: رشته تصادفی و ثابتی که برای این کاربر در پایگاه داده خودتان نگه داشته‌اید
  window.AivaChatbotWidget.setUserId(user.aivaId, function (result) {
    if (!result.success) {
      console.warn("setUserId failed:", result.error);
    }
  });

  // بعد از تعیین شناسه، اطلاعات کاربر را بفرستید
  window.AivaChatbotWidget.setUser({
    name: user.fullName,
    phone: user.mobile
  });
}

// هنگام خروج کاربر
function onUserLogout() {
  window.AivaChatbotWidget.unsetUserId(function (result) {
    console.log("new anonymous id:", result.userId);
  });
}

ترتیب این دو فراخوانی مهم است. setUser اطلاعات را برای شناسه‌ای ثبت می‌کند که در آن لحظه فعال است؛ اگر آن را پیش از setUserId صدا بزنید، اطلاعات به شناسه ناشناس قبلی می‌چسبد. چون فراخوانی‌های هویتی در صف و به ترتیب اجرا می‌شوند، همین ترتیب در کد کافی است، حتی اگر ویجت هنوز کامل بارگذاری نشده باشد.

جابه‌جایی ویجت با CSS

چپ یا راست بودن ویجت را با widgetPosition یا از پنل تعیین می‌کنید. برای بالاتر یا پایین‌تر بردنش، که فاصله پیش‌فرضش از پایین صفحه ۲۰ پیکسل است، از CSS استفاده کنید. عدد بزرگ‌تر یعنی ویجت بالاتر:

<style>
  #aiva-chatbot-root .chatbot-container {
    bottom: 80px !important;
  }
</style>

طبق مستندات، این استایل را بعد از اسکریپت ویجت در صفحه بگذارید. همه استایل‌های داخلی ویجت زیر #aiva-chatbot-root محدود شده‌اند و نباید منو، دکمه‌ها یا فرم‌های سایت را تحت تأثیر قرار دهند. شما هم برای هر سفارشی‌سازی ویجت، سلکتورهایتان را با همین پیشوند بنویسید.

روی صفحه‌های باریک، پنجره گفتگو هنگام باز شدن تمام‌صفحه می‌شود و فاصله‌ای که تعیین می‌کنید فقط روی جای دکمه چت اثر دارد. اگر در موبایل نوار چسبانی پایین صفحه دارید و فاصله متفاوتی لازم است، از media query استفاده کنید:

@media (max-width: 480px) {
  #aiva-chatbot-root .chatbot-container {
    bottom: 72px !important;
  }
}

API عمومی برای سناریوهای خاص

اگر رابط گفتگوی کاملاً اختصاصی می‌سازید و نمی‌خواهید از ویجت استفاده کنید، آیوا یک API عمومی REST هم دارد که با شناسه دستیار کار می‌کند. این API گفتگوی جریانی، تاریخچه، ثبت اطلاعات کاربر، ثبت رأی پسندیدم و نپسندیدم و تنظیمات نمایشی ویجت را پوشش می‌دهد. مستندات آن با دکمه «مستندات api» در مرحله انتشار باز می‌شود و نشانی‌اش /api/public/redoc است. برای گفتگو محدودیت نرخ هم هست: ده پیام در دقیقه برای هر بازدیدکننده در هر دستیار و حداکثر ۴ هزار کاراکتر برای هر پیام. برای سایت‌های معمولی، همان ویجت با متدهای این راهنما ساده‌تر و کافی است.

سؤالات متداول

چرا window.AivaChatbotWidget.open تعریف نشده است؟

چون ویجت هنوز کامل بارگذاری نشده است. open و متدهای نمایشی دیگر فقط بعد از آماده شدن ویجت ساخته می‌شوند. فراخوانی را به رویداد کاربر، مثل کلیک، وصل کنید و پیش از صدا زدن وجود متد را بررسی کنید؛ مثل نمونه دکمه بالا. متدهای هویتی این مشکل را ندارند و در صف می‌مانند.

آیا updateConfig تنظیمات پنل را هم تغییر می‌دهد؟

نه. تغییرها فقط در همان صفحه و همان بار بارگذاری اعمال می‌شوند. تنظیمات دائمی را در پنل آیوا ذخیره کنید.

تفاوت close و destroy چیست؟

close فقط پنجره گفتگو را می‌بندد و دکمه چت می‌ماند. destroy کل ویجت را از صفحه حذف می‌کند.

جمع‌بندی

با window.AivaChatbotWidget ویجت را از کد سایت کنترل می‌کنید: باز و بسته کردن با open، close و toggle، تغییر ظاهر در یک صفحه با updateConfig، معرفی کاربر با setUser و یکی کردن تاریخچه با setUserId و unsetUserId. متدهای هویتی را با خیال راحت زود صدا بزنید، برای بقیه منتظر آماده شدن ویجت بمانید و شناسه کاربر را حدس‌ناپذیر بسازید. مرور همه قدم‌های ساخت دستیار در آموزش ساخت چت‌بات با آیوا آمده است.

اگر هنوز دستیاری نساخته‌اید، ساخت دستیار را رایگان شروع کنید تا شناسه و کد نصب خودتان را بگیرید.