Inicio rápido

De cero a un plugin funcionando en menos de 10 minutos usando el template oficial.

Prerrequisitos

• .NET 8 SDK — descargar en dotnet.microsoft.com
• PowerShell 5.1+ — incluido en Windows 10/11
• FocusTracker ≥ 1.4.0 instalado para probar localmente
• Cualquier editor: Visual Studio, VS Code + C# Dev Kit, o Rider

Pasos

1. Descargá el template
   Clona o descargá el template desde ESTE ENLACE. Tiene el SDK preconfigurado, el plugin.json y el script de build.
2. Editá tu identidad en plugin.json
   Cambiá id, name, version, author y description. El id nunca puede cambiar entre versiones.

   {
     "id":             "com.tudominio.mi-plugin",
     "name":           "Mi Plugin",
     "version":        "1.0.0",
     "author":         "Tu Nombre",
     "description":    "Una descripción corta (≤140 chars).",
     "minHostVersion": "1.4.0",
     "entryAssembly":  "MiPlugin.dll"
   }

3. Implementá IFocusPlugin
   Renombrá MyPlugin.cs y completá los cinco campos de identidad, el método GetUserHelp() (obligatorio) y tu lógica en Initialize / Shutdown. Ver la sección IFocusPlugin para la referencia completa.
4. Empaquetá con build.ps1
   Desde PowerShell en la raíz del template:

   .\build.ps1

   Genera dist/com.tudominio.mi-plugin-1.0.0.focusplugin.
5. Instalá y probá
   En FocusTracker → Plugins → Importar, seleccioná el .focusplugin. El plugin aparece al instante en Mis plugins. Si algo falla, revisá %APPDATA%\FocusTracker\crash.log.

Estructura del proyecto

Un plugin es una DLL de .NET 8 empaquetada en un ZIP con extensión .focusplugin.

Árbol de archivos del template

Contenido del paquete .focusplugin

Carpeta de extracción en el host

El host extrae cada plugin en %APPDATA%\FocusTracker\plugins\_extracted\{id}\. Esta carpeta se limpia y re-extrae cada vez que se instala una nueva versión, por lo que no necesitás hacer nada manual.

IFocusPlugin

Toda clase plugin debe implementar esta interfaz. El host la descubre por reflexión y requiere un constructor público sin parámetros.

public class MiPlugin : IFocusPlugin
{
    // ── Identidad ──────────────────────────────────────────────────
    public string Id          => "com.tudominio.mi-plugin";
    public string Name        => "Mi Plugin";
    public string Version     => "1.0.0";
    public string Author      => "Tu Nombre";
    public string Description => "Descripción corta (≤140 chars).";

    // ── Ayuda (OBLIGATORIO) ────────────────────────────────────────
    public PluginHelpContent GetUserHelp() => new()
    {
        Summary  = "Qué hace el plugin.",
        Sections = new[] { new PluginHelpSection { Heading = "Uso", Body = "..." } }
    };

    // ── Ciclo de vida ──────────────────────────────────────────────
    public void Initialize(IPluginContext context) { /* tu lógica */ }
    public void Shutdown() { /* cleanup */ }
}

Identidad

Documentación — obligatoria

Ciclo de vida

plugin.json

El host lee este archivo antes de abrir cualquier DLL. Si la validación falla, el paquete es rechazado sin ejecutar código.

{
  "id":             "com.tudominio.mi-plugin",
  "name":           "Mi Plugin",
  "version":        "1.0.0",
  "author":         "Tu Nombre",
  "description":    "Descripción corta (≤140 chars).",
  "minHostVersion": "1.4.0",
  "entryAssembly":  "MiPlugin.dll"
}

Campos

Versión consistente en los tres lugares

La versión del plugin debe estar sincronizada en:

• plugin.json → campo "version"
• MiPlugin.cs → propiedad Version => "1.0.0"
• MiPlugin.csproj → <Version>1.0.0</Version>

El script build.ps1 usa el version del plugin.json para nombrar el archivo de salida, así que si hay discrepancia el paquete generado tendrá un nombre inconsistente.

IPluginContext

El host entrega una instancia de IPluginContext en Initialize(). Todos los métodos son thread-safe; los callbacks de eventos se ejecutan en el hilo de UI.

Estado de tracking

Eventos

public void Initialize(IPluginContext context)
{
    _ctx = context;
    context.TrackingStarted += OnStart;
    context.TrackingStopped += OnStop;
    context.FocusChanged    += OnFocus;
}

public void Shutdown()
{
    if (_ctx is not null)
    {
        _ctx.TrackingStarted -= OnStart;
        _ctx.TrackingStopped -= OnStop;
        _ctx.FocusChanged    -= OnFocus;
    }
}

Lectura de sesiones

Lectura de uso y tiempo

Lectura de proyectos

Configuración del host

Escritura de proyectos

