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

# أداة صوتية قابلة للتضمين

> أضف وكيلاً صوتياً بالذكاء الاصطناعي إلى أي موقع ويب ببضعة أسطر من التعليمات البرمجية

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

تُعرض الأداة كشريط بتأثير زجاجي يتكيف مع النسقين الفاتح والداكن، مع ألوان تمييز وموضع قابلين للتخصيص. تُوزَّع كحزمة npm باسم `@thunderphone/widget`، وهي متاحة أيضًا عبر CDN للبيئات التي لا تستخدم أدوات تجميع الحزم.

<Frame>
  <img src="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="ThunderPhone widget in light and dark themes with various accent colors" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## المتطلبات الأساسية

قبل تضمين الأداة، أكمل هذه الخطوات الثلاث في [لوحة تحكم ThunderPhone](https://app.thunderphone.com):

<Steps>
  <Step title="إنشاء مفتاح API قابل للنشر">
    انتقل إلى **المطورون** في إعدادات لوحة التحكم وأنشئ مفتاحًا قابلاً للنشر. تبدأ المفاتيح القابلة للنشر بـ `pk_live_` ويمكن تضمينها بأمان في التعليمات البرمجية من جانب العميل.
  </Step>

  <Step title="تهيئة النطاقات المسموح بها">
    في إعدادات المطورون نفسها، أضف النطاقات التي ستُضمَّن فيها الأداة. يُسمح دائمًا بـ `localhost` للتطوير. تُدعَم أحرف البدل (مثل `*.example.com`).
  </Step>

  <Step title="إنشاء أداة ويب">
    انتقل إلى **عناصر واجهة الويب** في لوحة التحكم وأنشئ أداة. اختر الوكيل الذي تريد إتاحته والمفتاح القابل للنشر الذي تريد استخدامه. يُحدَّد الوكيل تلقائيًا من تهيئة مفتاحك القابل للنشر.
  </Step>
</Steps>

<Warning>
  المفاتيح القابلة للنشر (`pk_live_...`) **ليست** نفسها رموز API السرية الخاصة بك. صُممت المفاتيح القابلة للنشر للاستخدام من جانب العميل، ويقتصر نطاقها على جلسات الأداة ضمن نطاقاتك المسموح بها. لا تستخدم رمز API السري مطلقًا في التعليمات البرمجية من جانب العميل.
</Warning>

***

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

ثبّت الحزمة:

```bash theme={null}
npm install @thunderphone/widget
```

أضف الأداة إلى تطبيقك:

```tsx theme={null}
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

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

***

## التخصيص

تحتوي الأداة على أربع خصائص للمظهر:

| الخاصية        | القيمة الافتراضية                       | الوصف                                                                            |
| -------------- | --------------------------------------- | -------------------------------------------------------------------------------- |
| `theme`        | `'light'`                               | `'light'` للزجاج الأبيض، و`'dark'` للزجاج الداكن                                 |
| `primaryColor` | `'#000000'` (فاتح) / `'#ffffff'` (داكن) | لون التمييز لزر البدء وشكل الموجة ومؤشر الاتصال                                  |
| `title`        | `'Voice assistant'`                     | النص المعروض في الأداة                                                           |
| `position`     | `'bottom-right'`                        | زاوية إطار العرض: `'bottom-right'`، `'bottom-left'`، `'top-right'`، `'top-left'` |

<CodeGroup>
  ```tsx Light theme (default) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

  ```tsx Dark theme with custom color theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
    theme="dark"
    primaryColor="#8b5cf6"
    title="Ask our AI"
  />
  ```
</CodeGroup>

تخصّص ثلاث خصائص إضافية الجلسة بدلًا من المظهر -- وتُمرَّر جميعها إلى طلب الجلسة عند بدء مكالمة:

| الخاصية    | الوصف                                                                                  |
| ---------- | -------------------------------------------------------------------------------------- |
| `language` | تجاوز لغة لكل جلسة -- رمز أو إعدادات محلية مثل `en` أو `es` أو `fr-FR`                 |
| `voice`    | تجاوز صوت لكل جلسة -- اسم صوت مثل `maria`                                              |
| `context`  | سياق واقعي للصفحة أو الموقع يُمرَّر إلى الوكيل (يُقتطع على جانب الخادم إلى 12,000 حرف) |

راجع [مرجع مكوّن React](/ar/widget/react) للاطلاع على جدول الخصائص الكامل.

لإنشاء واجهة مستخدم مخصصة بالكامل، استخدم [الخطاف بلا واجهة](/ar/widget/headless-hook) لإدارة الجلسة الصوتية أثناء بناء واجهتك الخاصة. يوفّر الخطاف مستويات الصوت في الوقت الفعلي لإنشاء تصورات مرئية تتفاعل مع الصوت.

***

## خيارات التكامل

اختر طريقة التكامل التي تناسب منظومتك:

<CardGroup cols={3}>
  <Card title="مكوّن React" icon="react" href="/ar/widget/react">
    مكوّن واجهة مستخدم جاهز مسبقًا مع عناصر تحكم مدمجة بالمكالمات وعرض للحالة. استورده، مرّر الخصائص، وانتهى الأمر.
  </Card>

  <Card title="خطاف Headless" icon="code" href="/ar/widget/headless-hook">
    تحكم كامل في واجهة المستخدم. يدير الخطاف `useThunderPhone` الجلسة الصوتية بينما تنشئ واجهتك الخاصة.
  </Card>

  <Card title="وسم CDN / Script" icon="globe" href="/ar/widget/cdn-script-tag">
    لا حاجة إلى أداة تجميع. حمّل الأداة عبر وسم script للمواقع الثابتة وWordPress والبيئات الأخرى غير المعتمدة على React.
  </Card>
</CardGroup>

***

## التنسيق

تأتي الأداة مع سمات فاتحة وداكنة مدمجة يتحكم بها الخاصية `theme`، ولون تمييز يتحكم به الخاصية `primaryColor`. ولتخصيص أعمق، يمكنك تجاوز خصائص وفئات CSS المخصصة. راجع [دليل التنسيق](/ar/widget/styling) للتفاصيل.

<Note>
  هل تحتاج إلى مساعدة؟ تواصل معنا عبر [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>