Skip to main content
إدماج Mellowtel في تطبيق Electron تاعك اللي يخدم على عدة منصات باش المستخدمين يقدروا يشاركوا عرض النطاق الترددي تاع الإنترنت اللي ما يستعملوش مقابل مكافآت أو ميزات مميزة. الـ SDK تاع Electron يخدم في أي مكان يخدم فيه Electron (macOS، Windows، وLinux).
الموافقة تاع المستخدم ضرورية. الـ SDK يخدم غير كي المستخدم يوافق بشكل صريح. init() يرجع بصمت في حالة ما كانش موافقة مسجلة، لذا إذا شفت الـ SDK يبدأ بلا أخطاء وما يرسلش حركة مرور، السبب الأكثر احتمال هو أن المستخدم ما وافقش بعد.

​
المتطلبات المسبقة

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

​
التثبيت

​
1. إعداد مصادقة npm

صنع ملف .npmrc في الدليل الجذري تاع المشروع تاعك باش توجه npm إلى سجل حزم GitHub تاع Mellowtel وتوثيق التثبيت: 
@mellowtel-inc:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN
بدل YOUR_NPM_TOKEN بالتوكن تاع التثبيت اللي تحت. اضغط باش تكشف، ثم استعمل أيقونة النسخ في كتلة الكود باش تنسخه إلى الحافظة تاعك. 
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

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

من الدليل الجذري تاع المشروع تاعك، ثبّت الـ SDK تاع Electron: 
npm install @mellowtel-inc/mellowtel-electron

​
3. أضف إلى الكود تاعك

في ملف العملية الرئيسية تاع Electron (عادةً main.ts أو main.js)، استورد الـ SDK، وكونه بمفتاح التكوين تاعك، واطلب الموافقة من المستخدم، ثم ناد init() باش تبدأ الخدمة. 
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()
});
بدل 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-inc/mellowtel-electron. شوف README الرئيسي للاستعمال الرسمي.

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

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

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

1

اشرح وش يدير Mellowtel

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

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

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

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

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

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

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

​
استكشاف الأخطاء وإصلاحها

  1. تحقق أن .npmrc في جذر المشروع، بجانب package.json.
  2. تأكد أن التوكن ما عندوش مسافات زائدة في البداية أو النهاية.
  3. امسح ذاكرة التخزين المؤقت لـ npm وأعد المحاولة بتشغيل npm cache clean --force متبوع بـ npm install.
  1. تحقق أن التوكن في .npmrc صحيح ونشط. إذا كنت غير متأكد، اطلب توكن جديد من info@mellowtel.com.
  2. تأكد أن السطر @mellowtel-inc:registry موجود ويوجه إلى https://npm.pkg.github.com/.
  1. تأكد أنك تنادي requestConsent بعد ما app.whenReady() يحل ومع مرجع BrowserWindow صالح وغير مدمر.
  2. إذا كنت تستعمل setupMellowtelApp(), تحقق أنه ينادى قبل app.whenReady(), مش بعد.
هذي عن قصد. init() يرجع بصمت في حالة ما وافقش المستخدم. تحقق getOptInStatus() باش تأكد. إذا رجع undefined أو false, ناد requestConsent أولاً. لاحظ أن السجل الداخلي “المستخدم ما هوش مشترك” يبلع كي disableLogs يبقى على الافتراضي تاعه (شوف “السجلات صامتة” تحت)، لذا الطرفية ما تعطيكش إشارة في أي اتجاه حتى تقلب ذاك العلم.
الخيار disableLogs في المنشئ الافتراضي هو true. مرر { disableLogs: false } كالحجة الثانية للمنشئ أثناء الإدماج باش تبين حالة الاتصال ونشاط الطلب في الطرفية تاعك. هذي أيضاً أسرع طريقة للتمييز بين “عدم الاشتراك” الصامت (شوف فوق) وفشل اتصال حقيقي.
الوقت المقدر لإكمال: 10-15 دقيقة. إذا كنت تحتاج مساعدة أو عندك ملاحظات، اتصل بنا على info@mellowtel.com أو انضم إلى مجتمع Discord تاعنا.