> ## 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 تضمين المحادثة المدعومة بالذكاء الاصطناعي مباشرة على أي موقع.

تشمل الميزات:

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

## خيارات النشر

### النشر السحابي (موصى به)

لمستخدمي Gorbit Cloud، يتم تقديم الودجة من CDN لـ Gorbit. ببساطة أضف ما يلي إلى موقعك:

```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>
```

### نشر الاستضافة الذاتية

لمثيلات Gorbit المستضافة ذاتيًا، ستحتاج إلى بناء واستضافة الودجة بنفسك.

<Steps>
  <Step title="استنساخ المستودع">
    استنسخ [مستودع Gorbit](https://github.com/gorbit-dot-app/gorbit) من GitHub.
  </Step>

  <Step title="الانتقال إلى مجلد الودجة">
    ```bash theme={null}
    cd widget/
    ```
  </Step>

  <Step title="تثبيت التبعيات">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="الحصول على مفتاح API للودجة">
    انتقل إلى لوحة مشرف Gorbit وأنشئ مفتاح API جديد خصيصًا للودجة.

    <img className="rounded-image" src="https://mintcdn.com/gorbit/qYeWoSrsnkRPFQDm/assets/deployment/widget_api_key.png?fit=max&auto=format&n=qYeWoSrsnkRPFQDm&q=85&s=6d4eb33c04966fb4010190949bbb14fc" alt="Creating a widget API key in the Gorbit admin panel" width="1020" height="836" data-path="assets/deployment/widget_api_key.png" />

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

  <Step title="تكوين البيئة (اختياري)">
    للبنيات مع تكوين مدمج، أنشئ ملف `.env`:

    ```bash theme={null}
    cp .env.example .env
    ```

    عدّل `.env` واضبط رابط الخلفية ومفتاح API:

    ```
    VITE_WIDGET_BACKEND_URL=https://your-backend.com
    VITE_WIDGET_API_KEY=your_api_key
    ```
  </Step>

  <Step title="بناء الودجة">
    لـ **النشر السحابي** (التكوين عبر سمات HTML):

    ```bash theme={null}
    npm run build:cloud
    ```

    لـ **النشر المستضاف ذاتيًا** (التكوين مدمج في الحزمة):

    ```bash theme={null}
    npm run build:self-hosted
    ```
  </Step>

  <Step title="نشر الحزمة">
    حمّل `dist/gorbit-widget.js` إلى CDN أو خادم الويب الخاص بك.
  </Step>
</Steps>

### كود التضمين للعميل

بعد النشر، زوّد العملاء بكود التضمين:

**النمط السحابي (السمات مطلوبة):**

```html theme={null}
<script type="module" src="https://your-cdn.com/gorbit-widget.js"></script>
<gorbit-chat-widget
  backend-url="https://your-backend.com"
  api-key="customer_api_key"
  agent-name="Support"
  logo="https://path-to-your-logo.com/"
>
</gorbit-chat-widget>
```

**المستضاف ذاتيًا (التكوين مدمج):**

```html theme={null}
<script type="module" src="https://your-cdn.com/gorbit-widget.js"></script>
<gorbit-chat-widget
  agent-name="Support"
  logo="https://path-to-your-logo.com/"
>
</gorbit-chat-widget>
```

## مرجع التكوين

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

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

#### `backend-url`

رابط واجهة Gorbit الخلفية. هنا ترسل الودجة طلبات المحادثة.

* **Gorbit Cloud**: استخدم `https://cloud.gorbit.app` أو رابط المستأجر الخاص بك
* **مستضاف ذاتيًا**: استخدم رابط مثيل Gorbit (مثلاً، `https://gorbit.yourcompany.com`)

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

<!-- مستضاف ذاتيًا -->
<gorbit-chat-widget backend-url="https://gorbit.yourcompany.com" ...></gorbit-chat-widget>
```

#### `api-key`

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

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

<Note>
  للبنيات المستضافة ذاتيًا مع تكوين مدمج،
  يمكن تعيين `backend-url` و `api-key` عبر متغيرات البيئة أثناء البناء بدلاً من سمات HTML.
</Note>

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

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

## أمان مفتاح API

<Warning>
  مفتاح API للودجة مكشوف في الكود من جانب العميل. أنشئ دائمًا مفتاح API مخصص مع:

  * **أذونات محدودة** - وصول المحادثة فقط، لا ميزات المشرف
  * **تحديد المعدل** - منع الإساءة من الجهات الخبيثة
  * **المراقبة** - تتبع الاستخدام واكتشاف الحالات الشاذة
</Warning>

<Steps>
  <Step title="إنشاء مفتاح API خاص بالودجة">
    في لوحة مشرف Gorbit، أنشئ مفتاح API جديد بأذونات دنيا.
  </Step>

  <Step title="تفعيل تحديد المعدل">
    قم بتكوين حدود المعدل المناسبة لاستخدامك المتوقع.
  </Step>

  <Step title="مراقبة الاستخدام">
    راجع بانتظام استخدام مفتاح API للأنماط غير المعتادة.
  </Step>
</Steps>

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

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

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