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

​

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

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

​

التثبيت

​

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

@mellowtel-inc:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN

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

​

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

npm install @mellowtel-inc/mellowtel-electron

​

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

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()
});

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

​

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

​

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

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

​

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

​

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

​

مرجع الطرق

• 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 لهذا التثبيت. مفيد عند تقديم تذاكر الدعم.

• 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 } } يرجع كل العدادات الثلاثة في نداء واحد.

​

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

​

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

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

​

حل المشاكل