> ## 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. # Integriere Mellowtel in deine Electron-App Integriere Mellowtel in deine plattformübergreifende Electron-Anwendung, um Nutzern zu ermöglichen, ihre ungenutzte Internetbandbreite im Austausch für Belohnungen oder Premium-Funktionen zu teilen. Das Electron SDK läuft überall dort, wo Electron läuft (macOS, Windows und Linux). **Die Zustimmung des Nutzers ist obligatorisch.** Das SDK funktioniert nur, wenn der Nutzer ausdrücklich zugestimmt hat. `init()` kehrt stillschweigend frühzeitig zurück, wenn keine Zustimmung vorliegt. Wenn du also siehst, dass das SDK ohne Fehler startet, aber nie Daten sendet, ist der wahrscheinlichste Grund, dass der Nutzer noch nicht zugestimmt hat. ## Voraussetzungen * Ein Mellowtel-Konto und ein Konfigurationsschlüssel (erhalte deinen im [Dashboard](https://www.mellowtel.com/mellowtel-auth/)). * Eine Electron-Anwendung mit Zugriff auf den Hauptprozess. *** ## Installation ### 1. Konfiguriere npm-Authentifizierung Erstelle eine `.npmrc`-Datei im Stammverzeichnis deines Projekts, um npm auf das Mellowtel GitHub Packages-Registry zu verweisen und die Installation zu authentifizieren: ```bash theme={null} @mellowtel-inc:registry=https://npm.pkg.github.com/ //npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN ``` Ersetze `YOUR_NPM_TOKEN` durch das untenstehende Installations-Token. Klicke, um es anzuzeigen, und verwende dann das Kopiersymbol im Codeblock, um es in deine Zwischenablage zu kopieren. ``` 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 ``` ### 2. Installiere das Paket Installiere das Electron SDK aus dem Stammverzeichnis deines Projekts: ```bash theme={null} npm install @mellowtel-inc/mellowtel-electron ``` ### 3. Füge es deinem Code hinzu Importiere das SDK in deiner Electron-Hauptprozessdatei (typischerweise `main.ts` oder `main.js`), instanziiere es mit deinem Konfigurationsschlüssel, fordere die Zustimmung des Nutzers an und rufe dann `init()` auf, um den Dienst zu starten. ```typescript theme={null} import { app, BrowserWindow } from 'electron'; import Mellowtel from '@mellowtel-inc/mellowtel-electron'; // Wenn die App bereit ist, erstelle das Fenster app.whenReady().then(async () => { let win = createWindow(); const mellowtel: Mellowtel = new Mellowtel('YOUR_CONFIGURATION_KEY'); await mellowtel.requestConsent(win, "Erhalte 3 Monate kostenlos") await mellowtel.init() }); ``` Ersetze `YOUR_CONFIGURATION_KEY` durch den Schlüssel aus deinem Mellowtel-Dashboard. **Was jeder Aufruf macht:** * `new Mellowtel(configurationKey, options?)` instanziiert das SDK. Die einzige heute verfügbare Option ist `disableLogs`, die standardmäßig auf `true` gesetzt ist. Setze sie auf `false`, während du integrierst, damit du den Verbindungsstatus und die Anforderungsaktivität in deinem Terminal sehen kannst. * `requestConsent(window, incentive)` rendert eine **native Electron-Nachricht** verankert an das übergebene `BrowserWindow`. Das zweite Argument ist die prominente Überschrift des Dialogs (zum Beispiel, `"Erhalte 3 Monate kostenlos"`), die über einer festen Erklärung dessen, was Mellowtel tut, angezeigt wird. Es wird `true` zurückgegeben, wenn der Nutzer zustimmt, `false`, wenn der Nutzer ablehnt oder den Dialog schließt, und `undefined`, wenn die Zustimmung bereits vorliegt. Das SDK speichert die Opt-in-Entscheidung automatisch, sodass du danach nicht `optIn()` aufrufen musst. * `init()` wirft nur, wenn `configurationKey` leer ist. Wenn der Nutzer nicht zugestimmt hat, wird es protokolliert und kehrt stillschweigend zurück. Andernfalls öffnet es eine WebSocket-Verbindung zum Backend von Mellowtel. Der Aufruf blockiert nicht die Renderer-UI, sodass Fenster während der Verbindungsherstellung reaktionsfähig bleiben. ### Verhindern von Systemdialogunterbrechungen (empfohlen) Das SDK wird mit einem optionalen Helfer, `setupMellowtelApp()`, geliefert, der Electron-Befehlszeilenflags konfiguriert, um Systemdialoge (Autofill-Popups, Übersetzungsleisten, NTLM / Kerberos-Authentifizierungsaufforderungen, Passwortmanager-Integration, Medienüberlagerungen, Erststartdialoge) zu unterdrücken, die andernfalls deine Nutzer unterbrechen würden, wenn Mellowtels versteckte Fenster im Hintergrund Anfragen verarbeiten. Rufe es oben in deiner Hauptprozessdatei auf, **bevor** `app.whenReady()`, und importiere es zusammen mit dem Standardexport von `@mellowtel-inc/mellowtel-electron`. Siehe das [upstream README](https://github.com/mellowtel-inc/mellowtel-electron#setupmellowtelapp-optional) für die kanonische Verwendung. *** ## Nutzerzustimmung Das Anzeigen eines Zustimmungsdialogs ist **obligatorisch**. Du musst den Nutzern ermöglichen, ausdrücklich zuzustimmen, bevor du `init()` aufrufst, und du musst ihnen eine Möglichkeit bieten, ihren Opt-in-Status jederzeit zu verwalten. Du hast zwei Wege, um die Zustimmung zu handhaben: 1. **Verwende den eingebauten nativen Dialog** über `requestConsent(window, incentive)`. Dies ist der schnellste Weg und wird im obigen Snippet gezeigt. Es rendert einen nativen Electron `dialog.showMessageBox` mit deinem Anreiztext als Überschrift und speichert die Entscheidung des Nutzers automatisch. 2. **Baue deine eigene Zustimmungs-UI** und steuere das SDK über `optIn()`, `optOut()` und `getOptInStatus()`. Verwende dies, wenn du benutzerdefinierte Markenbildung, reichhaltigere Erklärungen oder Lokalisierung über das hinaus, was der native Dialog bietet, möchtest. ### Was dein Zustimmungsdialog enthalten muss Verwende einfache Sprache. Beispiel: *"Diese App verwendet Mellowtel, um deine ungenutzte Internetbandbreite zu teilen. Im Gegenzug erhältst du \[Vorteil/Funktion]. Du kannst jederzeit in den Einstellungen ablehnen."* Füge deutliche Optionen für Akzeptieren und Ablehnen hinzu. Füge Links zu den [Nutzungsbedingungen](https://www.mellowtel.com/terms-and-conditions) und der [Datenschutzrichtlinie](https://www.mellowtel.com/privacy-policy) hinzu. ### Erlaube Nutzern, ihre Zustimmung später zu ändern Mellowtel bietet einen eingebauten Einstellungsdialog über `showConsentSettings(window)`. Es rendert einen nativen Dialog mit Opt-In / Opt-Out-Buttons, die dem aktuellen Status des Nutzers entsprechen, und ruft intern `optIn()` oder `optOut()` auf (plus erneute Verbindung des WebSockets bei Opt-In), wenn der Nutzer umschaltet. Verknüpfe es mit einem Menüpunkt oder Einstellungsbutton in deiner App, damit Nutzer ihre Wahl erneut überprüfen können. Wenn du lieber deinen eigenen Einstellungsbildschirm erstellen möchtest, rufe `getOptInStatus()` auf, um den aktuellen Status zu lesen, und `optIn()` / `optOut()`, um ihn zu ändern. *** ## Methodenreferenz Die `Mellowtel`-Klasse stellt die folgenden öffentlichen Methoden bereit. Alle sind auf der Instanz verfügbar, die du mit `new Mellowtel(configurationKey, options?)` erstellt hast. **Lebenszyklus** * `init(): Promise` startet den Dienst, wenn der Nutzer zugestimmt hat, oder kehrt stillschweigend frühzeitig zurück, wenn nicht. Wirft nur, wenn der Konfigurationsschlüssel leer ist. * `requestConsent(window: BrowserWindow, incentive: string): Promise` zeigt den eingebauten nativen Zustimmungsdialog an und speichert das Ergebnis. Gibt `true` bei Zustimmung, `false` bei Ablehnung oder Schließen, `undefined`, wenn die Zustimmung bereits gegeben wurde, zurück. * `showConsentSettings(window: BrowserWindow): Promise` zeigt den eingebauten Zustimmungsverwaltungsdialog an. Das SDK handhabt die Opt-In / Opt-Out-Übergänge intern, wenn der Nutzer seine Wahl umschaltet. **Manuelle Opt-In-Steuerung** * `optIn(): Promise` kennzeichnet den Nutzer als zugestimmt, ohne einen Dialog anzuzeigen. Verwende dies nur, nachdem du die Zustimmung über deine eigene UI eingeholt hast. * `optOut(): Promise` kennzeichnet den Nutzer als abgelehnt und schließt die aktive WebSocket-Verbindung. * `getOptInStatus(): boolean | undefined` gibt den aktuellen Opt-In-Status zurück, oder `undefined`, wenn der Nutzer noch keine Wahl getroffen hat. * `getNodeId(): string` gibt die Mellowtel-Knotenkennung für diese Installation zurück. Nützlich beim Einreichen von Support-Tickets. **Anforderungszähler** Anforderungszahlen werden lokal über `electron-store` gespeichert und überstehen App-Neustarts. Zeige sie in deiner eigenen UI an, wenn du den Nutzern die Auswirkungen ihres Opt-Ins zeigen möchtest. * `getTotalRequestCount(): number` gibt die Gesamtanzahl der seit der Installation verarbeiteten Anfragen zurück. * `getDailyRequestCount(): number` gibt die Anzahl der heute verarbeiteten Anfragen zurück. * `getRequestCountForDate(date: string): number` gibt die Anzahl für ein bestimmtes `YYYY-MM-DD`-Datum zurück. * `getDailyRequestsHistory(): { [date: string]: number }` gibt jede tägliche Anzahl als Karte zurück. * `getRequestCountsInRange(startDate: string, endDate: string): { [date: string]: number }` gibt die Anzahlen für einen Datumsbereich zurück. * `getRequestCounts(): { total: number; daily: number; dailyHistory: { [date: string]: number } }` gibt alle drei Zähler in einem Aufruf zurück. *** ## Herunterfahren und Lebenszyklus Das Electron SDK registriert **keine** eigenen `before-quit` oder `will-quit` Handler. Wenn dein Electron-Prozess beendet wird, wird die Hintergrund-WebSocket-Verbindung mit ihm abgebaut, und es ist keine explizite Bereinigung auf deiner Seite erforderlich. Wenn du Mellowtel mitten in einer Sitzung trennen möchtest (zum Beispiel, wenn ein Nutzer eine "Pause"-Einstellung in deiner App umschaltet), rufe `optOut()` auf. Dies löscht sowohl das Opt-In-Flag als auch die aktive Verbindung. Um die Verbindung wiederherzustellen, rufe `optIn()` gefolgt von `init()` auf. ## Einwilligungsspeicherung Der Opt-In-Status wird im plattformstandardmäßigen `electron-store`-Konfigurationspfad gespeichert: * macOS: `~/Library/Application Support//config.json` * Windows: `%APPDATA%\\config.json` * Linux: `~/.config//config.json` Der Status übersteht App-Updates. Das Deinstallieren deiner App wird ihn nicht automatisch löschen, es sei denn, dein Deinstallationsprogramm entfernt ausdrücklich das Konfigurationsverzeichnis der App. *** ## Fehlerbehebung 1. Überprüfe, ob `.npmrc` sich im Projektstamm befindet, neben deiner `package.json`. 2. Stelle sicher, dass das Token keine führenden oder nachgestellten Leerzeichen hat. 3. Leere den npm-Cache und versuche es erneut, indem du `npm cache clean --force` gefolgt von `npm install` ausführst. 1. Überprüfe, ob das Token in `.npmrc` korrekt und aktiv ist. Wenn du unsicher bist, fordere ein neues Token von [info@mellowtel.com](mailto:info@mellowtel.com) an. 2. Bestätige, dass die Zeile `@mellowtel-inc:registry` vorhanden ist und auf `https://npm.pkg.github.com/` verweist. 1. Stelle sicher, dass du `requestConsent` **nachdem** `app.whenReady()` aufgelöst wurde und mit einem gültigen, nicht zerstörten `BrowserWindow`-Verweis aufrufst. 2. Wenn du `setupMellowtelApp()` verwendest, überprüfe, ob es **vor** `app.whenReady()` aufgerufen wird, nicht danach. Dies ist beabsichtigt. `init()` kehrt stillschweigend frühzeitig zurück, wenn der Nutzer nicht zugestimmt hat. Überprüfe `getOptInStatus()`, um dies zu bestätigen. Wenn es `undefined` oder `false` zurückgibt, führe zuerst `requestConsent` aus. Beachte, dass das interne "Nutzer hat nicht zugestimmt" Protokoll unterdrückt wird, wenn `disableLogs` auf seinem Standardwert belassen wird (siehe "Protokolle sind still" unten), sodass das Terminal dir kein Signal in die eine oder andere Richtung gibt, bis du dieses Flag umschaltest. Die `disableLogs` Konstruktoroption ist standardmäßig auf `true` gesetzt. Übergebe `{ disableLogs: false }` als zweites Argument an den Konstruktor, während du integrierst, um den Verbindungsstatus und die Anforderungsaktivität in deinem Terminal anzuzeigen. Dies ist auch der schnellste Weg, um eine "nicht zugestimmt" stille No-Op (siehe oben) von einem echten Verbindungsfehler zu unterscheiden. *** Geschätzte Zeit zur Fertigstellung: 10-15 Minuten. Wenn du Hilfe benötigst oder Feedback hast, kontaktiere uns unter [info@mellowtel.com](mailto:info@mellowtel.com) oder tritt unserer [Discord-Community](https://discord.com/invite/txAZp4MSDe) bei.