تركيب ودجت المحادثة

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

الكود

<script
  src="https://social.linkiasoft.com/widget/v1/loader.js"
  data-website-id="wc_pub_7c8d9e0f1a2b"
  async
></script>

ضعه قبل وسم </body> في كل صفحة تريد ظهور الزر فيها. تجد data-website-id الخاص بك في تبويب التثبيت للقناة. هذا هو التركيب كله. كل ما يلي اختياري.

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

ماذا يكلّف صفحتك

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

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

مناداته قبل تحميله

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

<script>
  window.Linkia =
    window.Linkia ||
    function () {
      (Linkia.q = Linkia.q || []).push(arguments);
    };
</script>
<script
  src="https://social.linkiasoft.com/widget/v1/loader.js"
  data-website-id="wc_pub_7c8d9e0f1a2b"
  async
></script>

تُحفَظ المناداة التي تسبق وصول المُحمِّل ثم تُعاد عند وصوله، فلا يضيع شيء ولا ينتظر شيء حدث onload. قائمة الأوامر كاملة في واجهة الجافاسكربت.

إن كان موقعك يضبط script-src مع nonce، فالسكربت المضمّن أعلاه يحتاج ذلك الـ nonce. أما الكود المكوّن من سطر واحد فلا يحتاجه — لأنه بلا سكربت مضمّن أصلًا، ولهذا هو الخيار الافتراضي.

تجاوز الإعدادات في صفحة واحدة

لوحة التحكم تحمل الإعدادات الافتراضية، ويمكن لصفحة واحدة تجاوز الشكل والزر ورسالة الترحيب قبل الإقلاع:

<script>
  window.linkiaSettings = {
    appearance: { primaryColor: '#1d4ed8', position: 'left' },
    greeting: 'عندك سؤال عن الأسعار؟ اسأل مباشرة.',
    hideLauncher: false,
  };
</script>

اضبطه قبل تشغيل المُحمِّل، أو مرّر نفس الكائن عبر Linkia('init', …).

الحقل	الأثر
`appearance`	أي حقل مظهر من لوحة التحكم — الألوان، الموضع، المسافات، الانحناء، `zIndex`، `launcherIconUrl`.
`greeting`	يستبدل رسالة الترحيب في هذه الصفحة فقط، ولا يُترجم تلقائيًا.
`hideLauncher`	لا يرسم أي زر. استخدمه مع زرك أنت — انظر أدناه.
`autoOpen`	`'never'` أو `'on_new_message'`.
`websiteId`	بديل عن خاصية `data-website-id`.

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

زر خاص بك

أي عنصر يحمل data-linkia-open يفتح الودجت، وأي عنصر يحمل data-linkia-unread يستقبل عدد الرسائل غير المقروءة كنص له:

<button data-linkia-open>
  تحدّث إلينا <span data-linkia-unread></span>
</button>

كلاهما يعمل مع العناصر المُضافة لاحقًا أيضًا، فينفع مع أي إطار عمل يرسم الزر بعد الإقلاع. اضبط hideLauncher: true إن كنت لا تريد زرّنا كذلك.

تطبيقات الصفحة الواحدة

يصمد الودجت أمام التنقل من جهة العميل بنفسه — فهو غير مرتبط بمسار، ويتجاهل المُحمِّل أي حقن ثانٍ. لذلك:

احقن السكربت مرة واحدة في التخطيط الجذري أو index.html، لا داخل مكوّن صفحة.
لا تُعِد تركيبه مع كل مسار. وإن أردت إزالته كليًا فنادِ Linkia('destroy').
أعد التعريف عند تغيّر المستخدم فقط، لا مع كل تنقل.

// app/layout.tsx — يُرسم مرة واحدة لا مع كل مسار
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <script
          src="https://social.linkiasoft.com/widget/v1/loader.js"
          data-website-id="wc_pub_7c8d9e0f1a2b"
          async
        />
      </body>
    </html>
  );
}

// plugins/linkia.client.js
export default defineNuxtPlugin(() => {
  const script = document.createElement('script');
  script.src = 'https://social.linkiasoft.com/widget/v1/loader.js';
  script.async = true;
  script.dataset.websiteId = 'wc_pub_7c8d9e0f1a2b';
  document.body.appendChild(script);
});

