Widget personalizzati

I widget personalizzati saranno disponibili a partire da SKOOR 10.0.0.

I widget personalizzati estendono l'ecosistema di visualizzazione SKOOR consentendo agli sviluppatori di creare componenti UI interattivi e su misura che vengono eseguiti in modo sicuro all'interno delle dashboard SKOOR. Combinano la flessibilità dei moderni framework web (come React o Vue, o il semplice Vanilla JS) con moderni strumenti di build (come Vite o Webpack), insieme alle pipeline di dati governate e ai rigorosi standard di sicurezza di SKOOR.

Guida rapida

Per utilizzare i widget personalizzati, sono necessarie le credenziali di SKOOR Registry. Contattare support@skoor.com per richiederle.

Utilizzare il pacchetto @skoor/create-custom-widget per generare la struttura di base di un nuovo progetto di widget personalizzato SKOOR con la struttura e le dipendenze consigliate.

  1. Aprire la pagina del pacchetto: https://www.npmjs.com/package/@skoor/create-custom-widget

  2. Creare la struttura del progetto widget: seguire le istruzioni del pacchetto per creare un nuovo workspace per il widget personalizzato.

  3. Compilare, testare e pubblicare: implementare il widget, validarlo in locale, quindi pubblicarlo nello SKOOR Package Registry nell'ambito dello scope cliente assegnato.

Come funzionano i widget personalizzati

skoor-custom-widget-architecture.svg

I widget personalizzati operano come pacchetti isolati e autonomi, distribuiti e gestiti tramite lo SKOOR Package Registry centralizzato (registry.skoor.com).

  • Entry point (main): ogni pacchetto widget definisce un file HTML come proprio entry point main in package.json. Tutte le risorse statiche necessarie (script, stili, immagini) vengono caricate direttamente dal registry.

  • Esecuzione isolata: i widget vengono eseguiti all'interno di IFRAME isolati tramite un'origine dedicata e una Content Security Policy (CSP) restrittiva. Ciò garantisce la separazione dei tenant, la sicurezza e rigorosi controlli dei confini.

  • Metodi di creazione: i widget personalizzati possono essere sviluppati manualmente dagli ingegneri utilizzando qualsiasi moderno flusso di lavoro di sviluppo locale (ad esempio Vite, Webpack o Vanilla JS) oppure generati tramite IA per creare rapidamente la struttura iniziale di dashboard e componenti funzionali.

Struttura del pacchetto e query di dati

Per rimanere completamente portatili e sotto controllo di versione, i widget personalizzati includono le definizioni dei dati necessarie direttamente all'interno del pacchetto, sotto il blocco di configurazione skoor:

  • Query incluse nel pacchetto: i pacchetti includono le query di database necessarie sotto la proprietà skoor.dataQueryPackage, che punta a un file JSON di query esportato. Utilizzare lo strumento di esportazione del server MCP di SKOOR per esportare un gruppo di query dedicato; l'esportazione include automaticamente le dipendenze necessarie.

  • Dashboard Bridge (@skoor/dashboard-bridge): i widget comunicano con la piattaforma core SKOOR esclusivamente tramite la libreria ufficiale @skoor/dashboard-bridge. Questo bridge astrae la comunicazione asincrona (tramite postMessage e Penpal), consentendo ai widget di:

    • Recuperare i dati dinamicamente utilizzando dataQuerySelect(...) o dataSourceSelect(...).

    • Leggere e aggiornare i filtri globali della dashboard (getFilters(), setFilters(...)).

    • Sincronizzare automaticamente lo stile dell'host, le variabili del tema, le famiglie di caratteri e l'altezza dei contenuti tramite setup().

Esempio di configurazione package.json per un widget personalizzato (pubblicato sotto uno scope cliente, ad es. @customer-scope/custom-metric-widget):

{
  "name": "@customer-scope/custom-metric-widget",
  "version": "1.0.0",
  "main": "dist/index.html",
  "skoor": {
    "dataQueryPackage": "./data/data-queries.json"
  }
}

Sviluppo, integrazione del server MCP e pubblicazione

