> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkiasoft.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> سطر واحد في موقعك، وتجاوزات الألوان والموضع والزر التي يمكنك ضبطها من الصفحة نفسها.

الودجت هو زر المحادثة الذي يكلّمه زوارك، وتصل محادثاته إلى صندوق وارد لينكياسوفت بجانب واتساب
وماسنجر وبقية القنوات. إعداده داخل التطبيق مشروح في
[محادثة الموقع](/ar/help/channels/website-chat) — وهذه الصفحة هي الجزء الذي يدخل شيفرة موقعك.

## الكود

```html theme={null}
<script
  src="https://social.linkiasoft.com/widget/v1/loader.js"
  data-website-id="wc_pub_7c8d9e0f1a2b"
  async
></script>
```

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

هذا هو التركيب كله. كل ما يلي اختياري.

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

  لا تضع مفتاح API في صفحة أبدًا؛ فمفتاح لينكياسوفت يحمل صلاحيات على مساحة العمل كاملة — راجع
  [المصادقة](/ar/authentication).
</Note>

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

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

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

<h2 id="calling-before-load">
  مناداته قبل تحميله
</h2>

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

```html theme={null}
<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`. قائمة الأوامر كاملة في [واجهة الجافاسكربت](/ar/widget-api).

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

<h2 id="overriding-settings">
  تجاوز الإعدادات في صفحة واحدة
</h2>

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

```html theme={null}
<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` يستقبل عدد
الرسائل غير المقروءة كنص له:

```html theme={null}
<button data-linkia-open>
  تحدّث إلينا <span data-linkia-unread></span>
</button>
```

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

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

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

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

<CodeGroup>
  ```jsx React / Next.js theme={null}
  // 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>
    );
  }
  ```

  ```js Vue / Nuxt theme={null}
  // 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);
  });
  ```
</CodeGroup>

## سياسة أمان المحتوى (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` إلى النطاق الذي يخدم
شعارك وأي صور يرسلها زوارك — وهو شبكة الوسائط لدينا ما لم تضبط شبكتك.

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

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

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

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

لا تُضبط أي كوكيز، ولا يُشارَك شيء مع أي موقع آخر.

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

## الحدود

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

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

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

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

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

## التالي

<CardGroup cols={2}>
  <Card title="واجهة الجافاسكربت" icon="code" href="/ar/widget-api">
    افتحه وأغلقه، وعرّف الزوار، واستمع للأحداث.
  </Card>

  <Card title="التحقق من الهوية" icon="shield-halved" href="/ar/widget-api#identity-verification">
    وقّع معرّف المستخدم في خادمك حتى لا يدّعي متصفح هوية غيره.
  </Card>
</CardGroup>