Escritura de sesiones y tracking

Modelos de datos

Botones y tarjetas

Un plugin puede agregar botones a cualquier pantalla del host y una tarjeta de datos a la pantalla de inicio.

Botones en pantallas

Los botones aparecen en una fila dedicada debajo de los controles nativos de cada pantalla.

context.RegisterButton(new PluginButtonContribution
{
    Screen       = PluginScreenTarget.Home,
    Label        = "Mi acción",
    Icon         = "\uE768",          // Segoe Fluent Icons — opcional
    Style        = PluginButtonStyle.Primary,
    OnClicked    = () => DoSomething(),
    // Visibilidad condicional — evaluada cada segundo
    GetIsVisible = () => context.IsTracking,
});

Pantallas disponibles (PluginScreenTarget)

Estilos de botón (PluginButtonStyle)

Tarjeta en Home

Una tarjeta es un widget de datos en la pantalla de inicio, con filas clave-valor y auto-refresco configurable.

context.RegisterHomeCard(new PluginCardContribution
{
    Title              = "Mi Plugin",
    Icon               = "\uE9D9",
    AutoRefreshSeconds = 5,  // 0 = estático
    GetRows            = BuildRows,
});

private IReadOnlyList<PluginCardRow> BuildRows() => new[]
{
    new PluginCardRow { Label = "Estado",    Value = "Activo"      },
    new PluginCardRow { Label = "DETALLES",  IsHeader = true  },
    new PluginCardRow { Label = "Restante", Value = "18:32"     },
};

Devolvé una lista vacía para que el host muestre el estado vacío por defecto. Las filas con IsHeader = true se renderizan en negrita y sin columna de valor, útiles para agrupar datos.

Ajustes en Settings

Tu plugin puede agregar items de configuración a la pantalla de Ajustes. El host crea automáticamente una pestaña con el nombre que indiques.

Tipos de control

Ejemplos

// Toggle
context.RegisterSetting(new PluginSettingDescriptor
{
    TabName         = "Mi Plugin",
    Title           = "Activar alertas",
    Description     = "Muestra una notificación al cambiar la app.",
    Type            = PluginSettingType.Toggle,
    ToggleDefault   = true,
    OnToggleChanged = v => { _config.Enabled = v; _config.Save(...); },
});

// Select
context.RegisterSetting(new PluginSettingDescriptor
{
    TabName            = "Mi Plugin",
    Title              = "Tipo de alerta",
    Type               = PluginSettingType.Select,
    SelectOptions      = new[] { "Sonido", "Visual", "Ambos" },
    SelectDefaultIndex = 2,
    OnSelectChanged    = v => _config.Mode = v,
});

// TextInput
context.RegisterSetting(new PluginSettingDescriptor
{
    TabName         = "Mi Plugin",
    Title           = "Prefijo",
    Type            = PluginSettingType.TextInput,
    TextPlaceholder = "ej: 🔍 Ahora:",
    TextDefault     = _config.Prefix,
    OnTextCommitted = v => _config.Prefix = v,
});

// Botón peligroso
context.RegisterSetting(new PluginSettingDescriptor
{
    TabName         = "Mi Plugin",
    Title           = "Resetear datos",
    Type            = PluginSettingType.Button,
    ButtonLabel     = "Eliminar todo",
    ButtonIsDanger  = true,
    OnButtonClicked = () => ResetAll(),
});

Notificaciones y sonido

El host ofrece cuatro variantes para notificar al usuario. Todas se muestran como toasts en la esquina de la pantalla, con el diseño visual de FocusTracker.

Métodos disponibles

// Toast simple
_ctx.ShowNotification("¡Hecho!", "La tarea se completó.");

// Toast con botones de decisión
_ctx.ShowPersistentNotification(
    "¿Tomás un descanso?",
    "Completaste 25 minutos de trabajo.",
    PluginToastKind.Success,
    new[]
    {
        new PluginToastAction { Label = "Descanso",    OnClicked = StartBreak   },
        new PluginToastAction { Label = "Seguir",      OnClicked = ContinueWork },
        new PluginToastAction { Label = "+ 5 min",    OnClicked = AddFiveMin   },
    });

Tipos de toast (PluginToastKind)

Sonidos disponibles (WindowsSystemSound)

Pantalla de ayuda

Todos los plugins deben implementar GetUserHelp(). El contenido se muestra en Plugins → Mis plugins → Ayuda, para que los usuarios entiendan cómo usar tu plugin sin salir de la app.

public PluginHelpContent GetUserHelp() => new()
{
    Summary =
        "Un párrafo que explique claramente qué hace el plugin " +
        "y cuál es el beneficio principal para el usuario.",

    Sections = new[]
    {
        new PluginHelpSection
        {
            Heading = "Primeros pasos",
            Body    = "Qué debe hacer el usuario para empezar."
        },
        new PluginHelpSection
        {
            Heading = "Configuración",
            Body    = "Descripción de cada ajuste disponible en Settings."
        },
        // Agregar tantas secciones como sean necesarias.
    }
};

