Zum Hauptinhalt springen

Manifest und Property Inspectors

Das Manifest ist der Vertrag

Das Manifest sagt Stream Deck, was dein Plugin ist, wie es ausgeführt wird, welche Actions es bereitstellt, welche Geräte und OS-Versionen es unterstützt und wo die Konfigurations-UI liegt.

1. Aufgaben des Manifests​

manifest.json definiert:

  • Plugin-Name, Autor, Version, Beschreibung, Icon und UUID,
  • den Einstiegspunkt ĂĽber CodePath,
  • unterstĂĽtzte Betriebssysteme,
  • die minimale Stream Deck Softwareversion,
  • die Node.js-Runtime-Konfiguration,
  • Actions und ihre Metadaten,
  • UnterstĂĽtzung fĂĽr Tasten- und Dial-Controller,
  • Action-Zustände und -Bilder,
  • Property-Inspector-Pfade,
  • vordefinierte Profile,
  • optionale App-Monitoring-Metadaten.

Verwende die Schema-URL zur Validierung:

{
  "$schema": "https://schemas.elgato.com/streamdeck/plugins/manifest.json"
}

2. Minimale Manifest-Form​

{
  "$schema": "https://schemas.elgato.com/streamdeck/plugins/manifest.json",
  "Author": "Example",
  "Name": "Deploy Tools",
  "Description": "Deployment shortcuts for Stream Deck.",
  "Icon": "imgs/plugin-icon",
  "Version": "1.0.0.0",
  "UUID": "com.example.deploy-tools",
  "CodePath": "bin/plugin.js",
  "SDKVersion": 2,
  "Software": {
    "MinimumVersion": "7.1"
  },
  "Nodejs": {
    "Version": "24"
  },
  "OS": [
    { "Platform": "mac", "MinimumVersion": "13" },
    { "Platform": "windows", "MinimumVersion": "10" }
  ],
  "Actions": [
    {
      "UUID": "com.example.deploy-tools.deploy",
      "Name": "Deploy",
      "Icon": "imgs/deploy-icon",
      "PropertyInspectorPath": "ui/deploy.html",
      "States": [
        {
          "Image": "imgs/deploy"
        }
      ]
    }
  ]
}

3. Action-Metadaten​

Jede Action braucht:

  • eine stabile Action-UUID mit der Plugin-UUID als Präfix,
  • einen lesbaren Action-Namen,
  • ein Icon,
  • Zustände und Bilder, wo angebracht,
  • optionale Controller-UnterstĂĽtzung fĂĽr Tasten und Dials,
  • optionalen Property-Inspector-Pfad.

Nutze eine Action für ein nutzerseitiges Verhalten. Verstecke nicht viele unzusammenhängende Verhaltensweisen hinter einer Action, außer der Property Inspector macht den Modus offensichtlich.

4. Tasten, Dials und Controller​

Tasten-Actions zielen auf tastenfeldartige Bedienelemente. Dial-Actions zielen auf Stream Deck + Encoder und deren Touchscreen-Bereich.

Wenn eine Action beides unterstĂĽtzt, deklariere es explizit:

{
  "UUID": "com.example.audio.volume",
  "Name": "Volume",
  "Controllers": ["Keypad", "Encoder"],
  "Icon": "imgs/volume",
  "States": [
    {
      "Image": "imgs/volume"
    }
  ],
  "Encoder": {
    "layout": "$B1",
    "TriggerDescription": {
      "Rotate": "Adjust volume",
      "Push": "Mute"
    }
  }
}

FĂĽge Dial-UnterstĂĽtzung nicht nur hinzu, weil sie verfĂĽgbar ist. FĂĽge sie hinzu, wenn Drehung oder der Touchstreifen die Action besser machen.

5. Property Inspectors​

Property Inspectors sind HTML-Webviews zum Konfigurieren von Actions. Lege sie unter *.sdPlugin/ui/ ab und referenziere sie aus manifest.json.

{
  "Actions": [
    {
      "UUID": "com.example.deploy-tools.deploy",
      "Name": "Deploy",
      "PropertyInspectorPath": "ui/deploy.html"
    }
  ]
}

Nutze einen Property Inspector fĂĽr:

  • Zielauswahl,
  • Modusauswahl,
  • Beschriftungen,
  • Anzeigeeinstellungen,
  • IDs pro Action,
  • nicht geheime Konfiguration.

Vermeide Property Inspectors fĂĽr:

  • Geheimnisse,
  • groĂźe Tabellen,
  • Konto-Onboarding-Flows,
  • Workflows, die ein vollständiges Browserfenster brauchen.

6. Einfacher Property Inspector​

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Deploy Settings</title>
    <script src="sdpi-components.js"></script>
  </head>
  <body>
    <sdpi-item label="Environment">
      <sdpi-select setting="environment">
        <option value="staging">Staging</option>
        <option value="production">Production</option>
      </sdpi-select>
    </sdpi-item>

    <sdpi-item label="Service">
      <sdpi-textfield setting="serviceName" placeholder="api"></sdpi-textfield>
    </sdpi-item>
  </body>
</html>

Elgatos Property-Inspector-Doku empfiehlt, die UI-Komponentenbibliothek lokal zu nutzen, um vorhersehbares Offline-Verhalten zu erreichen.

7. Einstellungsdesign​

Nutze einen Einstellungstyp pro Action:

type DeploySettings = {
  environment?: 'staging' | 'production';
  serviceName?: string;
};

Setze Standardwerte im Action-Code, nicht nur in der UI:

const environment = ev.payload.settings.environment ?? 'staging';
const serviceName = ev.payload.settings.serviceName ?? 'api';

Das hält die Action robust, wenn:

  • Nutzende die Action hinzufĂĽgen, bevor sie den Inspector öffnen,
  • Einstellungen von einer älteren Plugin-Version stammen,
  • Inspector-Felder entfernt oder umbenannt wurden,
  • Profile von einer anderen Maschine importiert wurden.

8. Einstellungen versionieren​

Wenn sich Einstellungen weiterentwickeln, nutze tolerante Lesevorgänge:

type SettingsV1 = {
  target?: string;
};

type SettingsV2 = {
  target?: string;
  displayMode?: 'status' | 'compact';
};

function normalizeSettings(settings: SettingsV1 | SettingsV2): Required<SettingsV2> {
  return {
    target: settings.target ?? 'default',
    displayMode: 'displayMode' in settings ? settings.displayMode ?? 'status' : 'status',
  };
}

Vermeide erzwungene Migrationen, auĂźer du brauchst sie wirklich. Die meisten Stream Deck Einstellungen lassen sich beim Lesen normalisieren.

9. Qualitäts-Checkliste für das Manifest​

  • Die Plugin-UUID ist stabil und im Reverse-DNS-Format.
  • Action-UUIDs haben die Plugin-UUID als Präfix.
  • CodePath zeigt auf die gebaute Einstiegsdatei.
  • Nodejs.Version passt zur aktuellen SDK-Anforderung.
  • Icons und Zustandsbilder existieren im gepackten Verzeichnis.
  • Property-Inspector-Pfade sind relativ zum Plugin-Verzeichnis.
  • Minimale OS- und Stream Deck Versionen passen zu den genutzten Funktionen.
  • Die Schema-Validierung besteht.