Integrate Mellowtel in your Electron App

​

Prerequisites

• A Mellowtel account and configuration key (get yours from the dashboard).
• An Electron application with access to the main process.

​

Installation

​

1. Install the Package

npm install mellowtel-electron

​

2. Add to Your Code

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

// Optional: Call BEFORE app.ready to prevent system dialogs
setupMellowtelApp();

// When the app is ready, create the window
app.whenReady().then(async () => {
  let win = createWindow();

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

  await mellowtel.requestConsent(win, "Get 3 months free")
  await mellowtel.init()
});

• new Mellowtel(configurationKey, options?) instantiates the SDK. The only option available today is disableLogs, which defaults to true. Set it to false while integrating so you can see connection state and request activity in your terminal.
• requestConsent(window, incentive) renders a native Electron message box anchored to the BrowserWindow you pass in. The second argument is the dialog’s prominent headline (for example, "Get 3 months free"), shown above a fixed explanation of what Mellowtel does. It resolves to true if the user accepts, false if the user declines or closes the dialog, and undefined if consent is already on file. The SDK persists the opt-in decision automatically, so you do not need to call optIn() afterwards.
• init() throws only when configurationKey is empty. If the user has not opted in, it logs and returns silently. Otherwise it opens a WebSocket to Mellowtel’s backend. The call is non-blocking for renderer UI, so windows stay responsive while the connection is established.

​

Preventing system dialog interruptions (recommended)

​

User Consent

1. Use the built-in native dialog via requestConsent(window, incentive). This is the fastest path and is what the snippet above shows. It renders a native Electron dialog.showMessageBox with your incentive copy as the headline and persists the user’s decision automatically.
2. Build your own consent UI and drive the SDK through optIn(), optOut(), and getOptInStatus(). Use this if you want custom branding, richer explanations, or localization beyond what the native dialog offers.

​

What your consent dialog must include

​

Let users change their consent later

​

Method Reference

• init(): Promise<void> starts the service if the user has opted in, or silently returns early if not. Throws only when the configuration key is empty.
• shutdown(): Promise<void> cleans up SDK resources when the application is closing. Closes the WebSocket, destroys hidden worker windows, and clears background timers. Preserves the user’s opt-in preference.
• requestConsent(window: BrowserWindow, incentive: string): Promise<boolean | undefined> shows the built-in native consent dialog and persists the result. Returns true on accept, false on decline or close, undefined if consent was already given.
• showConsentSettings(window: BrowserWindow): Promise<void> shows the built-in manage-consent dialog. The SDK handles the opt-in / opt-out transitions internally when the user toggles their choice.

• optIn(): Promise<void> flags the user as opted in without showing a dialog. Use this only after collecting consent through your own UI.
• optOut(): Promise<void> flags the user as opted out and performs full cleanup (same resources as shutdown(), plus clearing the saved consent preference). There is no need to call shutdown() afterward.
• getOptInStatus(): boolean | undefined returns the current opt-in state, or undefined if the user has never made a choice.
• getNodeId(): string returns the Mellowtel node identifier for this installation. Useful when filing support tickets.

• getTotalRequestCount(): number returns the total requests processed since install.
• getDailyRequestCount(): number returns the number of requests processed today.
• getRequestCountForDate(date: string): number returns the count for a specific YYYY-MM-DD date.
• getDailyRequestsHistory(): { [date: string]: number } returns every daily count as a map.
• getRequestCountsInRange(startDate: string, endDate: string): { [date: string]: number } returns counts for a date range.
• getRequestCounts(): { total: number; daily: number; dailyHistory: { [date: string]: number } } returns all three counters in one call.

​

Lifecycle and app shutdown

• Closes the WebSocket connection.
• Destroys hidden worker windows.
• Clears background timers and network resources.
• Preserves the user’s opt-in preference.

​

Single-window applications

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

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

​

Tray applications

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

​

macOS applications

​

Opting out

await mellowtel.optOut();

​

Starting again

await mellowtel.optIn(); // Only needed after optOut()
await mellowtel.init();

​

Consent Persistence

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

​

Troubleshooting