إعداد الأداة
اضبط الأداة بسمات data-* على وسم السكربت.
تضبط الأداة عبر سمات data-* على وسم السكربت. وكل ما تقرؤه الأداة من ذلك الوسم مذكور أدناه، مجمّعًا حسب وظيفته: الإعدادات الأساسية، والمتقدّمة، والسمات التي تشغّل سلوكًا كاملًا.
<script
type="module"
src="https://cdn.syncanix.com/widget.js"
data-key="pk_test_..."
data-position="bottom-left"
data-env="development"
data-chat-size="large"
data-locale="fr"
data-config-load="eager"
></script>السمات الأساسية
- data-key — مفتاحك القابل للنشر (pk_test_… أو pk_live_…). مطلوب.
- data-enabled — اضبطه على false لتحميل السكربت دون تركيب الويدجت (true افتراضيًا).
- data-position — زاوية المشغّل: bottom-right (افتراضي)، أو bottom-left، أو top-right، أو top-left.
- data-locale — يحدد لغة هذه الصفحة واتجاه نصها (مثل ar أو en-US). إذا تركته، فإن الأداة تتبع لغة صفحتك تلقائيا.
- data-chat-size — small (افتراضي)، أو medium، أو large، أو fullscreen، أو embedded.
- data-env — development أو production (وإلا يُستنتَج من بادئة المفتاح).
- data-theme — سلسلة JSON بتجاوزات رموز السمة.
تتبع الأداة لغة صفحتك من تلقاء نفسها، دون الحاجة إلى أي خصيصة. فهي تقرأ <html lang> الخاص بك، وإذا كانت صفحتك تعرض نصا بخط مختلف عما تعلنه، فإنها تثق بما يظهر على الشاشة. استخدم مبدل اللغة الخاص بموقعك وستتبعه المحادثة في المتصفح، بلا إعادة تحميل ودون فقدان المحادثة. لا تستخدم data-locale إلا إذا أردت تجاوز ذلك في صفحة معينة.
أول رسالة يكتبها الزائر تحدد لغة المحادثة، وتبقى كذلك حتى لو غير لغة موقعك بعد ذلك: محادثة بدأت بالعبرية تستمر بالإجابة بالعبرية. أما تسميات الأداة وإشعار الذكاء الاصطناعي فتظل تتبع صفحتك، حتى يبقى الإشعار مقروءا باللغة التي يتصفح بها. ومن أراد تغيير اللغة، يكفي أن يطلب ذلك في المحادثة.
السمات المتقدّمة
- data-origin — أصل واجهة برمجة تطبيقات Syncanix (الافتراضي هو واجهة الإنتاج).
- data-theme-name — يختار تصميمًا مسمّى من مكتبتك؛ وتتبع auto إعداد الفاتح/الداكن في الموقع المضيف.
- data-prompt-profile — يشغّل في هذه الصفحة ملف توجيه بعينه، بالاسم الذي نشرته به. لا يمكن تسمية سوى الملفات المنشورة؛ وأي قيمة أخرى ترجع إلى ملفك النشط.
- data-mount-target — محدِّد CSS لمكان تركيب أداة مضمَّنة.
- data-api-base-url — أين توجد واجهتك البرمجية إن كانت على مضيف غير مضيف الصفحة. وبدونه تُرسَل الإجراءات إلى مضيف الصفحة نفسها، وهو صحيح لموقع بمضيف واحد وخاطئ للفصل الشائع بين app. وapi.
- data-api-origins — قائمة مفصولة بفواصل بمصادر إضافية هي أيضًا واجهتك البرمجية. ولا يُلاحَظ إلا ما يذهب إلى مصادرك أنت، فالواجهة على مضيف منفصل يجب ذكرها هنا وإلا جرى تجاهلها عمدًا.
- data-theme-vars — يربط أدوار الألوان في الأداة بأسماء متغيّرات CSS الخاصة بك، بصيغة JSON. ويُحلّ مباشرةً فيتبع تبديلك بين الفاتح والداكن وحده؛ واقرنه بـ data-theme-source لتسمية العنصر الذي تُعلَن عليه متغيّراتك.
- data-config-load — lazy (جلب الإعدادات عند أول فتح، افتراضي) أو eager (عند التركيب).
- data-executor — اسم دالة عامة تنفّذ إجراءات المتصفّح أو المضيف.
- data-token-provider — اسم دالة عامة تُرجِع رمز المستخدم النهائي.
- data-step-up-provider — اسم دالة عامة تطلق إعادة المصادقة المعزَّزة.
- data-headers-provider — اسم دالة عامة تُرجِع ترويسات طلب إضافية.
- data-client-witness — تفعيل المراقبة السلبية لحركة واجهة برمجة التطبيقات، شكليًا فقط (معطَّل افتراضيًا).
- data-act-on-behalf-consent — اشتراط موافقة لمرة واحدة على «التصرّف نيابةً عنك» (معطَّل افتراضيًا).
تفعيل سلوك
هذه لا تضبط شكل الأداة ولا وجهتها — بل تشغّل سلوكًا كاملًا. وكل واحد منها مُطفأ ما لم تضفه.
- data-trigger — محدّد CSS لأزرار في صفحتك ينبغي أن تفتح المحادثة. عنصر تنقّل، أو رابط في التذييل، أو زرّ في حالة فارغة. والنقر يبدّل حالة اللوحة، وتُبقي الأداة حالة التوسّع مُعلَنة بشكل صحيح لقارئات الشاشة.
- data-ask-about — يتيح للزائر تحديد شيء في صفحتك وسؤال المساعد عنه. مُطفأ افتراضيًا، ويجب تفعيله لمساحة العمل أيضًا.
- data-haptics — اضبطه على false لمنع الأداة من إحداث اهتزاز في الهاتف عند موافقة الزائر على إجراء. مفعّل افتراضيًا، ويُكبَح دائمًا لمن يطلب جهازه تقليل ا لحركة.
- data-frame-mode — كيف تتصرّف الأداة داخل إطار: auto (الافتراضي) أو agent أو standalone. ولا يهمّ إلا إن كان تطبيقك يضمّن أجزاءً من نفسه في إطارات.
- data-frame-origins — قائمة مفصولة بفواصل بمصادر دقيقة يجوز لأداتك العليا التعامل مع صفحاتها المؤطّرة. والفراغ أو الغياب يعني لا شيء، وهو الافتراضي.
- data-capture-closed-roots — اضبطه على true إن كانت أجزاء من صفحتك مبنيّة بمكتبة مكوّنات خارجية لا يستطيع المساعد النظر داخلها. مُطفأ افتراضيًا، ولا يستحقّ اللجوء إليه إلا حين يكون عنصر تحكّم ينبغي أن يشغّله غير مرئيّ له.
إبقاء البيانات بعيدًا عن المساعد
يقرأ المساعد صفحتك ليعرف ما فيها. تحدِّد هذه الخيارات الثلاثة ما يُسمح له برؤيته، بحيث لا تضطر أي قيمة على الشاشة للوصول إليه — وتُحجب الأشكال ال شائعة للبيانات الشخصية افتراضيًا.
- data-block-selectors — قائمة محددات CSS مفصولة بفواصل للمناطق التي يجب ألا يراها المساعد أبدًا. أي عنصر مطابق وكل ما بداخله يُستبعد عند الالتقاط — غائب فعليًا وليس مُزالًا بعد قراءته. حدِّد الحاوية وليس كل عنصر تحكم على حدة.
- data-mask-selectors — قائمة محددات CSS مفصولة بفواصل تُحجب قيمها بينما يبقى الحقل نفسه مرئيًا. يعرف المساعد أن الحقل موجود لكنه لا يقرأ محتواه أبدًا — المعاملة نفسها التي تحظى بها كلمات المرور والبطاقات المُخفاة تلقائيًا.
- data-mask-pii — مُفعَّل افتراضيًا. أي قيمة تبدو كعنوان بريد إلكتروني أو رقم ضمان اجتماعي أمريكي أو رقم بطاقة تُحجب حتى إن لم يُسمِّها أي محدِّد. تُخفى القيمة فقط، ويبقى الحقل مرئيًا. لا تجعلها false إلا حيث تقبل وصول تلك القيم إلى المساعد وإلى النص المحفوظ.