دليل إدماج و موافقة Mellowtel Electron SDK

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

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

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

حساب Mellowtel ومفتاح التكوين (جيب تاعك من لوحة التحكم).
تطبيق Electron عندو الوصول للعملية الرئيسية.

التثبيت

1. تثبيت الحزمة

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

npm install mellowtel-electron

2. أضف الكود تاعك

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

import { app, BrowserWindow } from 'electron';
import Mellowtel, { setupMellowtelApp } from 'mellowtel-electron';

// اختياري: نداء قبل app.ready باش تمنع حوارات النظام
setupMellowtelApp();

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

  const mellowtel: Mellowtel = new Mellowtel('YOUR_CONFIGURATION_KEY');

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

عوض YOUR_CONFIGURATION_KEY بالمفتاح من لوحة التحكم تاع Mellowtel.

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

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-electron. شوف README الأصلي للاستخدام الرسمي.

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

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

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

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

وش لازم يتضمن حوار الموافقة تاعك

اشرح وش يدير Mellowtel

استعمل لغة بسيطة. مثال: “هذا التطبيق يستعمل Mellowtel لمشاركة عرض النطاق الترددي الزائد تاع الإنترنت تاعك. في المقابل، تحصل على [فائدة/ميزة]. تقدر تلغي الاشتراك في أي وقت في الإعدادات.”

اعطي المستخدمين خيار واضح

ضمّن خيارات قبول ورفض متميزة.

رابط للسياسات

ضمّن روابط لـ شروط الخدمة وسياسة الخصوصية.

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

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

مرجع الطريقة

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

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

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

optIn(): Promise<void> يعلّم المستخدم كأنه وافق بدون عرض حوار. استعمل هذا غير بعد ما تجمع الموافقة عبر واجهة المستخدم تاعك.
optOut(): Promise<void> يعلّم المستخدم كأنه ألغى الاشتراك وينفذ تنظيف كامل (نفس الموارد كـ shutdown(), بالإضافة لإزالة تفضيل الموافقة المحفوظ). ما تحتاجش تنادي shutdown() بعدين.
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 } } يرجع كل العدادات الثلاثة في نداء واحد.

دورة الحياة وإغلاق التطبيق

بعد معالجة أول طلب، Mellowtel ممكن ينشئ نوافذ عامل Electron مخفية. التطبيقات المستضيفة لازم تنادي shutdown() كي التطبيق يغلق فعليا. shutdown():

يغلق اتصال الـ WebSocket.
يدمر نوافذ العامل المخفية.
يزيل المؤقتات الخلفية وموارد الشبكة.
يحافظ على تفضيل الاشتراك تاع المستخدم.

shutdown() مقابل optOut(): shutdown() هو تنظيف دورة حياة التطبيق — الموافقة محفوظة. optOut() يسحب موافقة المستخدم وينظف كل الموارد. ما تخلطش بين الاثنين.

التطبيقات ذات النافذة الواحدة

نداء shutdown() كي النافذة الرئيسية للتطبيق تغلق:

mainWindow.on('closed', async () => {
  mainWindow = null;

  if (process.platform !== 'darwin') {
    await mellowtel.shutdown();
    app.quit();
  }
});

ما تعتمدش فقط على حدث window-all-closed تاع Electron لأن نوافذ العامل المخفية تاع Mellowtel ممكن تمنعها من التشغيل.

تطبيقات الدرج

ما تناديش shutdown() كي تخفي النافذة فقط إلى درج النظام. نداء من إجراء الإنهاء الصريح:

trayQuitItem.click = async () => {
  await mellowtel.shutdown();
  app.quit();
};

تطبيقات macOS

إذا التطبيق يبقى نشط بعد ما تغلق نوافذه، نداء shutdown() غير كي المستخدم يغلق التطبيق فعليا.

إلغاء الاشتراك

optOut() ينفذ تنظيف كامل بالفعل:

await mellowtel.optOut();

ما تحتاجش تنادي shutdown() بعدين. على عكس shutdown(), optOut() يغير أيضا تفضيل الموافقة المحفوظ.

البدء من جديد

بعد shutdown() أو optOut(), Mellowtel يقدر يبدأ من جديد:

await mellowtel.optIn(); // مطلوب غير بعد optOut()
await mellowtel.init();

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

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

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

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

حل المشاكل

خطأ "Package not found" أثناء التثبيت

تأكد أنك راك تثبت mellowtel-electron (ماشي اسم حزمة GitHub Packages محدد).
امسح ذاكرة التخزين المؤقتة تاع npm وأعد المحاولة بتشغيل npm cache clean --force متبوع بـ npm install mellowtel-electron.

حوار الموافقة ما يظهرش

تأكد أنك تنادي requestConsent بعد ما app.whenReady() تحل وتكون عندك مرجع BrowserWindow صالح وغير مدمر.
إذا كنت تستعمل setupMellowtelApp(), تحقق أنه منادى قبل app.whenReady(), ماشي بعد.

"init() يشتغل بلا أخطاء لكن والو ما يصراش"

هذا عن قصد. init() يرجع بصمت في البداية كي المستخدم ما وافقش. تحقق من getOptInStatus() باش تأكد. إذا رجع undefined أو false, شغل requestConsent أولا. لاحظ أن السجل الداخلي “المستخدم ما وافقش” يبلع كي disableLogs يبقى في الافتراضي تاعو (شوف “السجلات صامتة” تحت), يعني التيرمينال ما يعطيكش إشارة في أي اتجاه حتى تقلب هذا العلم.

السجلات صامتة

خيار المنشئ disableLogs الافتراضي هو true. مرر { disableLogs: false } كالحجة الثانية للمنشئ أثناء الدمج باش تظهر حالة الاتصال ونشاط الطلب في التيرمينال تاعك. هذا أيضا أسرع طريقة لتمييز “ما وافقش” بصمت (شوف فوق) من فشل اتصال حقيقي.

الوقت المقدر للإكمال: 10-15 دقيقة. إذا احتجت مساعدة أو عندك ملاحظات، تواصل معنا على info@mellowtel.com أو انضم لمجتمعنا على Discord.

ابدأ

مفاهيم

تطبيقات سطح المكتب

إضافات المتصفح

الموقع

عناصر ميلوتيل

تطبيق الهاتف

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

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

التثبيت

1. تثبيت الحزمة

2. أضف الكود تاعك

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

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

وش لازم يتضمن حوار الموافقة تاعك

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

مرجع الطريقة

دورة الحياة وإغلاق التطبيق

التطبيقات ذات النافذة الواحدة

تطبيقات الدرج

تطبيقات macOS

إلغاء الاشتراك

البدء من جديد

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

حل المشاكل

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

​التثبيت

​1. تثبيت الحزمة

​2. أضف الكود تاعك

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

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

​وش لازم يتضمن حوار الموافقة تاعك

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

​مرجع الطريقة

​دورة الحياة وإغلاق التطبيق

​التطبيقات ذات النافذة الواحدة

​تطبيقات الدرج

​تطبيقات macOS

​إلغاء الاشتراك

​البدء من جديد

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

​حل المشاكل

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

التثبيت

1. تثبيت الحزمة

2. أضف الكود تاعك

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

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

وش لازم يتضمن حوار الموافقة تاعك

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

مرجع الطريقة

دورة الحياة وإغلاق التطبيق

التطبيقات ذات النافذة الواحدة

تطبيقات الدرج

تطبيقات macOS

إلغاء الاشتراك

البدء من جديد

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

حل المشاكل