حالات الاستخدام
حالات الاستخدام هي أمثلة حقيقية لواجهة برمجة التطبيقات (API). يمكن أن تكون مزيجاً من لغات، وواجهات برمجة التطبيقات، وإعدادات مختلفة. يتم بناؤها لإتمام مهام محددة.
تسجيل مستخدم مخصص وتسجيل الدخول إليه
تشرح حالة الاستخدام هذه كيفية تسجيل مستخدم مخصص يدوياً وتسجيل الدخول إليه قبل بدء الدردشة. يمكنك تسجيل مستخدم جديد بأربع طرق: متغير JS، واجهة برمجة التطبيقات PHP، واجهة برمجة التطبيقات JS، وPHP + JS + WEB. متغير JS، واجهة برمجة التطبيقات PHP، وPHP + JS + WEB API هي الطرق الموصى بها.
متغير JS
أدخل فقط المتغير SB_DEFAULT_USER. تفاصيل أكثر هنا.
واجهة برمجة التطبيقات PHP
1 تسجيل المستخدم وتسجيل الدخول إليه
تحقق مما إذا كان هناك مستخدم نشط مسجل الدخول بالفعل من خلال التحقق من البريد الإلكتروني، إذا كان موجوداً، قم بتسجيل الدخول إليه، خلاف ذلك سجل مستخدم جديد.
require_once($_SERVER["DOCUMENT_ROOT"] . "/alfchatbot/include/functions.php");
$active_user = sb_get_active_user();
if (!$active_user || $active_user["email"] != "don.john@email.com") {
$response = sb_add_user_and_login([ "profile_image" => "https://alfchatbot.com/media/docs/user.png", "first_name" => "Don", "last_name" => "John", "email" => "don.john@email.com", "password" => "12345678"], ["phone" => ["123456789", "Phone"], "city" => ["London", "City"]]);
if ($response == "duplicate-email") {
$response = sb_login("don.john@email.com", "12345678");
}
}
PHP + JS + WEB API
1 تفعيل التهيئة اليدوية
انتقل إلى الإعدادات > الدردشة، حدد خيار التهيئة اليدوية، واحفظ.
2 طباعة رمز JS لتسجيل المستخدم وتسجيل الدخول إليه
قم بتوليد رمز JS لإدراجه في جميع الصفحات التي تحتوي على الدردشة. يتحقق الرمز مما إذا كان هناك مستخدم نشط مسجل الدخول، إذا كان موجوداً، قم بتسجيل الدخول إليه، خلاف ذلك سجل مستخدم جديد. يوفر الرمز أيضاً التفاصيل لتسجيل الدخول إلى مستخدم موجود.
$existing_user_email = 'don.john@email.com';
$sb_user = alfchatbot_curl(['function' => 'get-user-by', 'by' => 'email', 'value' => $existing_user_email]);
$code_login_existing_user = '';
if (isset($sb_user['success']) && $sb_user['success']) {
$sb_user = $sb_user['response'];
$code_login_existing_user = 'SBF.login("", "", "' . $sb_user['id'] . '", "' . $sb_user['token'] . '", () => { SBChat.initChat(); });';
}
$code = 'jQuery(document).on("SBReady", function () {
SBF.getActiveUser(true, () => {
if (!SBF.activeUser() || (SBF.activeUser().email != "' . $existing_user_email . '")) {
SBF.ajax({
function: "add-user-and-login",
settings: { profile_image: "https://alfchatbot.com/media/docs/user.png", first_name: "Don", last_name: "John", email: "don.john@email.com" },
settings_extra: { phone: ["123456789", "Phone"], city: ["London", "City"] }
}, (response) => {
if (!SBF.errorValidation(response)) {
SBF.loginCookie(response[1]);
SBF.activeUser(new SBUser(response[0]));
SBChat.initChat();
} else if (response[1] == "duplicate-email") {
' . $code_login_existing_user . '
} else {
SBChat.initChat();
}
});
}
});
});';
echo $code;
واجهة برمجة التطبيقات جافا سكريبت
1 تفعيل التهيئة اليدوية
انتقل إلى الإعدادات > الدردشة، حدد خيار التهيئة اليدوية، واحفظ.
2 تسجيل المستخدم وتسجيل الدخول إليه
تحقق مما إذا كان هناك مستخدم نشط مسجل الدخول بالفعل، إذا كان موجوداً، قم بتسجيل الدخول إليه، خلاف ذلك سجل مستخدم جديد. تحذير! هذه الطريقة غير آمنة، تفاصيل كلمة المرور والمستخدم مرئية للجميع.
jQuery(document).on("SBReady", function () {
SBF.getActiveUser(true, () => {
if (!SBF.activeUser() || (SBF.activeUser().email != "don.john@email.com")) {
SBF.ajax({
function: "add-user-and-login",
settings: { profile_image: "https://alfchatbot.com/media/docs/user.png", first_name: "Don", last_name: "John", email: "don.john@email.com", password: "12345678" },
settings_extra: { phone: ["123456789", "Phone"], city: ["London", "City"] }
}, (response) => {
if (!SBF.errorValidation(response)) {
SBF.loginCookie(response[1]);
SBF.activeUser(new SBUser(response[0]));
SBChat.initChat();
} else if (response[1] == "duplicate-email") {
SBF.login("don.john@email.com", "12345678", "", "", () => { SBChat.initChat(); });
} else console.log(response);
});
} else {
SBChat.initChat();
}
});
});
عرض الدردشة فقط على صفحات محددة
تشرح حالة الاستخدام هذه كيفية عرض الدردشة فقط على صفحات محددة.
1 تفعيل التهيئة اليدوية
انتقل إلى الإعدادات > الدردشة، حدد خيار التهيئة اليدوية، واحفظ.
2 تهيئة الدردشة
قم بتهيئة الدردشة باستخدام الدالة SBChat.initChat() من واجهة برمجة التطبيقات جافا سكريبت . يمكنك استخدام المتغير JS window.location.href للحصول على عنوان URL وعرض الدردشة فقط إذا كان عنوان URL يطابق معاييرك.
$(document).on("SBReady", function () {
// مثال: عرض الدردشة فقط على صفحة الاتصال
if (window.location.href.indexOf("/contact") > 0) {
SBChat.initChat();
}
// مثال: عرض الدردشة فقط على الصفحة الرئيسية
if (window.location.href == "https://example.com") {
SBChat.initChat();
}
});
عرض الدردشة عند النقر
تشرح حالة الاستخدام هذه كيفية عرض الدردشة فقط بعد أن ينقر المستخدم على زر.
1 تفعيل التهيئة اليدوية وفتح الدردشة تلقائيًا
قم بتمكين الخيارات الإعدادات > الدردشة > التهيئة اليدوية، الإعدادات > الدردشة > الفتح تلقائيًا، واحفظ التغييرات.
2 عرض الدردشة
استخدم الدالة SBChat.initChat() لعرض الدردشة. يمكنك استخدامها كوصلة بالكود javascript:SBChat.initChat(). لفتح الدردشة على الأجهزة المحمولة، تحتاج أيضاً إلى استخدام الدالة SBChat.open(). مثال:
<a href="javascript:SBChat.initChat();SBChat.open()">انقر هنا</a>
عرض وإخفاء الدردشة عند النقر
تشرح حالة الاستخدام هذه كيفية عرض الدردشة فقط بعد أن ينقر المستخدم على زر، وإخفائها مرة أخرى عند إغلاقها.
1 تفعيل التهيئة اليدوية
انتقل إلى الإعدادات > الدردشة، حدد خيار التهيئة اليدوية، واحفظ.
2 إضافة كود أحداث النقر
الحدث الأول عند النقر يعرض الدردشة، والحدث الثاني يخفيها. استبدل button-id بـمعرف الزر أو العنصر HTML الخاص بك.
$("body").on("click", "#button-id", function () {
SBChat.initChat();
$(".sb-chat-btn").show();
setTimeout(function () {
SBChat.open();
}, 500);
});
$("body").on("click", ".sb-chat .sb-chat-btn", function () {
$(this).hide();
});
إنشاء محادثة جديدة وتعيين قسم لها
تشرح حالة الاستخدام هذه كيفية إنشاء محادثة جديدة، تعيين قسم لها، وفتحها في الدردشة. إذا كنت تريد أن يتم تعيين جميع المحادثات تلقائيًا إلى قسم ثابت، استخدم متغير جافا سكريبت SB_DEFAULT_DEPARTMENT. يمكنك الحصول على المعرفات من الإعدادات > المتفرقات > الأقسام.
1 إنشاء محادثة جديدة وفتحها
أنشئ محادثة جديدة باستخدام الدالة SBChat.newConversation() من واجهة برمجة التطبيقات جافا سكريبت ومرر معرف القسم 2 في معلمات الدالة. بعد إنشاء المحادثة، يتم فتحها باستخدام الدالة SBChat.openConversation() . في الكود أدناه، يتم إنشاء المحادثة فقط إذا لم يكن لدى المستخدم أي محادثات أخرى.
$(document).on("SBInit", function () {
if (SBF.activeUser() != false && SBF.activeUser().conversations.length == 0) {
SBChat.newConversation(2, -1, "", [], 2, null, function (conversation) {
SBChat.openConversation(conversation.id);
});
}
});
إنشاء محادثة جديدة وتعيينها لوكيل
تشرح حالة الاستخدام هذه كيفية إنشاء محادثة جديدة، تعيين وكيل موجود لها، والسماح فقط لذلك الوكيل برؤية المحادثة في منطقة الإدارة.
1 تفعيل التوجيه
انتقل إلى الإعدادات > المتفرقات، حدد خيار التوجيه، واحفظ.
2 إنشاء محادثة جديدة وفتحها
أنشئ محادثة جديدة باستخدام الدالة SBChat.newConversation() من واجهة برمجة التطبيقات جافا سكريبت ومرر معرف الوكيل 445 في معلمات الدالة. بعد إنشاء المحادثة، يتم فتحها باستخدام الدالة SBChat.openConversation() .
$(document).on("SBInit", function () {
if (SBF.activeUser() != false && SBF.activeUser().conversations.length == 0) {
SBChat.newConversation(2, -1, "", [], null, 445, function (conversation) {
SBChat.openConversation(conversation.id);
});
}
});
فرض محادثة محددة
تشرح حالة الاستخدام هذه كيفية تعيين محادثة محددة عندما تصبح شرطًا معينًا صحيحًا وتجبر المستخدم على استخدام تلك المحادثة فقط حتى يظل الشرط صحيحًا. يستخدم الكود أدناه عنوان المحادثة لفهم أي محادثة هي المناسبة للاستخدام، ويبحث عن المحادثة المحددة باستخدام عنوانها، إذا تم العثور عليها، يتم فتحها، وإلا يتم إنشاء محادثة جديدة بعنوان البحث. يمكن استخدام حالة الاستخدام هذه في سيناريوهات مختلفة، على سبيل المثال، إذا كنت تريد فرض استخدام المستخدم لمحادثة مختلفة لصفحات مختلفة.
1 أدخل هذا الكود JavaScript في موقعك الإلكتروني
(function ($) {
jQuery(document).on("SBInit", function () {
let conversation_title = "CONVERSATION-NAME";
let conversations = SBF.activeUser().conversations;
if (conversations) {
for (var i = 0; i < conversations.length; i++) {
if (conversations[i].get("title") == conversation_title) {
SBChat.openConversation(conversations[i].id);
return;
}
}
}
SBF.ajax({
function: "new-conversation",
title: conversation_title
}, (response) => {
SBChat.setConversation(new SBConversation([], response["details"]));
});
});
}(jQuery));
استبدل CONVERSATION-NAME بالمعرف الفريد للمحادثة التي تريد استخدامها.
إذا كنت تستخدم منطقة التذاكر، استبدل SBInit بـ SBTicketsInit.
فرض قسم محدد
تشرح حالة الاستخدام هذه كيفية تعيين قسم محدد لمحادثة عندما يصبح شرط معين صحيحًا وتجبر المستخدم على استخدام تلك المحادثة فقط حتى يظل الشرط صحيحًا. يبحث الكود أدناه عن محادثة بالقسم المطلوب، إذا تم العثور عليها، يتم فتحها، وإلا يتم إنشاء محادثة جديدة مخصصة لذلك القسم. تستخدم حالة الاستخدام هذه لتجبر المستخدم على استخدام محادثات وأقسام مختلفة لصفحات مختلفة.
1 أدخل هذا الكود JavaScript في موقعك الإلكتروني
(function ($) {
jQuery(document).on("SBInit", function () {
let active_department = "YOUR-DEPARTMENT-ID";
let conversations = SBF.activeUser().conversations;
SBChat.default_department = active_department;
if (conversations) {
for (var i = 0; i < conversations.length; i++) {
if (conversations[i].get("department") == active_department) {
setTimeout(() => { SBChat.openConversation(conversations[i].id) }, 300);
return;
}
}
}
SBChat.open(false);
SBF.ajax({
function: "new-conversation",
department: active_department
}, (response) => {
SBChat.setConversation(new SBConversation([], response["details"]));
});
});
}(jQuery));
استبدل YOUR-DEPARTMENT-ID بمعرف القسم الذي تريد استخدامه.
إذا كنت تستخدم منطقة التذاكر، استبدل SBInit بـ SBTicketsInit.
فرض وكيل محدد
تشرح حالة الاستخدام هذه كيفية تعيين وكيل محدد لمحادثة عندما يصبح شرط معين صحيحًا وتجبر المستخدم على استخدام تلك المحادثة فقط حتى يظل الشرط صحيحًا. يبحث الكود أدناه عن محادثة بالوكيل المطلوب، إذا تم العثور عليها، يتم فتحها، وإلا يتم إنشاء محادثة جديدة مخصصة لذلك الوكيل. تستخدم حالة الاستخدام هذه لتجبر المستخدم على استخدام محادثات ووكلاء مختلفين لصفحات مختلفة.
1 أدخل هذا الكود JavaScript في موقعك الإلكتروني
(function ($) {
if (typeof SB_DEFAULT_AGENT != 'undefined') {
jQuery(document).on("SBInit", function () {
if (!SBF.activeUser()) return;
let conversations = SBF.activeUser().conversations;
if (conversations) {
for (var i = 0; i < conversations.length; i++) {
if (conversations[i].get("agent_id") == SB_DEFAULT_AGENT) {
setTimeout(() => { SBChat.openConversation(conversations[i].id) }, 300);
return;
}
}
}
$('.sb-list').sbLoading(true);
SBChat.open(false);
SBF.ajax({
function: "new-conversation",
agent_id: SB_DEFAULT_AGENT
}, (response) => {
SBChat.clear();
$('.sb-list').sbLoading(false);
SBChat.setConversation(new SBConversation([], response["details"]));
});
});
}
}(jQuery));
في كل من صفحاتك، أدخل الكود <script>var SB_DEFAULT_AGENT = 123</script> وغيّر معرف الوكيل بالمعرف الذي تريده.
إذا كنت تستخدم منطقة التذاكر، استبدل SBInit بـ SBTicketsInit.
إرسال رسالة جديدة وفتح الدردشة
تشرح حالة الاستخدام هذه كيفية إرسال رسالة جديدة، وفتح الدردشة بعد إرسال الرسالة.
1 إرسال الرسالة وفتح الدردشة
تحقق مما إذا كانت الرسالة نفسها موجودة بالفعل في المحادثة باستخدام الطريقة searchMessages() من واجهة برمجة JavaScript . إذا لم تكن الرسالة في المحادثة، أرسل رسالة جديدة باستخدام دالة SBChat.sendMessage() . بعد إرسال الرسالة، افتح المحادثة باستخدام دالة SBChat.openConversation() ، تحقق مما إذا كانت الدردشة مفتوحة، وإذا لم تكن، افتحها باستخدام دالة SBChat.open() .
$(document).on("SBInit", function () {
let message = "هل تريد شراء المنتج في هذه الصفحة؟";
if (SBChat.conversation == false || SBChat.conversation.searchMessages(message).length == 0) {
SBChat.sendMessage(SBF.setting("bot-id"), message, [], function (response) {
SBChat.openConversation(response["conversation_id"]);
if (!SBChat.chat_open) {
SBChat.open();
}
});
}
});
عرض رسالة منبثقة عند تمرير الصفحة
تشرح حالة الاستخدام هذه كيفية عرض رسالة منبثقة عندما يقوم المستخدم بتمرير الصفحة إلى موضع معين، في هذا المثال عندما يصل التمرير إلى 500 بكسل.
1 تحقق من تمرير الصفحة وعرض الرسالة المنبثقة
تحقق من تمرير الصفحة عبر JavaScript وعرض الرسالة المنبثقة باستخدام دالة popup() من واجهة برمجة JavaScript .
$(document).on("SBInit", function () {
var showed = false;
$(window).scroll(function () {
var scroll = $(window).scrollTop();
if (scroll > 500 && !showed) {
SBChat.popup(false, { title: "وصلت إلى 500 بكسل!", message: "أدخل هنا رسالتك." });
showed = true;
}
});
});
عرض الدردشة ضمن منطقة إدارة WordPress
تشرح حالة الاستخدام هذه كيفية عرض الدردشة ضمن منطقة إدارة WordPress والتعرف تلقائيًا على المستخدم المسجل الدخول في WordPress.
1 أدخل الكود في ملف functions.php
قم بتعديل ملف functions.php الخاص بقالب WordPress الخاص بك (مثلاً /wp-content/themes/your-theme/functions.php) وأدخل الكود أدناه في أسفل الملف.
function sb_enqueue_admin_custom() {
if (!key_exists('page', $_GET) || $_GET['page'] != 'alfchatbot') {
wp_enqueue_script('sbinit', SB_URL . '/js/main.js', ['jquery'], SB_VERSION);
$current_user = wp_get_current_user();
if (!empty($current_user->ID)) wp_add_inline_script('sbinit', 'document.cookie = "sb-login=false;expires=Thu, 01 Jan 1970 00:00:01 GMT;path=/;SameSite=None;Secure;" + (location.protocol == "https:" ? "SameSite=None;Secure;" : ""); var SB_WP_ACTIVE_USER = ' . $current_user->ID . ';');
}
}
add_action('admin_enqueue_scripts', 'sb_enqueue_admin_custom');
إذا كان تم تعيين الإعدادات > متنوعات > نطاق الكوكيز، أضف أيضًا الكود domain=YOUR-VALUE إلى سلسلة الكوكيز أعلاه.