SDK گپیفای به شما این اجازه را می‌دهد تا اطلاعات تکمیلی از کاربر خود را به سمت گپیفای ارسال کنید.
در صورتی که شما اسکریپت گپیفای را بر روی سایت خود قرار داده باشید، SDK گپیفای، آبجکت window.$gapify را expose می‌کند. برای اینکه مطمئن شوید که SDK به صورت کامل لود شده است، مطمئن شوید که ایونت gapify:ready را به صورت زیر چک می‌کنید:
window.addEventListener("gapify:ready", function () {
// Use window.$gapify here
// ...
});
اگر می‌خواهید به پیام‌هایی که در ویجت ارسال می‌شوند گوش دهید، می‌توانید از ایونت زیر استفاده کنید:
window.addEventListener('gapify:on-message', function(e) {
console.log('gapify:on-message', e.detail)
})
تنظیمات SDK
برای مخفی کردن آیکون ویجت بر روی وبسایت، می‌توانید از تنظیمات زیر استفاده کنید.
توجه: اگر از این تنظیمات استفاده کنید، باید تریگر کردن ویجت را نیز به کار ببرید.
window.gapifySettings = {
hideMessageBubble: false,
position: "left", // This can be left or right
locale: "en", // Language to be set
useBrowserLanguage: false, // Set widget language from user's browser
type: "standard", // [standard, expanded_bubble]
darkMode: "auto", // [light, auto]
};
استفاده‌ی خودکار از زبان مرورگر در ویجت لایوچت
برای اینکه ویجت لایوچت شما از زبان مرورگر کاربر استفاده کند، مقدار useBrowserLanguage را true کنید. اگر زبان مرورگر کاربر توسط گپیفای پشتیبانی نشود، مقدار محلی تنظیم شده در locale استفاده خواهد شد. در صورتی که این مقدار نیز موجود نباشد، ویجت به locale تنظیم‌شده در داشبورد ایجنت‌ها (اپراتورها) باز خواهد گشت.
طراحی‌های ویجت
گپیفای از دو طراحی برای آیکون ویجت پشتیبانی می‌کند:
-
۱- طراحی استاندارد دایره‌ای: آیکون به صورت دایره نشان داده می‌شود.
-
۲- آیکون بسط‌داده‌شده: آیکون به صورت یک مستطیل دارای متن نمایش داده می‌شود.
در صورتی که از آیکون بسط‌داده‌شده استفاده می‌کنید، می‌توانید متنی که بر روی آن نوشته شده است را از طربق تغییر پارامتر launcherTitle در gapifySettings به صورت زیر ویرایش کنید:
window.gapifySettings = {
type: "expanded_bubble",
launcherTitle: "Chat with us",
};
فعال کردن پنجره‌ی بازشو (pop out window)
برای اینکه پنجربه‌ی بازشو را فعال کنید (یعنی حالت بازشده‌ی ویجت را در یک صفحه‌ی جدای مرورگر باز کنید)، این تنظیمات را به gapifySettingsاضافه کنید. این آپشن به صورت پیش‌فرض غیرفعال است.
window.gapifySettings = {
// ...Other Config
showPopoutButton: true,
}
You can also popout the chat window programatically with the `popoutChatWindow()` method.
تابعی برای فعال کردن پنجره‌ی بازشو
شما می‌توانید ویجت را با استفاده از تابع popoutChatWindow() را به صورت زیر باز کنید.
window.$gapify.popoutChatWindow();
تغییر وضعیت قابل مشاهده بودن ویجت
اگر می‌خواهید آیکون ویجت را مخفی یا قابل مشاهده کنید، می‌توانید با استفاده از toggleBubbleVisibility('show/hide') این کار را انجام دهید. مثال:
window.$gapify.toggleBubbleVisibility("show"); // to display the bubble
window.$gapify.toggleBubbleVisibility("hide"); // to hide the bubble
باز و بسته کردن ویجت
در صورتی که می‌خواهید ویجت را باز و بسته کنید، از توابع زیر استفاده کنید:
window.$gapify.toggle();
// Toggle widget by passing state
window.$gapify.toggle("open"); // To open widget
window.$gapify.toggle("close"); // To close widget
تنظیم و ست کردن مشخصات کاربر در ویجت
شما می‌توانید نام، ایمیل، آدرس آواتار و شماره تلفن کاربری که در ویجت به شما پیام می‌دهد را به صورت خودکار ست کنید.
window.$gapify.setUser("<unique-identifier-key-of-the-user>", {
email: "<email-address-of-the-user@your-domain.com>",
name: "<name-of-the-user>",
avatar_url: "<avatar-url-of-the-user>",
phone_number: "<phone-number-of-the-user>",
});
تابع setUser یک شناساگر (identifier) دریافت می‌کند که می‌تواند معادل id کاربر در پایگاه‌داده‌ی شما بوده یا هر پارامتر یکتای دیگری باشد که نشان‌دهنده‌ی یک کاربر یکتا است.
اطمینان حاصل کنید که با لاگ‌اوت کردن کاربرتان، سشن را reset می‌کنید.
احراز هویت با استفاده از HMAC
برای پیشگیری از جعل هویت و خصوصی نگه داشتن مکالماتتان با مشتری‌های خود، ما توصیه می‌کنید تا یک سیستم احراز هویت راه‌اندازی کنید. این سیستم از طریق تولید کردن یک HMAC (Hash Based Message Authentication Code) بر مبنای مشخصه‌ی identifier و با استفاده از الگوریتم SHA256 کار می‌کند. در کنار identifier شما می‌توانید identifier_hash را نیز پاس دهید تا مطمئن شوید که کاربر، کاربر درستی است.
window.$gapify.setUser(`<unique-identifier-key-of-the-user>`, {
name: "", // Name of the user
avatar_url: "", // Avatar URL
email: "", // Email of the user
identifier_hash: "", // Identifier Hash generated based on the webwidget hmac_token
phone_number: "", // Phone Number of the user
description: "", // description about the user
country_code: "", // Two letter country code
city: "", // City of the user
company_name: "", // company name
social_profiles: {
twitter: "", // Twitter user name
linkedin: "", // LinkedIn user name
facebook: "", // Facebook user name
github: "", // Github user name
},
});
تنظیم کردن و ارسال ویژگی‌های سفارشی (Custom Attributes)
برای ست کردن اطلاعات اضافی در مورد مشتری خودتان، می‌توانید از ویژگی‌های سفارشی استفاده کنید. شما باید از بخش تنظیمات در پنل ایجنت‌ها، ویژگی‌های سفارشی را برای گفتگو یا مخاطب تعریف کنید و سپس با استفاده از SDK آن‌ها را نیز به صورت خودکار تنظیم کنید.
برای اینکار کافی است به صورت زیر از setCustomAttributes استفاده کنید.
window.$gapify.setCustomAttributes({
accountId: 1,
pricingPlan: "paid",
// Here the key which is already defined in custom attribute
// Value should be based on type (Currently support Number, Date, String and Number)
});
شما می‌توانید این اطلاعات ست‌شده را در پنل ایجنت‌ها و در پنل کناری مکالمه (سمت چپ در زبان فارسی) مشاهده کنید.
برای پاک کردن یک ویژگی سفارشی از deleteCustomAttribute به شکل زیر استفاده کنید.
window.$gapify.deleteCustomAttribute("attribute-key");
تنظیم زبان به صورت دستی
برای تنظیم زبان به صورت دستی از تابع setLocale استفاده کنید.
window.$gapify.setLocale("en");
برچسب‌گذاری بر روی مکالمات
در صورتی که کاربر هیچ مکالمه‌ای را پیش از این شروع نکرده باشد، می‌توانید با استفاده از توابع زیر، برچسب‌گذاری را انجام دهید:
window.$gapify.setLabel("support-ticket");
window.$gapify.removeLabel("support-ticket");
رفرش کردن سشن (از این تابع در زمان لاگ‌اوت کردن کاربرهایتان استفاده کنید)
window.$gapify.reset();
خطاهای ویجت
برای اینکه از خطاهای موجود در ویجت آگاه شوید، مطمئن شوید که به ایونت gapify:event گوش می‌دهید.
window.addEventListener("gapify:error", function () {
// ...
});