واجهة برمجة تطبيقات الأداة (Widget API)

للمطورين، أو أي شخص يريد فتح الدردشة من خلال زره الخاص.

التثبيت

<script src="https://keyda.in/business/widget.js"
        data-key="kb_live_your_key_here" async></script>

يحتاج وسم النص البرمجي فقط إلى src و data-key. كل شيء آخر - الألوان، الموضع، التحية، اللغة - يأتي من لوحة التحكم الخاصة بك، لذلك لا تحتاج أبدًا إلى إعادة نشر موقعك لتغييرها.

يتم عرض الويدجت باللغة المحددة في Install → Language your bot speaks: زرها، والعناصر النائبة، والإشعارات، واتجاه التخطيط (العربية والأردية من اليمين إلى اليسار). تصل النصوص مع تكوين الويدجت، لذلك لا يوجد طلب ثانٍ ولا شيء لترجمته من جانبك.

الأوضاع

عائم (افتراضي). زر تشغيل في الزاوية يفتح لوحة الدردشة.

مضمن. ضع حاوية فارغة في الصفحة وستقوم الدردشة بملئها بدلاً من ذلك:

<div data-keyda-bot style="height:520px"></div>

يحتاج الحاوية إلى ارتفاع. في الوضع المضمن، تكون الدردشة مرئية دائماً، لذا لا يوجد شيء لفتحه أو إغلاقه.

JavaScript API

متاح على window.KeydaBot بمجرد تحميل البرنامج النصي:

مثال — افتح المحادثة من زر "تحدث معنا" الخاص بك:

<button onclick="KeydaBot.open()">Chat with us</button>

كيف يتصرف على صفحتك

• تفتح اللوحة فوق زر التشغيل، الذي يبقى في مكانه ويصبح عنصر التحكم في الإغلاق. النقر عليه مرة أخرى، أو النقر على ✕ في الرأس، أو الضغط على زر Escape يغلق الدردشة.
• يمكن للزائر توسيع اللوحة من الرأس — حيث تمتد لتشمل ارتفاع النافذة وبعرض يصل إلى 760 بكسل — ويتم حفظ هذا الاختيار في متصفحه. على الهواتف، تظهر اللوحة بملء الشاشة تلقائياً، لذا لا يظهر هذا التحكم هناك.
• يغيّر إعداد حجم الشعار الشعار نفسه لا الزر: يحافظ المشغل على حجمه ويكبر الشعار داخله. أما حجم الزر (التثبيت ← المظهر) فهو ما يغيّر حجم الزر نفسه — صغير أو متوسط أو كبير — أياً كان شكله.
• أربعة أشكال للزر: كبسولة تحمل تسميتك، وفقاعة دائرية، ومربع بزوايا مستديرة، وفقاعة محادثة بذيل. يقع الذيل على الجانب المواجه لصفحتك.
• يتم عرض كل شيء داخل shadow root، لذا لا يمكن لـ CSS الخاص بموقعك التأثير على الأداة، ولا يمكن لـ CSS الخاص بالأداة التأثير على موقعك.
• لا يتم تحميل اللوحة إلا عندما يفتحها الزائر، لذا فهي لا تبطئ سرعة صفحتك.
• تستمر محادثة الزائر لمدة 24 ساعة إذا عاد خلالها، ثم تبدأ من جديد بعد ذلك. تؤدي إعادة فتح اللوحة إلى استعادة سلسلة المحادثة — بما في ذلك الملفات، وأي سؤال من تسلسل الترحيب كان لا يزال بانتظار إجابة.
• تتيح أيقونة المشبك في حقل الكتابة للزائر إرفاق حتى ثلاث صور أو مستندات برسالة واحدة (الأحجام والأنواع في الحدود والأمان). تُصغَّر الصور داخل المتصفح قبل الرفع، لذا تغادر صورة بدقة 12 ميجابكسل الصفحة بحجم بضع مئات من الكيلوبايتات فقط. عطّل الملفات من التثبيت ويختفي الزر.
• يعمل تسلسل الترحيب على شكل فقاعات عادية: تتحول الخيارات إلى أزرار أسفل الفقاعة، ويظهر زر تخطٍّ عندما تكون الخطوة اختيارية، ويصبح النص التوضيحي في حقل الكتابة هو السؤال نفسه. يُتذكَّر التسلسل المكتمل في متصفح الزائر لمدة 30 يوماً.
• إذا تعذر الوصول إلى المساعد، تعرض الأداة رسالة قصيرة ولا تتسبب أبداً في ظهور خطأ على صفحتك.

ضمن حزم SDK للتطبيقات

تعمل نفس الدردشة في كل حزمة SDK، لذا تصل المرفقات وتسلسلات الترحيب إلى تطبيقك دون الحاجة إلى إصدار جديد — باستثناء واحد. فتح منتقي الملفات من عرض ويب هو مهمة التطبيق المضيف. تقوم حزم iOS وReact Native وIonic بذلك بالفعل؛ بينما تحتاج Android وFlutter إلى SDK 0.1.4 أو أحدث. في الإصدارات الأقدم، تتعرف الأداة على البيئة المضيفة وتُخفي أيقونة المشبك بدلاً من إظهار زر لا يفعل شيئاً.