buildship chat widget
1.0.0
أداة دردشة AI مفتوحة المصدر والتي يمكن تضمينها بسهولة على موقع الويب الخاص بك أو التطبيق. تم تصميم أداة التوصيل والتشغيل هذه للعمل بسلاسة مع سير عمل Buildship الخاص بك ، مما يسمح له بالاتصال بقاعدة البيانات الخاصة بك ومستودع المعرفة وأي أدوات أخرى تستخدمها.
مع مساعد دردشة AI القوي ، يمكنك تحسين تجربة المستخدم لموقع الويب الخاص بك أو تطبيقك بشكل كبير.
أولاً ، قم بتحميل أداة الدردشة على صفحتك عن طريق إضافة مقتطف الرمز التالي. ثم قم بتوصيل عنصر واجهة المستخدم بسير سير عمل Buildship عن طريق استبدال عنوان URL لـ API بعنوان URL الخاص بك API الذي تم نشره وفقًا للتعليمات في الخطوة 2. أضف أي خيارات تخصيص حسب الحاجة.
< script src =" https://unpkg.com/@buildshipapp/chat-widget@^1 " defer > </ script >
< script >
window . addEventListener ( "load" , ( ) => {
window . buildShipChatWidget . config . widgetTitle = "Chatbot" ;
window . buildShipChatWidget . config . greetingMessage =
"Hello! How may I help you today?" ;
window . buildShipChatWidget . config . url =
"https://<project_id>.buildship.run/chat/...." ;
<!-- Other optional properties, learn more in the `Config Properties` section below -->
} ) ;
</ script >يمكنك أيضًا استيرادها كوحدة نمطية إذا كنت تعمل مع TypeScript أو ES6 (تم تضمين إعلانات النوع):
import "@buildshipapp/chat-widget" ;
window . buildShipChatWidget . config . widgetTitle = "Chatbot" ;
window . buildShipChatWidget . config . greetingMessage =
"Hello! How may I help you today?" ;
window . buildShipChatWidget . config . url =
"https://<project_id>.buildship.run/chat/...." ;
// ...ثانياً ، ضع زرًا مع جسم البيانات التالية في أي مكان على موقع الويب الخاص بك أو تطبيقه لفتح عنصر واجهة المستخدم:
< button data-buildship-chat-widget-button > Beep Boop </ button >تم تصميم عنصر واجهة المستخدم للعمل مع Buildship-منشئ خلفي من الرمز المنخفض لإنشاء واجهات برمجة التطبيقات والوظائف المجدولة بصريًا وسريعًا مع واجهة السحب والإفلات.
window.buildShipChatWidget.config.url . انظر الخطوة 3 لمزيد من التفاصيل.ستقوم القطعة بتقديم طلب نشر إلى عنوان URL هذا. سيكون هيئة الطلب كائنًا يحتوي على رسالة المستخدم والبيانات الأخرى لسير العمل للاستفادة من ذلك ، مثل ذلك:
{
"message" : " The user's message " ,
"threadId" : " A unique identifier for the conversation (learn more below) " ,
"timestamp" : " The timestamp of when the POST request was initiated "
...Other miscellaneous user data (learn more in the 'Config Properties' section below)
}يمكنك معرفة المزيد عن كل من الخصائص في القسم التالي.
ستتوقع القطعة استجابة من نقطة النهاية في شكل كائن JSON الذي يحتوي على استجابة سير العمل ( message ) ومعرف مؤشر الترابط ( threadId ) ، مثل ذلك:
{
"message" : " The bot's response " ,
"threadId" : " The unique identifier for the conversation (learn more below) "
}في حالة وجود استجابة متدفق ، لن تتوقع عنصر واجهة المستخدم كائن JSON كما هو موضح أعلاه ، ولكنه بدلاً من ذلك يتوقع دفقًا من القطع التي تضيف في النهاية إلى رسالة الاستجابة. ستجمع القطعة هذه القطع عند استلامها وعرضها وتحديث الرسالة في الوقت الفعلي ، وتنتهي أخيرًا بالاستجابة الكاملة.
threadId من خلال الاستجابة اختياريا ، هناك طريقتان لتعيين threadId من خلال الاستجابة.
عبر رأس استجابة
إذا كانت الاستجابة تتضمن رأسًا يحتوي على معرف x-thread-id مفتاح مع معرف مؤشر الترابط كقيمة ، فسيقوم عنصر واجهة المستخدم تلقائيًا بتقاطه وتعيينه على أنه threadId للمحادثة (إذا لم يتم تعيينه بالفعل).
ملاحظة: تأكد من تعيين رأس Access-Control-Expose-Headers رد الفعل في ردك لفضح رأس معرف x-thread-id على عنصر واجهة المستخدم العميل.
عبر الدفق نفسه
إذا كانت نقطة النهاية تستجيب message والمعدل threadId في التنسيق التالي: message + x1f + threadId ، حيث x1f هو حرف فاصل الوحدة ، فسيقوم عنصر واجهة المستخدم باستخراج معرف مؤشر الترابط من الدفق وتعيينه على أنه threadId للمحادثة (إذا لم يتم تعيينه بالفعل). على سبيل المثال:
// Simulating what a streamed response might look like where
// message: "Hello world!"
// threadId: "tId_123"
readable . push ( "Hello " ) ;
readable . push ( "world!" ) ;
readable . push ( "x1f" + "tId_123" ) ; // No spaces between the end of the message, the unit separator character, and the beginning of the threadId يمكن تخصيص القطعة عن طريق تحرير الخصائص الموجودة في الكائن window.buildShipChatWidget.config .
| ملكية | يكتب | وصف |
|---|---|---|
| window.buildshipchatwidget.config.url | مطلوب | عنوان URL لنقطة النهاية التي ستقدم بها القطعة طلبًا نشرًا عندما يرسل المستخدم رسالة. يجب أن تتوقع نقطة النهاية كائن JSON في هيئة الطلب ويجب أن يستجيب بكائن JSON يحتوي على استجابة الروبوت ومعرف الخيط. |
| window.buildshipchatwidget.config.throadid | خياري | معرف فريد للمحادثة. يمكن استخدام هذا للحفاظ على سياق المحادثة عبر رسائل/جلسات متعددة. إذا لم يتم تعيينه ، فسيقوم عنصر واجهة المستخدم بإرسال رسالة المستخدم الأولى بدون معرف مؤشر ترابط. إذا قمت بعد ذلك بتصميم سير العمل الخاص بك لإرجاع معرف مؤشر ترابط كجزء من استجابةه (كما هو موضح في الطلب والاستجابة) ، فسيستخدم عنصر واجهة المستخدم تلقائيًا ذلك لبقية المحادثة حتى يظل البرنامج النصي محملاً - على سبيل المثال ، سيتم تجاهل معرف مؤشر الترابط إذا تم تحديث الصفحة. ملاحظة: لن يتم استخدام معرف مؤشر الترابط الذي تم إرجاعه في الاستجابة إذا تم تعيين خاصية threadId بالفعل. |
| window.buildshipchatwidget.config.user | خياري | كائن يحتوي على بيانات المستخدم. يمكن استخدام هذا لإرسال اسم المستخدم أو البريد الإلكتروني أو أي بيانات أخرى قد يحتاجها سير العمل. مثال: window.buildShipChatWidget.config.user = { name: "Some User", email: "[email protected]", // ...Other user data}; |
| window.buildshipchatwidget.config.widgettitle | خياري | عنوان القطعة. سيتم عرض هذا في الجزء العلوي من القطعة. الإعدادات الافتراضية إلى Chatbot . |
| window.buildshipchatwidget.config.greetingMessage | خياري | الرسالة التي سيتم عرضها (كما لو تم إرسالها من قبل النظام) عندما يتم فتح عنصر واجهة المستخدم لأول مرة. الإعدادات الافتراضية لعدم عرض أي رسالة تحية. |
| window.buildshipchatwidget.config.disableRoralert | خياري | تعطيل تنبيهات الخطأ في حالة عدم تعيين عنوان URL ، إذا فشل الطلب ، إلخ. الافتراضيات إلى false . |
| window.buildshipchatwidget.config.closeonoutsideclick | خياري | يغلق القطعة عندما ينقر المستخدم خارج الجسم عن واجهة المستخدم. إذا تم ضبطها على false ، فستحتاج إلى استخدام طريقة close() (الواردة في الكائن window.buildShipChatWidget ) لتكون قادرًا على إغلاق عنصر واجهة المستخدم برمجيًا (على سبيل المثال ، عن طريق إرفاقه بزر). الافتراضات إلى true . |
| window.buildshipchatwidget.config.openonload | خياري | يفتح تلقائيًا عنصر واجهة المستخدم عند الانتهاء من التحميل (يتطلب زرًا مع سمة data-buildship-chat-widget-button لتكون موجودة على الصفحة). الإعدادات الافتراضية إلى false . |
| Window.BuildshipChatwidget.Config.ResponseIsastream | خياري | إذا تم ضبطها على true ، فإن القطعة تتوقع أن يتم تراجع الاستجابة من نقطة النهاية. يجب أن تستجيب نقطة النهاية بسلسلة من القطع التي تضيف أخيرًا إلى استجابة نقطة النهاية. ستقوم القطعة بتجميع هذه القطع عند استلامها وعرض الرسالة وتحديثها ، وتنتهي أخيرًا بالاستجابة الكاملة. تعرف على المزيد هنا. الإعدادات الافتراضية إلى false . |
يمكن تخصيص تصميم القطعة عن طريق تجاوز متغيرات CSS و/أو القواعد. (انظر هنا للحصول على قائمة بالمتغيرات والمحددات).
على سبيل المثال ، يمكن تجاوز المتغيرات مثل ذلك:
: root {
--buildship-chat-widget-primary-color : # 0000ff ;
}
/* Explicitly targeting the light theme is necessary in case the user's system theme is set to 'dark', but the body's `data-theme` attribute is set to `light` (perhaps via a theme toggle on the page). */
[ data-theme *= "light" ] {
...;
}يتم تنشيط الوضع المظلم عند:
يتم تعيين موضوع نظام المستخدم على dark (أي @media (prefers-color-scheme: dark) صحيح) وهذا ما تستخدمه الصفحة ، أو
يحتوي الجسم على سمة من سمات data-theme dark ، مثل ذلك:
< body data-theme =" dark " > </ body >يمكن تجاوز أنماط الوضع المظلم أيضًا:
@media ( prefers-color-scheme : dark) {
: root {
...;
}
}
[ data-theme *= "dark" ] {
...;
}الخط ورث من الجسم.
عندما يتم تحميل البرنامج النصي ، فإنه يبحث عن أي عناصر ذات سمة data-buildship-chat-widget-button وتفتح عنصر واجهة المستخدم عند النقر على أي من هذه العناصر.
بالإضافة إلى كائن config ، يعرض كائن window.buildShipChatWidget أيضًا طرق open() و close() و init() ، والتي يمكن استدعاؤها مباشرة.
تقبل طريقة open() event النقر ، وتستخدم event.target لحساب موضع القطعة باستخدام واجهة المستخدم العائمة.
طريقة close() تغلق القطعة.
تقوم طريقة init() بتهيئة عنصر واجهة المستخدم ، ويتم استدعاؤها تلقائيًا عندما تنتهي النافذة من التحميل. يمكن أن يطلق عليه يدويًا لإعادة تخصيص عنصر واجهة المستخدم إذا لزم الأمر (مفيد بشكل خاص في حالة SPAs ، حيث قد تحتاج إلى إعادة توجيه عنصر واجهة المستخدم بعد تغيير المسار).