Per sviluppare e pubblicare widget personalizzati in modo efficiente, è possibile connettere gli assistenti di codifica IA direttamente alla propria istanza SKOOR utilizzando il server Model Context Protocol (MCP) integrato.

Utilizzo del server MCP di SKOOR (recupero, creazione, aggiornamento, esportazione)

Il server MCP di SKOOR consente ai client LLM esterni (come Cursor o Cline) di recuperare, creare, modificare ed esportare definizioni di tabelle e query di dati direttamente dalla propria istanza SKOOR:

  • Recupero: interrogare schemi di database, strutture di tabelle e definizioni di query di dati esistenti per comprendere i modelli di dati disponibili.

  • Creazione: generare automaticamente nuove query di dati e strutturare le definizioni dei widget in base alle proprie specifiche esatte.

  • Aggiornamento / Modifica: perfezionare in modo iterativo le query, regolare le aggregazioni o modificare i parametri direttamente all'interno dell'ambiente di sviluppo con validazione completa dello schema.

  • Esportazione: esportare i pacchetti di query di dati in formato JSON utilizzando lo strumento di esportazione del server MCP. Inserire le query specifiche del widget in un gruppo dedicato ed esportare tale gruppo; l'esportazione includerà automaticamente le dipendenze necessarie.

Configurare il client MCP (ad esempio nelle impostazioni del progetto o globali) utilizzando il seguente modello di configurazione HTTP:

{
  "servers": {
    "skoor-mcp": {
      "type": "http",
      "url": "https://<your-skoor-instance>/skoor-webservice/mcp",
      "headers": {
        "Authorization": "Basic <your-base64-encoded-credentials>"
      }
    }
  },
  "inputs": []
}

Configurazione del registry e pubblicazione

  1. Configurare il registry: creare un file .npmrc nella directory principale del progetto con l'endpoint del registry privato SKOOR:

    registry=https://registry.skoor.com
  2. Autenticarsi: accedere al registry utilizzando le credenziali fornite da SKOOR:

    npm login --registry=https://registry.skoor.com
  3. Scope cliente: i pacchetti devono sempre essere pubblicati nello scope cliente assegnato (ad es. @customer-scope/my-widget).

Sicurezza, restrizioni di rete e CSP

Per proteggere la sovranità dei dati aziendali e prevenire fughe di dati non autorizzate verso terze parti, SKOOR applica rigorose policy di sicurezza sui widget personalizzati:

  • Isolamento predefinito: la comunicazione di rete esterna dall'interno di un widget è severamente vietata e bloccata per impostazione predefinita tramite una Content Security Policy (CSP) conservativa.

  • Eccezioni CSP: se un widget richiede esplicitamente la comunicazione con endpoint esterni (come API pubbliche o repository di terze parti), è possibile dichiarare eccezioni nella sezione skoor.csp in package.json:

{
  "skoor": {
    "csp": {
      "connect-src": [
        "https://api.external-service.com"
      ]
    }
  }
}
  • Conferma dell'utente: quando un widget richiede origini di rete aggiuntive tramite la propria configurazione CSP, la piattaforma mostra agli amministratori o agli utenti una finestra di dialogo di conferma per autorizzare esplicitamente l'accesso ai dati in uscita.

Ciclo di vita: installazione e distribuzione nella dashboard

La distribuzione e l'utilizzo di un widget personalizzato seguono un ciclo di vita amministrativo e operativo lineare:

  1. Pubblicazione: gli sviluppatori compilano e pubblicano il pacchetto con controllo di versione nello SKOOR Package Registry privato (registry.skoor.com).

  2. Installazione: gli amministratori accedono a SKOOR Settings, individuano la sezione di gestione Custom Widgets e installano il pacchetto desiderato dal registry privato.

  3. Integrazione nella dashboard: una volta installato, il widget personalizzato diventa disponibile nel WYSIWYG Dashboard Builder, dove gli utenti possono posizionarlo sulle dashboard, configurarne i parametri di visualizzazione e collegarlo ai filtri globali della dashboard.