Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mellowtel.com/llms.txt

Use this file to discover all available pages before exploring further.

Integra Mellowtel en tu aplicación multiplataforma Electron para permitir que los usuarios compartan su ancho de banda de internet no utilizado a cambio de recompensas o características premium. El SDK de Electron funciona en cualquier lugar donde se ejecute Electron (macOS, Windows y Linux).
El consentimiento del usuario es obligatorio. El SDK solo opera cuando el usuario ha optado explícitamente. init() retorna silenciosamente temprano cuando no hay consentimiento registrado, así que si ves que el SDK se inicia sin errores pero nunca envía tráfico, la razón más probable es que el usuario aún no ha optado.

​
Requisitos previos

  • Una cuenta de Mellowtel y clave de configuración (obtén la tuya desde el panel de control).
  • Una aplicación Electron con acceso al proceso principal.

​
Instalación

​
1. Configura la autenticación de npm

Crea un archivo .npmrc en el directorio raíz de tu proyecto para apuntar npm al registro de paquetes de GitHub de Mellowtel y autenticar la instalación: 
@mellowtel-inc:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN
Reemplaza YOUR_NPM_TOKEN con el token de instalación a continuación. Haz clic para revelar, luego usa el icono de copiar en el bloque de código para copiarlo al portapapeles. 
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

​
2. Instala el paquete

Desde la raíz de tu proyecto, instala el SDK de Electron: 
npm install @mellowtel-inc/mellowtel-electron

​
3. Añádelo a tu código

En tu archivo de proceso principal de Electron (típicamente main.ts o main.js), importa el SDK, instáncialo con tu clave de configuración, solicita el consentimiento del usuario y luego llama a init() para iniciar el servicio. 
import { app, BrowserWindow } from 'electron';
import Mellowtel from '@mellowtel-inc/mellowtel-electron';


// Cuando la aplicación esté lista, crea la ventana
app.whenReady().then(async () => {
  let win = createWindow();
  
  const mellowtel: Mellowtel = new Mellowtel('YOUR_CONFIGURATION_KEY');

  await mellowtel.requestConsent(win, "Obtén 3 meses gratis")
  await mellowtel.init()
});
Reemplaza YOUR_CONFIGURATION_KEY con la clave de tu panel de control de Mellowtel.
Qué hace cada llamada:
  • new Mellowtel(configurationKey, options?) instancia el SDK. La única opción disponible hoy es disableLogs, que por defecto es true. Establécelo en false mientras integras para que puedas ver el estado de conexión y la actividad de solicitudes en tu terminal.
  • requestConsent(window, incentive) muestra un cuadro de mensaje nativo de Electron anclado a la BrowserWindow que pasas. El segundo argumento es el titular destacado del diálogo (por ejemplo, "Obtén 3 meses gratis"), mostrado sobre una explicación fija de lo que hace Mellowtel. Resuelve a true si el usuario acepta, false si el usuario rechaza o cierra el diálogo, y undefined si el consentimiento ya está registrado. El SDK persiste automáticamente la decisión de optar, por lo que no necesitas llamar a optIn() después.
  • init() solo lanza un error cuando configurationKey está vacío. Si el usuario no ha optado, registra y retorna silenciosamente. De lo contrario, abre un WebSocket al backend de Mellowtel. La llamada no bloquea la UI del renderizador, por lo que las ventanas permanecen receptivas mientras se establece la conexión.

​
Prevenir interrupciones de diálogos del sistema (recomendado)

El SDK viene con un ayudante opcional, setupMellowtelApp(), que configura las banderas de línea de comandos de Electron para suprimir diálogos del sistema (ventanas emergentes de autocompletar, barras de traducción, solicitudes de autenticación NTLM / Kerberos, integración con gestores de contraseñas, superposiciones de medios, diálogos de primera ejecución) que de otro modo interrumpirían a tus usuarios cuando las ventanas ocultas de Mellowtel procesan solicitudes en segundo plano. Llámalo al principio de tu archivo de proceso principal, antes de app.whenReady(), e impórtalo junto con la exportación predeterminada de @mellowtel-inc/mellowtel-electron. Consulta el README original para el uso canónico.

​
Consentimiento del Usuario

Mostrar un diálogo de consentimiento es obligatorio. Debes permitir que los usuarios opten explícitamente antes de llamar a init(), y debes proporcionar una forma para que gestionen su estado de opt-in en cualquier momento.
Tienes dos caminos para manejar el consentimiento:
  1. Usa el diálogo nativo incorporado a través de requestConsent(window, incentive). Este es el camino más rápido y es lo que muestra el fragmento anterior. Renderiza un dialog.showMessageBox nativo de Electron con tu copia de incentivo como el titular y persiste automáticamente la decisión del usuario.
  2. Construye tu propia interfaz de consentimiento y maneja el SDK a través de optIn(), optOut(), y getOptInStatus(). Usa esto si deseas personalización de marca, explicaciones más ricas o localización más allá de lo que ofrece el diálogo nativo.

​
Qué debe incluir tu diálogo de consentimiento

1

Explica qué hace Mellowtel

Usa un lenguaje sencillo. Ejemplo: “Esta aplicación usa Mellowtel para compartir tu ancho de banda de internet no utilizado. A cambio, obtienes [beneficio/característica]. Puedes optar por no participar en cualquier momento en la configuración.”
2

Da a los usuarios una elección clara

Incluye opciones distintas de Aceptar y Rechazar.
3

Enlaza a las políticas

Incluye enlaces a los Términos de Servicio y la Política de Privacidad.

​
Permitir que los usuarios cambien su consentimiento más tarde