Reglas

• Summary requerido — no puede ser null ni estar vacío. Al menos una oración.
• Método puro y sin estado — se llama antes de Initialize(). No uses campos privados ni accedas a _ctx.
• Sin límite de secciones — agregá las que necesités. Una sola es válida.
• Solo texto plano — el Body no soporta markdown ni HTML.

Persistir configuración

El template incluye PluginConfig — un patrón simple de serialización JSON. Usalo directamente o adaptalo con tus propios campos.

// PluginConfig.cs
public class PluginConfig
{
    public bool   EnableAlerts { get; set; } = true;
    public string Prefix       { get; set; } = "";

    public static PluginConfig Load(string folder, string pluginId)
    {
        var path = Path.Combine(folder, $"plugin_{pluginId}.json");
        if (!File.Exists(path)) return new();
        try { return JsonSerializer.Deserialize<PluginConfig>(File.ReadAllText(path)) ?? new(); }
        catch { return new(); }
    }

    public void Save(string folder, string pluginId) =>
        File.WriteAllText(
            Path.Combine(folder, $"plugin_{pluginId}.json"),
            JsonSerializer.Serialize(this, new JsonSerializerOptions { WriteIndented = true }));
}

Uso en Initialize()

private IPluginContext? _ctx;
private PluginConfig    _config = new();

public void Initialize(IPluginContext context)
{
    _ctx    = context;
    _config = PluginConfig.Load(context.GetDataFolder(), Id);

    context.RegisterSetting(new PluginSettingDescriptor {
        ToggleDefault   = _config.EnableAlerts,
        OnToggleChanged = v => {
            _config.EnableAlerts = v;
            _config.Save(context.GetDataFolder(), Id);
        },
        // ...
    });
}

Empaquetar el plugin

El script build.ps1 compila, empaqueta y genera el .focusplugin listo para distribuir en un solo comando.

Uso

# Release (por defecto)
.\build.ps1

# Debug — incluye símbolos para depurar
.\build.ps1 -Configuration Debug

# Sin pausa al terminar — ideal para CI/CD
.\build.ps1 -NoPause

El archivo de salida se genera en dist/{id}-{version}.focusplugin.

Qué hace el script

1. Compila el SDK en el modo indicado.
2. Compila tu plugin referenciando el SDK.
3. Empaqueta: copia el DLL del plugin, plugin.json y tus dependencias propias (excluye SDK, Microsoft.* y System.*) en un ZIP renombrado a .focusplugin.

Instalar para probar

En FocusTracker → Plugins → Importar, seleccioná el .focusplugin generado. El plugin aparece inmediatamente en Mis plugins. Si algo falla, revisá:

%APPDATA%\FocusTracker\crash.log

Checklist final

Antes de compartir o publicar tu plugin, verificá cada punto de esta lista.

1. Id único y permanente
   Tu Id en código coincide exactamente con el id en plugin.json. Usás reverse-DNS. Solo letras, dígitos, puntos, guiones y guiones bajos.
2. Versión consistente en los tres archivos
   Version en código = version en plugin.json = <Version> en el .csproj.
3. Description ≤ 140 caracteres
   Tanto el campo Description en código como el description en plugin.json.
4. GetUserHelp() implementado y completo
   Summary no vacío. Al menos una sección explicando cómo usar el plugin. Sin dependencia de estado.
5. Shutdown() desuscribe todos los eventos
   Cada += tiene su -= correspondiente. Probalo desactivando el plugin desde Mis plugins y volviéndolo a activar.
6. Thread safety
   Si usás System.Timers.Timer u otros threads, el estado mutable está protegido con lock.
7. SDK excluido del paquete
   Verificá que FocusTracker.PluginSDK.dll no esté dentro del .focusplugin.
8. Probado localmente
   Instalado vía Importar, activado, desactivado y vuelto a activar sin errores en %APPDATA%\FocusTracker\crash.log.

Marketplace de plugins

Distribuí tu plugin a todos los usuarios de FocusTracker directamente desde la pantalla de Plugins de la app.

Lo que se viene

• Portal de desarrolladores para subir y gestionar tus plugins.
• Proceso de revisión para garantizar calidad y seguridad antes de publicar.
• Modelos de monetización: gratuito, donación, compra única y suscripción mensual/anual.
• Panel de analytics con instalaciones, ratings y retención.
• Actualizaciones automáticas: los usuarios son notificados cuando publiques una nueva versión.

Mientras tanto

Podés compartir tu .focusplugin directamente — se instala desde Plugins → Importar con un click. Si querés ser de los primeros en publicar cuando el marketplace abra, o tenés preguntas sobre el SDK, escribime a hola@santiagorada.com.