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

# دمج Mellowtel في تطبيق Electron تاعك

دمج Mellowtel في تطبيق Electron عبر المنصات تاعك باش تخلي المستخدمين يشاركو عرض النطاق الترددي غير المستخدم تاعهم مقابل مكافآت أو ميزات متميزة. الـ SDK تاع Electron يخدم في أي مكان يخدم فيه Electron (macOS، Windows، وLinux).

<Warning>
  **موافقة المستخدم ضرورية.** الـ SDK يخدم غير كي المستخدم يوافق بشكل صريح. `init()` يرجع بصمت في وقت مبكر كي ما تكونش الموافقة موجودة، يعني إذا شفت الـ SDK يبدأ بلا أخطاء وما يرسلش حركة المرور، السبب الأكثر احتمال هو أن المستخدم ما وافقش بعد.
</Warning>

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

* حساب Mellowtel ومفتاح التكوين (جيب تاعك من [لوحة التحكم](https://www.mellowtel.com/mellowtel-auth/)).
* تطبيق Electron عنده وصول للعملية الرئيسية.

***

## التثبيت

### 1. إعداد توثيق npm

دير ملف `.npmrc` في الدليل الجذري تاع المشروع تاعك باش توجه npm إلى سجل Mellowtel GitHub Packages وتوثيق التثبيت:

```bash theme={null}
@mellowtel-inc:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN
```

بدل `YOUR_NPM_TOKEN` بالتوكن تاع التثبيت اللي تحت. اضغط باش تكشف، ومن بعد استعمل رمز النسخ في كتلة الكود باش تنسخها للحافظة تاعك.

<Accordion title="كشف توكن التثبيت">
  ```
  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
  ```
</Accordion>

### 2. تثبيت الحزمة

من الدليل الجذري تاع المشروع تاعك، ثبّت الـ SDK تاع Electron:

```bash theme={null}
npm install @mellowtel-inc/mellowtel-electron
```

### 3. أضف للكود تاعك

في ملف العملية الرئيسية تاع Electron (عادةً `main.ts` أو `main.js`)، استورد الـ SDK، أنشئه بمفتاح التكوين تاعك، اطلب الموافقة من المستخدم، ومن بعد ناد `init()` باش تبدأ الخدمة.

```typescript theme={null}
import { app, BrowserWindow } from 'electron';
import Mellowtel from '@mellowtel-inc/mellowtel-electron';


// كي تكون التطبيق جاهز، أنشئ النافذة
app.whenReady().then(async () => {
  let win = createWindow();
  
  const mellowtel: Mellowtel = new Mellowtel('YOUR_CONFIGURATION_KEY');

  await mellowtel.requestConsent(win, "احصل على 3 أشهر مجانية")
  await mellowtel.init()
});
```

<Note>
  بدل `YOUR_CONFIGURATION_KEY` بالمفتاح من لوحة التحكم تاع Mellowtel.
</Note>

**وش يدير كل نداء:**

* `new Mellowtel(configurationKey, options?)` ينشئ الـ SDK. الخيار الوحيد المتاح اليوم هو `disableLogs`، اللي الافتراضي تاعه `true`. حطها `false` أثناء الدمج باش تشوف حالة الاتصال ونشاط الطلبات في الطرفية تاعك.
* `requestConsent(window, incentive)` يعرض **مربع رسالة Electron أصلي** مربوط بالـ `BrowserWindow` اللي تمرره. الحجة الثانية هي العنوان البارز للحوار (مثلاً، `"احصل على 3 أشهر مجانية"`)، يُعرض فوق شرح ثابت لوش يدير Mellowtel. يرجع `true` إذا المستخدم قبل، `false` إذا المستخدم رفض أو أغلق الحوار، و`undefined` إذا كانت الموافقة موجودة بالفعل. الـ SDK يحتفظ بقرار الاشتراك تلقائيًا، يعني ما تحتاجش تنادي `optIn()` بعدين.
* `init()` يرمي فقط كي `configurationKey` يكون فارغ. إذا المستخدم ما وافقش، يسجل ويرجع بصمت. وإلا يفتح WebSocket للخلفية تاع Mellowtel. النداء غير محظور لواجهة المستخدم، يعني النوافذ تبقى مستجيبة بينما يتم إنشاء الاتصال.

### منع انقطاعات حوارات النظام (موصى به)

الـ SDK يجي مع مساعد اختياري، `setupMellowtelApp()`، اللي يضبط أعلام سطر الأوامر تاع Electron باش يقمع حوارات النظام (النوافذ المنبثقة للتعبئة التلقائية، أشرطة الترجمة، مطالبات توثيق NTLM / Kerberos، تكامل مدير كلمات المرور، تراكبات الوسائط، حوارات التشغيل الأول) اللي ممكن تقطع المستخدمين تاعك كي نوافذ Mellowtel المخفية تعالج الطلبات في الخلفية.

نادها في أعلى ملف العملية الرئيسية تاعك، **قبل** `app.whenReady()`، واستوردها جنب التصدير الافتراضي من `@mellowtel-inc/mellowtel-electron`. شوف [README الأصلي](https://github.com/mellowtel-inc/mellowtel-electron#setupmellowtelapp-optional) للاستخدام الرسمي.

***

## موافقة المستخدم

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

عندك طريقين باش تتعامل مع الموافقة:

1. **استعمل الحوار الأصلي المدمج** عبر `requestConsent(window, incentive)`. هذا هو الطريق الأسرع وهو اللي يظهر في الكود اللي فوق. يعرض `dialog.showMessageBox` أصلي تاع Electron مع نص الحافز تاعك كعنوان ويحتفظ بقرار المستخدم تلقائيًا.
2. **بني واجهة موافقة خاصة بك** ووجه الـ SDK عبر `optIn()`، `optOut()`، و`getOptInStatus()`. استعمل هذا إذا كنت حابب علامة تجارية مخصصة، شروحات أغنى، أو توطين يتجاوز اللي يوفره الحوار الأصلي.

### وش لازم يحتوي عليه حوار الموافقة تاعك

<Steps>
  <Step title="شرح وش يدير Mellowtel">
    استعمل لغة بسيطة. مثال: *"هذا التطبيق يستعمل Mellowtel لمشاركة عرض النطاق الترددي غير المستخدم تاعك. في المقابل، تحصل على \[ميزة/خاصية]. تقدر تلغي الاشتراك في أي وقت من الإعدادات."*
  </Step>

  <Step title="أعطي المستخدمين اختيار واضح">
    ضمّن خيارات قبول ورفض متميزة.
  </Step>

  <Step title="رابط إلى السياسات">
    ضمّن روابط إلى [شروط الخدمة](https://www.mellowtel.com/terms-and-conditions) و[سياسة الخصوصية](https://www.mellowtel.com/privacy-policy).
  </Step>
</Steps>

### خلي المستخدمين يغيرو موافقتهم لاحقًا

Mellowtel يوفر حوار إعدادات مدمج عبر `showConsentSettings(window)`. يعرض حوار أصلي مع أزرار الاشتراك / إلغاء الاشتراك اللي تتماشى مع الحالة الحالية تاع المستخدم، ويدير الانتقالات الداخلية للاشتراك / إلغاء الاشتراك كي المستخدم يغير اختياره. اربطها بعنصر قائمة أو زر إعدادات في التطبيق تاعك باش المستخدمين يقدرو يراجعو اختيارهم.

إذا كنت تفضل تبني شاشة إعدادات خاصة بك، ناد `getOptInStatus()` باش تقرأ الحالة الحالية و`optIn()` / `optOut()` باش تغيرها.

***

## مرجع الطرق

فئة `Mellowtel` تعرض الطرق العامة التالية. كلهم متاحين على المثيل اللي أنشأته بـ `new Mellowtel(configurationKey, options?)`.

**دورة الحياة**

* `init(): Promise<void>` يبدأ الخدمة إذا كان المستخدم مشترك، أو يرجع بصمت في وقت مبكر إذا ما كانش. يرمي فقط كي يكون مفتاح التكوين فارغ.
* `requestConsent(window: BrowserWindow, incentive: string): Promise<boolean | undefined>` يعرض حوار الموافقة الأصلي المدمج ويحتفظ بالنتيجة. يرجع `true` عند القبول، `false` عند الرفض أو الإغلاق، `undefined` إذا كانت الموافقة موجودة بالفعل.
* `showConsentSettings(window: BrowserWindow): Promise<void>` يعرض حوار إدارة الموافقة المدمج. الـ SDK يدير الانتقالات الداخلية للاشتراك / إلغاء الاشتراك كي المستخدم يغير اختياره.

**التحكم اليدوي في الاشتراك**

* `optIn(): Promise<void>` يعلّم المستخدم كمشترك بدون عرض حوار. استعمل هذا فقط بعد جمع الموافقة عبر واجهتك الخاصة.
* `optOut(): Promise<void>` يعلّم المستخدم كغير مشترك ويغلق اتصال WebSocket النشط.
* `getOptInStatus(): boolean | undefined` يرجع الحالة الحالية للاشتراك، أو `undefined` إذا المستخدم ما دارش اختيار.
* `getNodeId(): string` يرجع معرف عقدة Mellowtel لهذا التثبيت. مفيد عند تقديم تذاكر الدعم.

**عدادات الطلبات**

عدادات الطلبات تحتفظ محليًا عبر `electron-store` وتبقى بعد إعادة تشغيل التطبيق. عرضها في واجهتك الخاصة إذا كنت حابب تبين للمستخدمين تأثير اشتراكهم.

* `getTotalRequestCount(): number` يرجع العدد الإجمالي للطلبات المعالجة منذ التثبيت.
* `getDailyRequestCount(): number` يرجع عدد الطلبات المعالجة اليوم.
* `getRequestCountForDate(date: string): number` يرجع العدد لتاريخ محدد `YYYY-MM-DD`.
* `getDailyRequestsHistory(): { [date: string]: number }` يرجع كل عدد يومي كخريطة.
* `getRequestCountsInRange(startDate: string, endDate: string): { [date: string]: number }` يرجع الأعداد لفترة زمنية.
* `getRequestCounts(): { total: number; daily: number; dailyHistory: { [date: string]: number } }` يرجع كل العدادات الثلاثة في نداء واحد.

***

## الإيقاف ودورة الحياة

الـ SDK تاع Electron ما يسجلش معالجات `before-quit` أو `will-quit` الخاصة به. كي يخرج عملية Electron تاعك، يتم تمزيق اتصال WebSocket الخلفي معها، وما تحتاجش تنظيف صريح من جانبك.

إذا كنت حابب تفصل Mellowtel في منتصف الجلسة (مثلاً، كي المستخدم يغير إعداد "إيقاف مؤقت" في التطبيق تاعك)، ناد `optOut()`. هذا يمسح علم الاشتراك ويغلق الاتصال النشط. باش تعاود الاتصال، ناد `optIn()` متبوعًا بـ `init()`.

## استمرار الموافقة

حالة الاشتراك تتخزن في مسار `electron-store` الافتراضي للمنصة:

* macOS: `~/Library/Application Support/<YourAppName>/config.json`
* Windows: `%APPDATA%\<YourAppName>\config.json`
* Linux: `~/.config/<YourAppName>/config.json`

الحالة تبقى بعد تحديثات التطبيق. إلغاء تثبيت التطبيق تاعك ما يمسحهاش تلقائيًا إلا إذا كان برنامج إلغاء التثبيت تاعك يزيل دليل الإعدادات تاع التطبيق.

***

## حل المشاكل

<AccordionGroup>
  <Accordion title="خطأ &#x22;Package not found&#x22; أثناء التثبيت">
    1. تحقق أن `.npmrc` في جذر المشروع، بجانب `package.json`.
    2. تأكد أن التوكن ما عندوش مسافات بيضاء في البداية أو النهاية.
    3. امسح ذاكرة التخزين المؤقت لـ npm وأعد المحاولة عن طريق تشغيل `npm cache clean --force` متبوعًا بـ `npm install`.
  </Accordion>

  <Accordion title="خطأ &#x22;Unauthorized&#x22; أو 401 أثناء التثبيت">
    1. تحقق أن التوكن في `.npmrc` صحيح ونشط. إذا كنت غير متأكد، اطلب توكن جديد من [info@mellowtel.com](mailto:info@mellowtel.com).
    2. تأكد أن السطر `@mellowtel-inc:registry` موجود ويشير إلى `https://npm.pkg.github.com/`.
  </Accordion>

  <Accordion title="حوار الموافقة ما يظهرش">
    1. تأكد أنك تنادي `requestConsent` **بعد** ما `app.whenReady()` تحل ومع مرجع `BrowserWindow` صالح وغير مدمر.
    2. إذا كنت تستعمل `setupMellowtelApp()`، تحقق أنه يتم استدعاؤه **قبل** `app.whenReady()`، مش بعد.
  </Accordion>

  <Accordion title="`init()` يخدم بلا أخطاء لكن ما يصرا والو">
    هذا عن قصد. `init()` يرجع بصمت في وقت مبكر كي المستخدم ما وافقش. تحقق من `getOptInStatus()` باش تأكد. إذا رجع `undefined` أو `false`، ناد `requestConsent` أولاً. لاحظ أن السجل الداخلي "المستخدم ما وافقش" يتم ابتلاعه كي `disableLogs` يبقى في الافتراضي تاعه (شوف "السجلات صامتة" أدناه)، يعني الطرفية ما تعطيكش إشارة في أي اتجاه حتى تقلب ذلك العلم.
  </Accordion>

  <Accordion title="السجلات صامتة">
    خيار المنشئ `disableLogs` الافتراضي تاعه `true`. مرر `{ disableLogs: false }` كالحجة الثانية للمنشئ أثناء الدمج باش تعرض حالة الاتصال ونشاط الطلبات في الطرفية تاعك. هذا أيضًا أسرع طريقة باش تميز "ما وافقش" صامتة لا تعمل (شوف أعلاه) من فشل اتصال حقيقي.
  </Accordion>
</AccordionGroup>

***

الوقت المقدر للإكمال: 10-15 دقيقة.

إذا كنت تحتاج مساعدة أو عندك ملاحظات، تواصل معنا على [info@mellowtel.com](mailto:info@mellowtel.com) أو انضم لمجتمعنا على [Discord](https://discord.com/invite/txAZp4MSDe).