Vai al contenuto principale

Guida rapida al plugin

The quickest way to build a plugin is with the JavaScript or Python SDK. Pick a tab below and follow it through installation. To use Rust, TinyGo, AssemblyScript, Zig, or another compiled language instead, see Native WebAssembly.

Prerequisiti​

  • Un server Owncast che puoi amministrare, versione 0.3.0 o superiore.
  • Node.js 18 o superiore (node --version per controllare) per il toolchain @owncast/plugin-sdk.

1. Crea un nuovo plugin​

L'identificatore di un plugin è il suo slug: lettere minuscole, numeri e trattini, che inizia con una lettera. Viene usato come nome della directory, nome del file di output e prefisso dell'URL.

Crea un progetto con create-owncast-plugin, passando lo slug:

npx create-owncast-plugin@latest my-plugin
cd my-plugin
npm install

Ora hai:

my-plugin/
├── package.json
├── plugin.manifest.json     display name, slug, version, permissions
├── README.md                how to build, test, package, and install it
├── INSTRUCTIONS.md          optional, rendered as a tab in the admin
├── AGENTS.md                notes for AI coding agents
├── .agents/                 a bundled skill for AI coding agents
├── src/
│   └── plugin.js            your code, with a sample handler
└── __tests__/
    └── plugin.test.js       a sample scenario test

npm install crea anche node_modules/. Nessuno di questi è creato per te, ma puoi aggiungere un icon.png (mostrato nell'elenco dei plugin dell'amministrazione), una directory public/ (file statici serviti a /plugins/my-plugin/), e una directory assets/ (file che l'host incorpora per i campi di manifest).

Il manifest ha sia un nome visualizzato leggibile dall'uomo ("name": "My Plugin") che uno slug ("slug": "my-plugin"). Il nome visualizzato è quello che gli amministratori vedono nelle liste. Lo slug è l'identificatore canonico. Vedi il riferimento al manifest per le regole.

2. Scrivi del codice​

Un gestore reagisce a un evento. L'SDK deriva l'elenco delle sottoscrizioni del manifest dai gestori che definisci, quindi non c'è nient'altro da tenere sincronizzato. Ecco un echo bot:

Apri src/plugin.js:

const { definePlugin, owncast } = require('@owncast/plugin-sdk');

module.exports = definePlugin({
  onChatMessage(msg) {
    owncast.chat.send(`echo: ${msg.body}`);
  },
});

Vedi il riferimento ai gestori per tutto ciò a cui puoi collegarti, e il riferimento alle API per ogni metodo owncast.*.

3. Costruisci il plugin​

Questo produce my-plugin.ocpkg nella radice del tuo progetto: un file singolo contenente il tuo manifest, il plugin compilato e i contenuti di public/ e assets/. Il .ocpkg è il formato di distribuzione: quel file singolo è tutto ciò di cui un amministratore ha bisogno.

npm run package

4. Esegui i test​

Ogni scenario genera eventi attraverso il vero runtime del plugin con effetti collaterali simulati, quindi un test superato significa lo stesso comportamento in produzione. Vedi la guida ai test per il modello di dati completo.

npm test

5. (Opzionale) itera contro un server di sviluppo locale​

Serve il plugin a http://localhost:8080/plugins/my-plugin/ per curling gli endpoint, aprendo pagine statiche in un browser, o attivando i gestori di eventi attraverso gli endpoint helper /_dev/ (ad esempio POST /_dev/chat). Riavvia il server di sviluppo quando cambi il tuo codice.

npm run serve

6. Installa sul tuo server​

Nell'amministrazione di Owncast, apri Plugin nella barra laterale e fai clic su Carica plugin. Scegli il file my-plugin.ocpkg prodotto dalla tua build. Il plugin appare immediatamente nell'elenco. Attiva Abilitato per caricarlo.

La pagina Plugin nell'amministrazione, che elenca i plugin installati con i loro permessi richiesti, stato, un toggle di abilitazione e i pulsanti Carica plugin e Configura

In alternativa, copia my-plugin.ocpkg nella directory data/plugins/ del tuo server e il prossimo ciclo di scansione lo prenderà:

scp my-plugin.ocpkg user@your-owncast-server:/path/to/owncast/data/plugins/

Se il plugin dichiara permessi, l'amministratore li esamina nella scheda Permessi nella pagina di dettaglio del plugin prima di abilitarlo. Il primo abilitazione cattura l'insieme di permessi approvati. If you later ship an update that asks for more access, the already-approved version keeps running with its existing permissions while the update waits as pending until the admin re-approves.

La scheda Permessi sulla pagina di dettaglio di un plugin, che elenca ogni permesso richiesto con una descrizione in linguaggio semplice

Cosa leggere dopo​

Quando le cose vanno male​

  • Il plugin non appare nell'elenco degli amministratori. Assicurati che il .ocpkg sia in data/plugins/, non solo in plugins/, e che il nome del file termini con .ocpkg. La pagina Plugin dell'amministratore ha un pulsante Aggiorna se non vuoi aspettare il prossimo ciclo di scansione.
  • Il plugin appare ma non si abilita. Controlla la vista di dettaglio del plugin dell'amministratore. La colonna Stato mostra error se il manifest è invalido o il plugin non è riuscito a istanziarsi. Passa sopra per il messaggio, o esegui i tuoi test localmente per catturare lo stesso problema prima della spedizione.
  • Il plugin si abilita ma non fa nulla. Assicurati di usare il nome del gestore corretto (onChatMessage / on_chat_message, non onMessage) e che il permesso corrispondente sia nel tuo manifest. A call without its permission never reaches Owncast: the denial is logged on the server and the call returns an empty or zero value, so watch the Owncast logs.
  • Il plugin è disabilitato automaticamente. Un filtro che genera errori o si blocca cinque volte di seguito viene disabilitato per il resto della sessione. Correggi il bug, ricostruisci, ridistribuisci e riabilita.

Improve this page

See something missing or incorrect? Edit this page and improve the documentation for everyone.

Contributors to this documentation
Gabe KangasGabe Kangas