Mellowtel proporciona un diálogo de configuración incorporado a través de showConsentSettings(window). Renderiza un diálogo nativo con botones de Opt In / Opt Out que coinciden con el estado actual del usuario, y llama internamente a optIn() o optOut() (además de reconectar el WebSocket al optar) cuando el usuario cambia su elección. Conéctalo a un elemento de menú o botón de configuración en tu aplicación para que los usuarios puedan revisar su elección. Si prefieres construir tu propia pantalla de configuración, llama a getOptInStatus() para leer el estado actual y optIn() / optOut() para cambiarlo.

​
Referencia de Métodos

La clase Mellowtel expone los siguientes métodos públicos. Todos están disponibles en la instancia que creaste con new Mellowtel(configurationKey, options?). Ciclo de vida
  • init(): Promise<void> inicia el servicio si el usuario ha optado, o retorna silenciosamente temprano si no. Solo lanza un error cuando la clave de configuración está vacía.
  • requestConsent(window: BrowserWindow, incentive: string): Promise<boolean | undefined> muestra el diálogo de consentimiento nativo incorporado y persiste el resultado. Retorna true al aceptar, false al rechazar o cerrar, undefined si ya se había dado consentimiento.
  • showConsentSettings(window: BrowserWindow): Promise<void> muestra el diálogo de gestión de consentimiento incorporado. El SDK maneja las transiciones de opt-in / opt-out internamente cuando el usuario cambia su elección.
Control manual de opt-in
  • optIn(): Promise<void> marca al usuario como optado sin mostrar un diálogo. Usa esto solo después de recopilar el consentimiento a través de tu propia interfaz.
  • optOut(): Promise<void> marca al usuario como no optado y cierra la conexión WebSocket activa.
  • getOptInStatus(): boolean | undefined retorna el estado actual de opt-in, o undefined si el usuario nunca ha tomado una decisión.
  • getNodeId(): string retorna el identificador de nodo de Mellowtel para esta instalación. Útil al presentar tickets de soporte.
Contadores de solicitudes Los conteos de solicitudes se persisten localmente a través de electron-store y sobreviven a los reinicios de la aplicación. Muéstralos en tu propia interfaz si deseas mostrar a los usuarios el impacto de su opt-in.
  • getTotalRequestCount(): number retorna el total de solicitudes procesadas desde la instalación.
  • getDailyRequestCount(): number retorna el número de solicitudes procesadas hoy.
  • getRequestCountForDate(date: string): number retorna el conteo para una fecha específica YYYY-MM-DD.
  • getDailyRequestsHistory(): { [date: string]: number } retorna cada conteo diario como un mapa.
  • getRequestCountsInRange(startDate: string, endDate: string): { [date: string]: number } retorna los conteos para un rango de fechas.
  • getRequestCounts(): { total: number; daily: number; dailyHistory: { [date: string]: number } } retorna los tres contadores en una sola llamada.

​
Apagado y Ciclo de Vida

El SDK de Electron no registra sus propios manejadores de before-quit o will-quit. Cuando tu proceso de Electron sale, la conexión WebSocket de fondo se cierra con él, y no se requiere limpieza explícita de tu parte. Si deseas desconectar Mellowtel a mitad de sesión (por ejemplo, cuando un usuario cambia una configuración de “pausa” en tu aplicación), llama a optOut(). Esto tanto limpia la bandera de opt-in como cierra la conexión activa. Para reconectar, llama a optIn() seguido de init().

​
Persistencia del Consentimiento

El estado de opt-in se almacena en la ruta de configuración predeterminada de electron-store de la plataforma:
  • macOS: ~/Library/Application Support/<YourAppName>/config.json
  • Windows: %APPDATA%\<YourAppName>\config.json
  • Linux: ~/.config/<YourAppName>/config.json
El estado sobrevive a las actualizaciones de la aplicación. Desinstalar tu aplicación no lo limpiará automáticamente a menos que tu desinstalador elimine explícitamente el directorio de configuración de la aplicación.

​
Solución de Problemas

  1. Verifica que .npmrc esté en la raíz del proyecto, junto a tu package.json.
  2. Asegúrate de que el token no tenga espacios en blanco al principio o al final.
  3. Limpia la caché de npm y vuelve a intentar ejecutando npm cache clean --force seguido de npm install.
  1. Verifica que el token en .npmrc sea correcto y esté activo. Si no estás seguro, solicita un nuevo token a info@mellowtel.com.
  2. Confirma que la línea @mellowtel-inc:registry esté presente y apunte a https://npm.pkg.github.com/.
  1. Asegúrate de llamar a requestConsent después de que app.whenReady() se haya resuelto y con una referencia válida y no destruida de BrowserWindow.
  2. Si usas setupMellowtelApp(), verifica que se llame antes de app.whenReady(), no después.
Esto es por diseño. init() retorna silenciosamente temprano cuando el usuario no ha optado. Verifica getOptInStatus() para confirmar. Si retorna undefined o false, ejecuta requestConsent primero. Ten en cuenta que el registro interno “El usuario no ha optado” se omite cuando disableLogs se deja en su valor predeterminado (ver “Los registros están en silencio” a continuación), por lo que el terminal no te da señal de ninguna manera hasta que cambies esa bandera.
La opción de constructor disableLogs por defecto es true. Pasa { disableLogs: false } como el segundo argumento al constructor mientras integras para mostrar el estado de conexión y la actividad de solicitudes en tu terminal. Esta es también la forma más rápida de distinguir una operación silenciosa “no optada” (ver arriba) de una falla real de conexión.
Tiempo estimado para completar: 10-15 minutos. Si necesitas ayuda o tienes comentarios, contáctanos en info@mellowtel.com o únete a nuestra comunidad de Discord.