أداة الموقع

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

التثبيت هو لصق مقطع كود واحد في قالب الموقع. أما الباقي فيُضبط في لوحة التحكم ويُطبَّق دون العودة إلى الموقع.

من أين تحصل على كود التثبيت

في لوحة التحكم افتح الأداة ← مربع التثبيت على الموقع ← حقل كود الإدراج. زر نسخ يضع المقطع كاملاً في الحافظة.

يبدو الكود هكذا، مع مفتاحك الخاص بدلاً من النقاط:

<script>
  window.mybot = { key: "eu-1a2b3c4d-..." };
</script>
<script async src="https://getmybot.dev/loader.js"></script>

إذا رأيت بدل الكود عبارة تفيد بأنه لم يُصدر بعد مفتاح تثبيت لهذا البوت، فهذا يعني أن قناة أداة الموقع غير موصولة. تواصل مع الدعم: المفتاح يُصدر عند وصل القناة.

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

أين يوضع الكود

يوضع المقطع في HTML كل صفحة يجب أن تظهر فيها الأداة. عملياً يعني ذلك مرة واحدة في القالب المشترك للموقع: التذييل، أو حقل «الكود قبل </body>» في نظام إدارة المحتوى، أو حاوية في مدير الوسوم.

القواعد قصيرة:

أفضل موضع هو قبل وسم </body> مباشرةً. يعمل في <head> أيضاً، لكن المتصفح حينها يصرف وقتاً على الأداة قبل محتواك.
ترتيب الوسمين مهم: الأول يحدد المفتاح والثاني يحمّل الأداة. لا تبدّلهما ولا توزّعهما في مواضع مختلفة من الصفحة.
الوسم الثاني يحمل async فلا يعطّل عرض الصفحة. لا تحذف هذه الخاصية.
مقطع واحد لكل صفحة. نسختان تعنيان محاولتَي تشغيل.

بعد ذلك يحدد المُحمِّل بنفسه أي مركز بيانات يخدم البوت ويجلب من هناك جسم الأداة. لا يُطلب منك شيء لأجل ذلك.

مفتاح التثبيت مفتاح عام

المفتاح في الوسم الأول هو معرّف عام للبوت، وليس كلمة مرور. إنه موجود في مصدر الصفحة: يستطيع أي زائر فتح «عرض مصدر الصفحة» وقراءته. هكذا تعمل كل أدوات الدردشة، وهذا أمر طبيعي.

ما يهم فهمه:

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

قائمة النطاقات المسموح بها

للأداة قائمة نطاقات مسموح بها (origin allowlist) — عناوين المواقع التي يُسمح للأداة بالعمل انطلاقاً منها. تُحدَّد القائمة عند وصل القناة وتُعدَّل لاحقاً دون إعادة إصدار المفتاح: يبقى الكود في موقعك كما هو.

كل عنصر هو origin: البروتوكول والمضيف، والمنفذ إن لم يكن قياسياً.

https://example.com
https://www.example.com
https://shop.example.com
http://localhost:3000

المطابقة دقيقة حرفاً بحرف:

لا توجد رموز بديلة. https://*.example.com لن يعمل — عدّد النطاقات الفرعية واحداً واحداً.
example.com وwww.example.com عنصران مختلفان. إذا كان الموقع يُفتح بالعنوانين فأضفهما معاً.
http:// وhttps:// عنصران مختلفان أيضاً. عادةً يكفي https://، لكن بيئة الاختبار على http:// يجب إضافتها صراحةً.
لا يُسمح بمسار: https://example.com/shop سيُرفض، فالـ origin هو عنوان الموقع فقط.

إذا لم يكن نطاقك الحقيقي في القائمة فلن تعمل الأداة. سيتلقى متصفح الزائر رفضاً بعبارة «origin not allowed» ولن تُفتح الدردشة أصلاً. يحدث هذا عادةً بعد الانتقال إلى نطاق جديد، أو إضافة نطاق فرعي، أو إطلاق نسخة لغوية ثانية على عنوان مستقل — وكلٌّ منها يحتاج عنصراً خاصاً به.

إذا كانت القائمة فارغة فلا قيد على الإطلاق وتعمل الأداة من أي موقع. اعتبر ذلك حالة «لم يُضبط بعد» لا انفتاحاً مقصوداً: ما إن تعرف نطاقاتك حتى تُدخلها.

ما الذي يحميه هذا القيد وما الذي لا يحميه

يحمي: لن يستطيع موقع آخر تضمين أداتك عنده. لولا ذلك لاستطاع أحدهم نسخ الكود إلى صفحته، فتسلّم متصفحاتُ زوارك الحقيقيين محتوى المحادثات مع بوتك إلى ذلك الموقع. القائمة تسدّ هذه الثغرة بالضبط.

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

