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

# عنصر الويب

> تضمين محادثة Gorbit الذكاء الاصطناعي على أي موقع ويب

## نظرة عامة

أدخل قدرات الذكاء الاصطناعي لـ Gorbit مباشرة إلى موقعك مع عنصر محادثة قابل للتضمين. مبني بـ [Lit](https://lit.dev/)
مكونات الويب لأقصى توافق وأقل حجم حزمة.

يتكامل العنصر بسلاسة مع أي موقع ويب،
يوفر لزوارك وصولاً فورياً للمحادثات المدعومة بالذكاء الاصطناعي دون مغادرة صفحتك.

## الميزات

* **خفيف الوزن** - حزمة \~100-150kb مضغوطة بـ gzip
* **قابل للتخصيص بالكامل** - الألوان والعلامات التجارية والتنسيق لمطابقة موقعك
* **متجاوب** - نافذة منبثقة لسطح المكتب، ملء الشاشة للجوال
* **عزل Shadow DOM** - لا تضارب في الأنماط مع CSS الحالي
* **بث في الوقت الفعلي** - أحداث مرسلة من الخادم (SSE) لاستجابات سريعة
* **استمرار الجلسة** - المحادثات تصمد عبر إعادة تحميل الصفحات
* **وضعان للعرض** - مشغل عائم أو تضمين مضمن

## البدء السريع

أضف هذه الأسطر القليلة إلى موقعك:

```html theme={null}
<!-- تحميل العنصر -->
<script type="module" src="https://cdn.gorbit.app/widget/1.0/dist/gorbit-widget.js"></script>

<!-- التكوين والعرض -->
<gorbit-chat-widget
  backend-url="https://cloud.gorbit.app/api"
  api-key="your_api_key_here"
  mode="launcher"
>
</gorbit-chat-widget>
```

هذا كل شيء! سيظهر العنصر كزر عائم في الزاوية السفلية اليمنى من صفحتك.

<Warning>
  **استخدم دائماً مفتاح API محدود النطاق للعنصر.** مفتاح API مرئي في الكود من جانب العميل،
  لذا يجب أن يكون لديه أذونات محدودة وحدود معدل. لا تستخدم أبداً مفاتيح المسؤول أو الوصول الكامل.
</Warning>

## أوضاع العرض

### وضع المشغل (افتراضي)

<video src="https://mintlify.s3.us-west-1.amazonaws.com/gorbit/assets/overview/gorbit_anywhere/widget_popup.mov" alt="نافذة محادثة عنصر Gorbit" autoPlay />

يظهر زر عائم في الزاوية السفلية اليمنى. النقر عليه يفتح نافذة محادثة منبثقة.

* **سطح المكتب**: نافذة منبثقة 400x600px فوق الزر
* **الجوال**: تراكب بملء الشاشة لتجربة جوال مثلى

```html theme={null}
<gorbit-chat-widget mode="launcher"></gorbit-chat-widget>
```

### الوضع المضمن

<video src="https://mintlify.s3.us-west-1.amazonaws.com/gorbit/assets/overview/gorbit_anywhere/widget_inline.mov" alt="وضع عنصر Gorbit المضمن" autoPlay />

يتم تضمين العنصر مباشرة في تخطيط صفحتك. مثالي لصفحات الدعم المخصصة أو قواعد المعرفة.

```html theme={null}
<div style="width: 400px; height: 600px;">
  <gorbit-chat-widget mode="inline"></gorbit-chat-widget>
</div>
```

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

## خيارات التكوين

### السمات المطلوبة

| السمة         | النوع  | الوصف                                                 |
| ------------- | ------ | ----------------------------------------------------- |
| `backend-url` | string | عنوان URL لواجهة برمجة تطبيقات الواجهة الخلفية Gorbit |
| `api-key`     | string | مفتاح API للمصادقة                                    |

### السمات الاختيارية

| السمة              | النوع  | الافتراضي     | الوصف                                           |
| ------------------ | ------ | ------------- | ----------------------------------------------- |
| `agent-id`         | number | `undefined`   | وكيل/شخصية محدد للاستخدام                       |
| `agent-name`       | string | `"Assistant"` | اسم العرض في الرأس                              |
| `logo`             | string | شعار Gorbit   | عنوان URL لصورة شعار مخصص                       |
| `primary-color`    | string | `#1c1c1c`     | لون العلامة التجارية الأساسي (الأزرار، اللمسات) |
| `background-color` | string | `#e9e9e9`     | لون خلفية العنصر                                |
| `text-color`       | string | `#000000bf`   | لون النص (شفافية 75% سوداء)                     |
| `mode`             | string | `"launcher"`  | وضع العرض: `"launcher"` أو `"inline"`           |

### أمثلة التكوين

**الإعداد الأساسي:**

```html theme={null}
<gorbit-chat-widget
  backend-url="https://cloud.gorbit.app/api"
  api-key="on_abc123">
</gorbit-chat-widget>
```

**التخصيص الكامل:**

```html theme={null}
<gorbit-chat-widget
  backend-url="https://cloud.gorbit.app/api"
  api-key="on_abc123"
  agent-id="42"
  agent-name="روبوت الدعم"
  logo="https://yoursite.com/logo.png"
  primary-color="#FF6B35"
  background-color="#FFFFFF"
  text-color="#1A1A1A"
  mode="launcher"
>
</gorbit-chat-widget>
```

## التخصيص

### التنسيق

يستخدم العنصر خصائص CSS المخصصة للسمات.
جميع الأنماط محددة داخل Shadow DOM لمنع التضارب مع CSS لموقعك.

**الألوان الافتراضية:**

| متغير CSS                | الافتراضي   | الوصف               |
| ------------------------ | ----------- | ------------------- |
| `--gorbit-primary`       | `#1c1c1c`   | الأزرار، اللمسات    |
| `--gorbit-primary-hover` | `#000000`   | حالة التمرير        |
| `--gorbit-background`    | `#e9e9e9`   | خلفية العنصر        |
| `--gorbit-text`          | `#000000bf` | النص (شفافية 75%)   |
| `--gorbit-text-light`    | `#ffffff`   | نص أبيض على داكن    |
| `--gorbit-border`        | `#00000033` | الحدود (شفافية 20%) |

**التجاوز عبر السمات:**

```html theme={null}
<gorbit-chat-widget
  primary-color="#FF6B35"
  background-color="#FFFFFF"
  text-color="#1A1A1A"
>
</gorbit-chat-widget>
```

## البنية

يتواصل العنصر مباشرة مع واجهة Gorbit الخلفية باستخدام أحداث مرسلة من الخادم (SSE)
لاستجابات البث في الوقت الفعلي:

**تحميل العنصر** - حزمة JavaScript خفيفة الوزن تهيئ مكون الويب

**إنشاء الجلسة** - ينشئ العنصر جلسة محادثة عبر واجهة برمجة تطبيقات Gorbit

**المستخدم يرسل رسالة** - يُرسل الطلب إلى واجهة Gorbit الخلفية

**استجابة البث** - استجابة الذكاء الاصطناعي تتدفق في الوقت الفعلي عبر SSE

**عرض Markdown** - يتم تنسيق الاستجابات مع دعم markdown كامل

## دعم المتصفح

* Chrome/Edge 90+ (Chromium)
* Firefox 90+
* Safari 15+
* Mobile Safari (iOS 15+)
* Mobile Chrome (Android)

## النشر

للحصول على تعليمات نشر مفصلة، بما في ذلك إعداد الاستضافة الذاتية وأفضل ممارسات أمان مفتاح API،
انظر [دليل نشر عنصر الويب](/deployment/configuration/website_widget).

<Info>
  **تحتاج مساعدة في الإعداد؟** تواصل مع مسؤول Gorbit لتكوين مفتاح API أو المساعدة في النشر.
</Info>