ضع ودجت الدردشة على موقعك

ودجت الدردشة هو نفس المساعد الذي تراه في لوحة التحكم، لكنه مضمَّن في موقعك ليجيب زوارك من مستنداتك. تشغيله يتم في ثلاث خطوات: أنشئ مفتاحًا في مفاتيح API، والصق كودًا قصيرًا في موقعك، ويمكنك أن تجربه أولًا في معاينة الودجت.

من يفعل ماذا

من	ماذا يفعل
أنت	تنشئ مفتاحًا، وتحدد مواقعك المسموح لها باستخدامه، وتلصق الكود في موقعك.
Agentech	تشغّل الودجت بالمفتاح الذي لصقته: تتعرف منه على مساحة عملك، وتجيب من مستنداتك، وتلتزم بالمواقع التي سمحت بها.

خطوة بخطوة

افتح مفاتيح API من القائمة الجانبية.
تحت أنشئ مفتاحًا، اكتب اسمًا (مثلًا "الموقع التسويقي").
- إذا كان هذا أول مفتاح تنشئه مساحة عملك، يُطلب منك أيضًا "أين سيعمل؟"، فاكتب عنوان الموقع (مثلًا https://www.acme.com). هذا الموقع وحده سيتمكن من استخدام المفتاح، ويمكنك إضافة مواقع أخرى لاحقًا.
اضغط أنشئ المفتاح. تظهر لوحة تم إنشاء المفتاح وفيها المفتاح نفسه، وتحت كود التضمين كود HTML الذي تلصقه بالضبط (انظر بالأسفل).
اضغط انسخ الكود، ثم الصقه في HTML موقعك قبل وسم </body> الختامي مباشرة، كما تقول اللوحة.
قبل النشر أو بعده، اضغط جرّبه بجانب المفتاح في جدول مفاتيح API لتفتح معاينة الودجت وتطرح عليه سؤالًا. هذا يعمل مهما كانت المواقع التي سمحت بها، لأن لوحة التحكم نفسها مسموح لها دائمًا (انظر بالأسفل).
ارجع إلى مفاتيح API في أي وقت لترى المفتاح مجددًا (إظهار/نسخ)، أو تضيف مواقع أخرى تحت المواقع المسموح بها، أو تدوير/إبطال المفتاح.

كود التضمين

لوحة تم إنشاء المفتاح، وأزرار جرّبه/نسخ في صف المفتاح، تعطيك دائمًا الكود الصحيح، فلا تكتبه بيدك. الكود وسم <script> واحد بخاصيتين:

<script src="https://cdn.assistant.agentech.tech/agentech-widget.js"
        data-api-key="YOUR_KEY_HERE"
        data-api-base="https://api.assistant.agentech.tech"></script>

data-api-key هو مفتاحك من مفاتيح API. وdata-api-base يوجّه الودجت إلى API الخاص بـ Agentech، ولا تحتاج إلى تغييره. يكفي أن تلصق هذا الكود مرة واحدة: يرسم الودجت زر الفتح الخاص به في زاوية سفلية من صفحتك، ويضيف عنصر <agentech-chat> له.

المفتاح مصمم ليكون عامًا. تقول صفحة مفاتيح API ذلك صراحة: "مفتاحك القابل للنشر هو ما يعرّف مساحة عملك لأداة الدردشة. يوضع في كود صفحتك، لذا تعامل معه كمفتاح عام — ما يمنع إساءة استخدامه هو قائمة المواقع بالأسفل، لا السرّية." يستطيع أي شخص قراءته بعرض كود صفحتك، وهذا متوقع. ما يمنع الغريب من استخدامه على موقعه هو قائمة المواقع المسموح بها، وليس سرّية المفتاح.

في أي زاوية يظهر الزر، وبأي لغة

في الصفحة من اليسار إلى اليمين يظهر زر الفتح في الزاوية السفلية اليمنى. وفي الصفحة من اليمين إلى اليسار، أي الموقع العربي، يظهر في الزاوية السفلية اليسرى، وتُفتح نافذة الدردشة من ذلك الجانب. لا تحتاج إلى ضبط ذلك: الودجت يقرأ اتجاه الصفحة التي يعمل فيها.

إذا كانت صفحتك عربية والزر ما زال على اليمين، فالصفحة نفسها لم تحدد اتجاهها. أضف dir="rtl" إلى وسم <html> (<html lang="ar" dir="rtl">) وسيتبعه الودجت. يمكنك أيضًا فرض الاتجاه على الودجت وحده بوضع dir="rtl" على عنصر السكربت، لكن إصلاح الصفحة أفضل، لأن كل ما فيها سينعكس أيضًا.

أزرار الودجت ونصوصه ("إرسال"، "بدعم من Agentech"، والنص الظاهر داخل مربع الرسالة) تتبع الإشارة نفسها، فالصفحة العربية تحصل على زر ونافذة بالعربية.

شيئان لا يتبعانها، عن قصد:

نصوصك أنت. العنوان، وافتتاحية المحادثة، والفقاعة الصغيرة بجانب الزر كلها من كتابتك. إذا حددتها في كود التضمين، تظهر كما كتبتها تمامًا، بأي لغة.
اتجاه كل رسالة. العميل الذي يكتب بالعربية تظهر رسالته من اليمين إلى اليسار، ومن يكتب بالإنجليزية تظهر رسالته من اليسار إلى اليمين، في المحادثة نفسها. هذا يتحدد لكل رسالة، لا لكل صفحة.

أما افتتاحية المحادثة التي يراها الزائر فهي إعداد منفصل. راجع إعداد مساعدك.

المواقع المسموح بها

تحت المواقع المسموح بها في صفحة مفاتيح API، اكتب الموقع أو المواقع التي يعمل عليها مفتاحك: موقع في كل سطر أو مفصولة بفواصل، مثل https://www.acme.com. استخدم https://*.acme.com للسماح بكل النطاقات الفرعية. يلزم موقع واحد على الأقل لحفظ القائمة.

إذا لم تحدد مساحة عملك أي موقع من قبل، ستظهر لك: "أداتك تقبل أي موقع. لم يحدد أحد المواقع المسموح لها باستخدام مفتاحك، لذا يمكن لأي شخص ينسخه من كود صفحتك أن يستهلك رسائلك. أضف موقعك تحت المواقع المسموح بها." هذه حماية لمساحات العمل التي أنشأت مفتاحًا قبل وجود هذه القائمة: إلى أن تضيف موقعًا، يعمل المفتاح من أي مكان، تمامًا كأنه لا توجد قائمة.

معاينة الودجت

معاينة الودجت (صفحة معاينة الأداة) تتصل بنفس نقطة الدردشة العامة التي يستخدمها الودجت المضمَّن في موقعك، فالسؤال الذي تطرحه هناك يحصل على نفس الإجابة التي يحصل عليها الزائر في موقعك. استخدمها لتجربة الودجت، أو لتجربة تغيير في رسالته الافتتاحية، قبل أن تلمس موقعك الحقيقي أو دون أن تلمسه.

اختر المفتاح الذي تجرب به من قائمة المفتاح، وهي تعرض كل مفتاح غير مُبطَل. إذا فتحت المعاينة من رابط جرّبه الخاص بالمفتاح في صفحة مفاتيح API، يكون ذلك المفتاح محددًا مسبقًا. وإذا كان لديك مفتاح واحد صالح فقط، فلا يوجد ما تختاره.
لوحة التحكم هذه مسموح لها دائمًا باستخدام مفاتيحك، لذا تعمل التجربة هنا مهما كانت المواقع التي سمحت بها. المعاينة لا تمر بقائمة المواقع المسموح بها إطلاقًا، لذا لا تستطيع أن تخبرك هل سيُمنع موقع آخر. هي تخبرك فقط هل المفتاح ومستنداتك يعملان.
المفتاح الذي لا تظهر قيمته بعد (انظر "ak_… — دوّره لإظهاره" بالأسفل) لا يمكن استخدامه هنا، لأن المعاينة لا تعرض إلا المفاتيح التي تستطيع الإرسال بها فعلًا.

"هذه المحادثة غير متاحة حاليًا."

هذه هي الرسالة التي يراها الزائر داخل الودجت نفسه (وعلى الصفحة الإنجليزية: "This chat isn't available right now.") عندما يحاول إرسال رسالة والمفتاح أو الموقع غير مقبول. لها سببان مختلفان يبدوان للزائر متشابهين:

الموقع ليس في قائمة المواقع المسموح بها. قارن العنوان الظاهر في شريط عنوان المتصفح بما حفظته بالضبط: https://www.acme.com وhttps://acme.com عنوانان مختلفان، وكذلك http:// وhttps://. أضف العنوان الناقص تحت المواقع المسموح بها واحفظ.
المفتاح خاطئ، أو تم تدويره، أو إبطاله. انسخ الكود الحالي من مفاتيح API من جديد وضعه مكان القديم في موقعك.

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

لاحظ أن زر الودجت وتحيته الافتتاحية قد يظهران بشكل طبيعي حتى مع وجود هذه المشكلة، فالخطأ لا يظهر إلا عندما يرسل الزائر سؤالًا فعلًا.

"ak_… — دوّره لإظهاره"

المفتاح الذي أُنشئ قبل أن نبدأ بحفظ المفاتيح بصيغة يمكن عرضها في هذه الصفحة، يظهر في عمود المفتاح بأحرفه الأولى فقط متبوعة بعبارة "… — دوّره لإظهاره"، مثلًا "ak_1a2b3c4d… — دوّره لإظهاره"، بدل القيمة الكاملة، لأننا لم نعد نملك نصه الأصلي لنعرضه لك. الحل: اضغط تدوير، ثم انسخ الكود الجديد من الصف وضعه مكان القديم في موقعك. يتوقف المفتاح القديم عن العمل لحظة التدوير.

متى تراسلنا

راجع متى تراسلنا. اذكر اسم مساحة عملك، وإذا كان الأمر يخص مفتاحًا واحدًا أو موقعًا واحدًا، فاذكر اسم المفتاح وعنوان الموقع.