المظهر

في الأداة ← المظهر تُضبط:

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

بجانبها معاينة — أداة حية تُظهر النتيجة قبل الحفظ.

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

تصل التغييرات إلى موقعك تلقائياً: تقرأ الأداة إعداداتها عند تحميل الصفحة، ولا حاجة أبداً لتعديل الكود الملصق.

الزوار مجهولون

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

ويترتب على ذلك:

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

ربط الزائر بمستخدمك أنت

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

يكفي نداء واحد بدالة تُنتج البرهان:

mybot.identify(async (visitorId) => {
  const res = await fetch("/mybot-sign", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ userId: currentUser.id, visitorId }),
  });
  return res.json(); // { userId, signature, expiresAt }
});

تستدعي الأداة دالتك بالوسيط visitorId — معرّف الزائر المجهول الحالي لهذا المتصفح، القيمة الوحيدة التي لا يعرفها إلا الأداة — وتنتظر أن تُعيد، أو تتحلَّل إلى، { userId, signature, expiresAt }. مهمة دالتك الوحيدة هي تسليم visitorId إلى خادمك الخاص، مع معرّف المستخدم المسجَّل دخوله (currentUser.id أعلاه هو أياً كان شكله على موقعك)، وإرجاع ما يجيب به خادمك تماماً كما هو. التوقيع الفعلي يحدث على خادمك، لا داخل هذه الدالة — انظر أدناه.

دالة استدعاء، لا قيمة جاهزة ولا وسيلة لقراءة visitorId مباشرةً، لسببين:

توقيت الظهور. تُنشئ الأداة visitorId بشكل غير متزامن أثناء انطلاقها — فهو غير موجود في اللحظة التي يعمل فيها سكربت التحميل، ولا يُثبَّت mybot.identify نفسه إلا بعد اكتمال ذلك (التفاصيل أدناه). لذا، بحلول اللحظة التي تستطيع فيها صفحتك استدعاء mybot.identify أصلاً، يكون المعرّف الذي تتلقاه دالتك مضموناً أنه حقيقي. أما دالة قراءة بسيطة (getter) فلن تمنح هذا الضمان: فلا شيء يمنع صفحة من قراءته قبل أوانه بسطر واحد فلا تحصل على شيء، فتُنتَج بصمت توقيعاً لا يتطابق أبداً دون أي دليل على السبب.
النطاق. لا يحتاج كود صفحتك أبداً إلى الاحتفاظ بـvisitorId أو تخزينه أو تمريره يدوياً — فهو موجود فقط داخل هذه الدالة الواحدة، للنداء الوحيد الذي تحتاجه.

منذ اللحظة التي يغادر فيها الأداة، يصبح visitorId قدرة حاملة (bearer capability): فأي من يحصل على توقيع له يمكن دمجه مع جلسة ذلك الزائر. أرسله فقط إلى خادمك الخاص، عبر طلبك الموثَّق الخاص، ولا مكان آخر — لا تُسجّله في السجلات، ولا تُمرّره لطرف ثالث، ولا تضعه في نداء تحليلات من جهة المتصفح.

التوقيع يُحسب على خادمك الخاص فقط

داخل دالتك أعلاه، خادمك الخاص — لا المتصفح أبداً — يحسب التوقيع: HMAC-SHA256 بمفتاح هو سرّ الأداة، بالنظام الست عشري، أول 32 محرفاً، من ثلاث قيم مجموعة في رسالة واحدة. والصيغة نفسها معروضة في لوحة التحكم بجوار السرّ، تحت عنوان «Signing algorithm»:

signature = hex(HMAC-SHA256(key: secret, message: userId + "\n" + visitorId + "\n" + expiresAt)).slice(0, 32)

كل + "\n" + أعلاه هو حرف سطر جديد حقيقي بين الأجزاء، وليس الحرفين الشرطة المائلة العكسية وn. إن كانت دالة HMAC لديك تأخذ الرسالة كسلسلة واحدة، فاجمع الأجزاء الثلاثة بسطر جديد حقيقي — فثلاثة نداءات .update() منفصلة بلا سطر جديد بينها تحسب بصمة رسالة مختلفة وخاطئة.

الأجزاء الثلاثة:

userId — معرّف المستخدم المسجَّل دخوله، القيمة نفسها التي يتلقاها خادمك من الدالة أعلاه ويُعيدها في رده.
visitorId — معرّف الزائر المجهول الذي تلقّته دالتك وسيطاً ومرَّرته دون تغيير إلى خادمك.
expiresAt — طابع زمني بنظام يونكس بالثواني (لا بالميلي ثانية)، يصدره خادمك عند التوقيع، إلى أن ينتهي سريان هذا التوقيع بالذات. وترفض المنصة أي نداء يكون فيه expiresAt في الماضي أصلاً، وأي نداء يكون فيه أبعد من 24 ساعة في المستقبل — فوقِّع مباشرة قبل إعادته من دالتك، لا مرة واحدة ثم تخزينه لطلبات لاحقة.

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

