أداة الويب

الأسماء التقنية مثل window.SingChat جزء من الأداة وواجهة API. انسخها في الكود كما هي تمامًا.

أداة الدردشة على الويب سكربت واحد، widget.js، يُقدَّم من askais.com. يضيف إلى صفحاتك زرًا لفتح الدردشة، ويرسم نافذة الدردشة داخل Shadow DOM، فتبقى أنماط موقعك منفصلة عن أنماط الأداة.

أضفها إلى موقعك

الصق هذا قبل </body> في كل صفحة يجب أن تظهر فيها الدردشة. تجد App ID في الإعدادات → صناديق الوارد.

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  async></script>

data-base-url مطلوب على موقعك: من دونه تبحث أداة الدردشة عن خادمها على نطاقك بدلًا من askais.com.

⚠️ حمّل widget.js من askais.com

لا تنزّل widget.js ولا تدمجه في شيفرتك. عند تحميله من askais.com يعمل دائمًا بأحدث إصدار؛ أما النسخة المحلية فتبقى جامدة وتفوتها كل الإصلاحات والميزات الجديدة.

سمات السكربت

يُضبط كل شيء بسمات data- على وسم السكربت:

• data-app-id — مطلوبة. App ID الخاص بصندوق الوارد.
• data-base-url — مطلوبة على موقعك. دائمًا https://askais.com.
• data-locale — اختيارية. تفرض لغة أداة الدردشة، مثل ja أو zh-Hant. إن حذفتها، تتبع الأداة لغة جهاز الزائر، ثم lang الخاصة بصفحتك.
• data-external-id — المعرّف الذي تستخدمه للمستخدم الذي سجّل الدخول.
• data-email — البريد الإلكتروني للمستخدم، ويظهر لفريقك.
• data-name — اسم المستخدم، ويظهر لفريقك.
• data-avatar-url — رابط صورة الملف الشخصي للمستخدم.
• data-hmac — توقيع الهوية، انظر أدناه.
• data-attrs — تفاصيل إضافية بصيغة JSON، مثل {"plan":"Pro"}، تظهر لفريقك في ملف الزائر. ويُتجاهَل JSON غير الصالح.

تضبط صفحة الدردشة داخل التطبيق السمات data-embed وdata-platform وdata-app-version وdata-device-model. راجع «الدردشة داخل التطبيق (WebView)».

الزوار الذين سجّلوا الدخول

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

<script src="https://askais.com/widget.js"
  data-app-id="YOUR_APP_ID"
  data-base-url="https://askais.com"
  data-external-id="user_123"
  data-email="ada@example.com"
  data-name="Ada Lovelace"
  data-attrs='{"plan":"Pro"}'
  data-hmac="SIGNATURE_FROM_YOUR_SERVER"
  async></script>

من دون data-external-id، تمنح أداة الدردشة كل متصفح معرّفًا مجهولًا خاصًا به، محفوظًا في التخزين المحلي للمتصفح، فيبقى سجل الدردشة بعد إعادة تحميل الصفحة في ذلك المتصفح. وإذا كان لصندوق الوارد نموذج ما قبل المحادثة، يملؤه الزوار المجهولون قبل بدء الدردشة.

الهوية الموثّقة (HMAC)

• hmac هو HMAC-SHA256 لقيمة externalId، مفتاحه هو المفتاح السري لصندوق الوارد، ويُكتب بالنظام الست عشري بأحرف صغيرة.
• احسبه على خادمك. لا يوضع المفتاح السري أبدًا في صفحة أو تطبيق.
• يظهر المفتاح السري مرة واحدة عند إنشاء صندوق الوارد، ومرة أخرى عند تدويره في الإعدادات → صناديق الوارد. ويؤدي تدويره إلى إبطال كل التوقيعات القديمة.
• أرسل دائمًا data-external-id مع data-hmac. يُتحقَّق من التوقيع مقابل المعرّف الخارجي، لذا يُرفض التوقيع المحسوب على البريد الإلكتروني وحده.
• إذا كان التوقيع خاطئًا، فلن تتمكن أداة الدردشة من الاتصال. ومن دون data-hmac تُؤخذ البيانات كما تقدّمها الصفحة، فيستطيع أي شخص قادر على تعديل الصفحة أن يدّعي أنه شخص آخر.

مثال لـ Node.js:

import { createHmac } from "node:crypto";

// Runs on your server. INBOX_SECRET_KEY never leaves it.
const hmac = createHmac("sha256", INBOX_SECRET_KEY)
  .update(user.id) // the exact value you pass as data-external-id
  .digest("hex");

تشغيل أداة الدردشة من JavaScript

لتشغيل أداة الدردشة بنفسك، مثلًا عندما تعرف صفحتك هوية المستخدم، حمّل السكربت من دون data-app-id واستدعِ window.SingChat.start() بعد اكتمال تحميله:

<script src="https://askais.com/widget.js"></script>
<script>
  window.SingChat.start({
    appId: "YOUR_APP_ID",
    baseUrl: "https://askais.com",
    // optional, for a signed-in user:
    externalId: "user_123",
    email: "ada@example.com",
    name: "Ada Lovelace",
    hmac: "SIGNATURE_FROM_YOUR_SERVER",
  });
</script>

start() هي الدالة الوحيدة التي يوفّرها السكربت. لا توجد دوال لفتح أداة الدردشة أو إغلاقها أو الاستماع إلى أحداثها؛ يفتحها الزوار من زر الدردشة.

المظهر والسلوك

• الإعدادات → صناديق الوارد، ثم وسّع صندوق وارد: اللون الأساسي ولون النص، والموضع (أسفل اليمين أو أسفل اليسار)، وحجم الفقاعة، والخلفية الفاتحة أو الداكنة، وعنوان النافذة وعنوانها الفرعي، مع معاينة مباشرة.
• نموذج ما قبل المحادثة (في المكان نفسه): اطلب من الزوار المجهولين بريدهم الإلكتروني أو اسمهم أو هاتفهم أو شركتهم قبل بدء الدردشة.
• النطاقات المسموح بها (في المكان نفسه): المواقع التي يُسمح لها بتحميل أداة الدردشة الخاصة بصندوق الوارد هذا. والقائمة الفارغة تسمح بأي موقع.
• علامة الأداة (في المكان نفسه): سطر «Powered by» أسفل الدردشة. وتعتمد إمكانية إخفائه أو عرض اسمك فيه على خطتك.
• تُضبط رسالة الترحيب التي يرسلها الذكاء الاصطناعي في وكيل الذكاء الاصطناعي، وفقاعات الأسئلة الشائعة القابلة للنقر في الإعدادات → الأسئلة الشائعة، والمقالات في Help Center.

الأمان

• App ID عام، ووضعه في صفحات HTML آمن.
• مكان المفتاح السري لصندوق الوارد هو خادمك فقط.
• استخدم الهوية الموثّقة (HMAC) كلما عرفت الصفحة هوية المستخدم.
• اقصر النطاقات المسموح بها على نطاقاتك، حتى لا يمكن تحميل أداة الدردشة على مواقع أخرى.