سياسة أمان المحتوى (CSP)

إن كان موقعك يرسل CSP، فاسمح بنطاقنا في أربعة توجيهات:

script-src  https://social.linkiasoft.com;
frame-src   https://social.linkiasoft.com;
connect-src https://social.linkiasoft.com;
img-src     https://social.linkiasoft.com data:;

يغطي connect-src طلبات الودجت وبثّ EventSource معًا. ويحتاج img-src إلى النطاق الذي يخدم شعارك وأي صور يرسلها زوارك — وهو شبكة الوسائط لدينا ما لم تضبط شبكتك.

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

ماذا يخزّن الودجت

أين	ماذا	لماذا
`localStorage` في صفحتك، بالمفتاح `linkia.wc.<websiteId>`	رمز زائر موقّع، صالح ٣٠ يومًا	ليرى الزائر العائد سجلّ محادثاته
خادمنا	لغة الزائر ومنطقته الزمنية ومتصفحه وصفحته الحالية وبصمة مُجزّأة لعنوان IP	سياق للموظف، وحدود للاستخدام

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

نادِ Linkia('logout') في المكان الذي يعمل فيه تسجيل خروج موقعك. على جهاز مشترك، سيقرأ الشخص التالي محادثة من سبقه لولا ذلك.

الحدود


طول الرسالة	٤٠٠٠ حرف
حجم المرفق	٢٥ ميجابايت، عند تفعيل المرفقات في القناة
الرسائل لكل زائر	٣٠ في الدقيقة
المحادثات الجديدة لكل زائر	١٠ خلال ١٠ دقائق

تجاوز أي حد يعطي 429، ويعرض الودجت الرسالة كغير مُرسَلة مع زر إعادة محاولة بدل أن يفقدها.

عندما لا يظهر

اعمل بالترتيب — أول أربع نقاط تغطي الغالبية:

وحدة التحكم. يكتب الودجت سطرًا يبدأ بـ [Linkia chat] عند رفضه العمل، ويذكر السبب.
قائمة النطاقات. رمز 403 من /boot يعني أن هذا النطاق غير مُدرج. acme.com يشمل www.acme.com، أما النطاق الفرعي فيحتاج *.acme.com.
معرّف الموقع. رمز 401 يعني معرّفًا مجهولًا أو قناة موقوفة.
CSP. المخالفة في وحدة التحكم تذكر التوجيه الناقص.
مانعات الإعلانات. كثير منها يحجب ودجتات المحادثة. جرّب في متصفح نظيف.

واجهة الجافاسكربت

افتحه وأغلقه، وعرّف الزوار، واستمع للأحداث.

التحقق من الهوية

وقّع معرّف المستخدم في خادمك حتى لا يدّعي متصفح هوية غيره.

البداية

المراسلة

محادثة الموقع

إدارة العملاء

Webhooks

التكاملات

تركيب ودجت المحادثة

الكود

ماذا يكلّف صفحتك

مناداته قبل تحميله

تجاوز الإعدادات في صفحة واحدة

زر خاص بك

تطبيقات الصفحة الواحدة

سياسة أمان المحتوى (CSP)

ماذا يخزّن الودجت

الحدود

عندما لا يظهر

التالي

واجهة الجافاسكربت

التحقق من الهوية

​الكود

​ماذا يكلّف صفحتك

​مناداته قبل تحميله

​تجاوز الإعدادات في صفحة واحدة

​زر خاص بك

​تطبيقات الصفحة الواحدة

​سياسة أمان المحتوى (CSP)

​ماذا يخزّن الودجت

​الحدود

​عندما لا يظهر

​التالي

واجهة الجافاسكربت

التحقق من الهوية

الكود

ماذا يكلّف صفحتك

مناداته قبل تحميله

تجاوز الإعدادات في صفحة واحدة

زر خاص بك

تطبيقات الصفحة الواحدة

سياسة أمان المحتوى (CSP)

ماذا يخزّن الودجت

الحدود

عندما لا يظهر

التالي