Configuration via Plugins

Owncast offre ai plugin due modi per consentire a un admin di cambiare le impostazioni. Dichiara un blocco config nel manifest e Owncast rende un modulo digitato per te, senza HTML per admin e senza codice per salvare o caricare da scrivere. Oppure registra una pagina admin e fornisci il tuo HTML.

Usa il blocco config del manifest per controlli piatti e digitati: stringhe, numeri e interruttori. Raggiungi una pagina admin personalizzata solo quando hai bisogno di un'interfaccia utente che il modulo automatico non può esprimere, come un layout raggruppato, un'anteprima dal vivo o un pulsante di azione che chiama la tua API. I due possono coesistere. Un plugin può avere sia la scheda Impostazioni del modulo automatico sia una o più pagine admin personalizzate.

Dichiara le impostazioni nel manifest

Ogni voce sotto config ha un tipo, un predefinito e una descrizione:

{
  "config": {
    "greeting": { "type": "string", "default": "welcome!", "description": "First-join message" },
    "cooldownMs": { "type": "number", "default": 2000, "description": "Per-user command cooldown" },
    "modOnly": { "type": "boolean", "default": false, "description": "Restrict to moderators" }
  }
}

Campo	Note
tipo	Uno tra stringa, numero, o booleano. Qualsiasi altro valore è accettato ma ottiene un input di testo semplice e nessun controllo di tipo al salvataggio.
predefinito	Il valore restituito da config.get fino a quando un admin salva un override. Il suo tipo JSON dovrebbe corrispondere a tipo.
descrizione	L'etichetta visualizzata accanto al campo nel modulo admin. Torna al nome della chiave quando è vuota.

I nomi delle chiavi non possono iniziare con __. Quella prefisso è riservato per il stato per istanza che l'host inietta, e un plugin che dichiara una chiave come __internal non riesce a caricarsi.

Cosa vede l'admin

Un plugin che dichiara un blocco config ottiene una scheda Impostazioni nella sua pagina di dettaglio sotto Admin → Plugin. Owncast costruisce il modulo dallo schema:

• string rende un input di testo, number un input numerico, e boolean un interruttore.
• La descrizione è l'etichetta del campo.
• Il predefinito si mostra fino a quando un admin salva un override.
• Una chiave il cui nome somiglia a una credenziale viene visualizzata come un input di password mascherato. La corrispondenza è case-insensitive e si attiva quando il nome contiene secret, password, token, apikey, o api_key, o è la parola isolata key. Così apiKey, clientSecret, accessToken, e webhook_secret vengono mascherati. Nomi come accessKey o keyValue non vengono mascherati, poiché key corrisponde solo come una parola intera. Dai a un campo segreto apiKey, api_key, o qualsiasi cosa che finisce in Secret o Token se vuoi che sia mascherato.

Un plugin senza blocco config non mostra la scheda Impostazioni.

Leggi i valori a runtime

owncast.config.get(key, fallback?) restituisce l'override dell'admin quando uno è impostato, altrimenti il predefinito dichiarato, già analizzato nel tipo dichiarato.

JavaScript

const cooldownMs = owncast.config.get('cooldownMs', 2000);
const modOnly = owncast.config.get('modOnly', false);

Python

cooldown_ms = owncast.config.get("cooldownMs", 2000)
mod_only = owncast.config.get("modOnly", False)

config.get è ambient, quindi non richiede permessi. Un campo number torna come un numero e un boolean come un bool, quindi non analizzare le stringhe tu stesso. Per una chiave sconosciuta, o una chiave dichiarata che non ha né un predefinito né un override salvato, restituisce fallback (undefined in JavaScript e None in Python quando passi none). Passa un fallback che puoi utilizzare.

La firma completa vive nella riferimento API.

Validazione e archiviazione

Quando un admin salva il modulo, Owncast verifica ogni valore secondo lo schema prima di archiviarlo:

• Una chiave non dichiarata nel manifest viene rifiutata con 400 chiave di configurazione sconosciuta.
• Un campo string deve ricevere una stringa, un number un numero, e un boolean un bool. Un mismatch di tipo viene rifiutato. Qualsiasi altro tipo dichiarato viene memorizzato così com'è.
• Il corpo della richiesta è limitato a 1 MB.

Gli override persistono nel negozio chiave/valore del plugin sotto la chiave riservata owncast.config, namespaced dallo slug del plugin. Altri plugin non possono leggerli, e sopravvivono ai riavvii e alle reinstallazioni. Modificare lo slug dopo il rilascio inizia un nuovo negozio, quindi gli override salvati tornano ai loro predefiniti, la stessa regola che si applica al resto dei tuoi dati KV.