احسب القيم الثلاث على خادمك وأعِدها من دالتك جاهزة. وهذه ليست شكليات: فلحساب التوقيع في المتصفح يلزم إرسال السرّ إلى هناك، أي تسليمه لكل زائر للصفحة. وعندها يستطيع أي أحد انتحال صفة أي عميل من عملائك وقراءة محادثته. إعادة التوقيع (وvisitorId/expiresAt اللذين حُسب من أجلهما) إلى المتصفح آمنة، أما السرّ فلا.

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

mybot.identify لا يوجد فوراً — بل يظهر بعد تحميل حزمة الأداة الأساسية، مع visitorId حقيقي (انظر «توقيت الظهور» أعلاه). نادِه من معالِج تحميل الصفحة، لا في أول سطر داخل <head>.

أين يوجد السرّ وكيف تبدّله

سرّ الأداة هو المفتاح الذي توقّع به. يوجد في إعدادات الأداة، في قسم «identify() secret». فإن قال القسم إن الأداة لم تُوصَل بعد، فأوصِل قناة الويب أولاً — يظهر السرّ معها.

الإظهار. يجلب زر «Reveal secret» القيمة. ولا تظهر نصاً مكشوفاً: ترى أولاً نقاطاً، ويُظهر المحارف مفتاحٌ منفصل هو «Show» (وللإخفاء «Mask»). وبجانبه زر «Clear from screen» الذي يزيل القيمة عن الشاشة.

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

وبعد النسخ رتِّب خلفك بنفسك. لا تستطيع المنصة إفراغ حافظتك: لا سبيل موثوقاً لفعل ذلك من المتصفح، فلا نَعِد به. أزِل القيمة عن الشاشة وأفرغ الحافظة يدوياً عند الانتهاء، خصوصاً على حاسوب مشترك.

التبديل. زر «Rotate secret» مع خطوة تأكيد. وهو إجراء كاسر فوراً: ما إن يوجد السرّ الجديد حتى يتوقف القديم عن اجتياز التحقق. لا نافذة تداخل — ولا لحظة يعمل فيها المفتاحان معاً.

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

لذا بدِّل عن قصد: جهّز أولاً إصدار الخادم الخلفي بالقيمة الجديدة، وعندها فقط اضغط «Rotate secret». أما الضغط لترى ما سيحدث فهو فكرة سيئة. وتُعرض القيمة الجديدة على الشاشة فور التبديل، فيمكنك نسخها في الحال.

كيف تتصرف الأداة داخل الصفحة

صُمّمت الأداة عمداً كي لا تتقاطع مع موقعك:

تعيش في حاوية معزولة (Shadow DOM مغلق). أنماطك لا تصل إلى داخلها، وأنماطها لا تتسرب إلى صفحتك. الأثر الجانبي أنك لا تستطيع تغيير شكلها بـ CSS خاص بك — استخدم إعدادات المظهر.
تمتد الحاوية على الشاشة كلها لكنها لا تعترض النقرات: تمرّ النقرات إلى الصفحة، ولا يستجيب سوى الزر ولوحة الدردشة.
الأداة دائماً فوق محتوى الصفحة، ولا تستطيع طبقاتك حجبها.
أي خطأ داخل الأداة يبقى داخلها: أسوأ الأحوال ألا يعمل زر الدردشة، ويستمر موقعك في العمل. إذا لم تظهر الأداة فابحث في وحدة تحكم المتصفح — في الغالب يكون السبب CSP أو نطاقاً غير مضاف إلى القائمة.

إذا لم تظهر الأداة

راجع بالترتيب:

افتح مصدر الصفحة وتأكد من وجود الوسمين ومن أن المفتاح ليس فارغاً.
تأكد أن عنوان الموقع مطابق تماماً لما في القائمة، بما في ذلك https:// وwww.
انظر في وحدة تحكم المتصفح: رسالة عن سياسة أمان المحتوى تعني وجوب السماح لمضيف المنصة في CSP الموقع.
تأكد أن مانع الإعلانات لا يحذف الأداة — جرّب في نافذة خاصة بلا إضافات.

ماذا بعد

القنوات — تعدد القنوات وقدرات كل قناة.
التفاعلات: الأساسيات — بماذا سيجيب البوت زائر الموقع.
الدعم والمشغّلون — كيف يجيب المشغّل داخل المحادثة.