Entwickler von Integrationen: Aktualisiert fĂŒr Gladys 4.86 (SDK 0.12.0 + Store-Kategorien) 🚀

Entwicklung
1

Gladys 4.86 ist veröffentlicht, und es bringt zwei Neuerungen, die Ihre Integrationen direkt betreffen. Das Update dauert 5 Minuten mit Claude Code — der Prompt befindet sich unten in diesem Beitrag :wink:

1. Der Store hat jetzt Kategorien :card_index_dividers:

Der Katalog der Integrationen erhĂ€lt eine Navigation nach Kategorien, Filter und eine Sortierung „Neueste zuerst“. Damit Ihre Integration in den richtigen Regalen erscheint, mĂŒssen Sie ein neues Feld categories in Ihrer gladys-assistant-integration.json deklarieren:

"categories": ["lighting", "energy"],
"gladys_version": ">=4.86.0",

Die Regeln:

  • 1 bis 3 Kategorien, aus dem offiziellen Vokabular: climate, lighting, energy, security, multimedia, appliances, environment, protocols, network, notifications, assistants, services.
  • gladys_version muss auf ">=4.86.0" gesetzt werden, sobald Sie das Feld deklarieren: Ältere Versionen von Gladys lehnen jedes unbekannte Feld im Manifest ab, daher lehnt der Store-Validator ein Manifest ab, das categories mit einer niedrigeren Mindestversion deklariert. Beide gehören zusammen.
  • Ohne das Feld bleibt Ihre Integration unter „Alle“ und in der Suche sichtbar, erscheint aber in keinem Regal.

Bestehende Integrationen wurden erstmals ĂŒber eine Zuordnungstabelle auf der Store-Seite kategorisiert, aber Ihr Manifest gilt ab dem Moment, in dem Sie das Feld deklarieren — das ist die Gelegenheit zu ĂŒberprĂŒfen, ob die Kategorien fĂŒr Sie passen (und sie anzupassen, falls nicht!).

2. SDK 0.12.0 :package:

Die Version 0.12.0 des JavaScript-SDK ist rein additiv (keine breaking changes, das Bump ist risikofrei) und bringt:

  • PTZ-Steuerung von Kameras: Die Funktionen move / preset / absolute Positionen zur Steuerung von motorisierten Kameras;
  • Wake-on-LAN: gladys.wakeOnLan(mac) + das Feld network_wake des Manifests — der Core sendet das Magic-Paket vom Netzwerk des Hosts (der Container im Bridge-Modus kann nicht auf dem LAN broadcasten);
  • Konfigurationsfeld account_link: Der „Verbinden“-Button fĂŒr Anbieter, die nie zu Gladys umleiten (Verbindung per QR-Code in der Hersteller-App bestĂ€tigt, z. B. Xiaomi Home);
  • Dynamischer select-Typ (Kategorie text): Eine Auswahlliste, die auf dem GerĂ€t selbst entdeckt wird (Apps eines TVs, RĂ€ume eines Staubsaugers, native Szenen
) deklariert ĂŒber supported_options;
  • Neue GerĂ€tekategorien: grid-sensor (Austausch mit dem Stromnetz), home-output-sensor (Ausgang eines Wechselrichters/Batterie), maintenance (Verbrauchsmaterial: BĂŒrsten, Beutel, Filter
), und die Gassensoren no2 / o3 / so2 — um Solar, Batterien und Roboterstaubsauger besser abzudecken.

Wenn Ihre Integration Energie, Kameras oder HaushaltsgerĂ€te betrifft, gibt es sicher eine Neuerung fĂŒr Sie dabei.

Wie aktualisiere ich? Fragen Sie Claude :robot:

Alle Ihre Integrationen wurden mit Claude Code entwickelt — das Update funktioniert genauso. Öffnen Sie Claude Code im Repository Ihrer Integration und fĂŒgen Sie diesen Prompt ein:

Aktualisieren Sie meine Gladys-Integration fĂŒr die Version 4.86:

1. Setzen Sie @gladysassistant/integration-sdk auf ^0.12.0 (rein additive
   Änderungen, nichts im bestehenden Code muss angepasst werden).
2. FĂŒgen Sie das Feld `categories` in gladys-assistant-integration.json hinzu:
   1 bis 3 Werte aus climate, lighting, energy, security, multimedia,
   appliances, environment, protocols, network, notifications, assistants,
   services — wĂ€hlen Sie die, die zu dem passen, was die Integration tut.
3. Setzen Sie `gladys_version` auf ">=4.86.0" (erforderlich, sobald man
   `categories` deklariert).
4. ÜberprĂŒfen Sie, dass alles funktioniert: Format, Lint, Tests, dann der
   Store-Validator lokal: npx github:GladysAssistant/integration-store .

Das offizielle Template hat bereits dieses Update durchgefĂŒhrt, lassen Sie sich von seinen
letzten beiden PRs inspirieren: https://github.com/GladysAssistant/integration-template-js

Anschließend lesen Sie den Diff durch, starten Sie eine Release wie gewohnt (Workflow Release auf GitHub), und der Store-Indexer holt die neue Version innerhalb einer Stunde.

Das offizielle Template hat gerade die beiden Updates durchgefĂŒhrt (PRs #14 und #15): Sie dienen als Referenz, wenn Sie den genauen Diff sehen möchten.

Fragen zur Migration? Das ist der Thread dafĂŒr :backhand_index_pointing_down:

2

Muss man nicht 24 Stunden warten, bis die Instanzen aktualisiert sind, um zu vermeiden, eine Integration zu veröffentlichen, die (noch) nicht kompatibel ist?

Besteht die Gefahr, dass die Nutzer mit einem blockierenden Update konfrontiert werden?

3

Gute Frage, aber nein, der Mechanismus wurde dafĂŒr konzipiert, es gibt kein blockierendes Szenario:

  1. Kein automatisches Update der Integration: Es ist immer ein expliziter Klick des Admins erforderlich. Das Veröffentlichen löst nichts automatisch auf den Instanzen aus.

  2. Auf einer Instanz < 4.86 wird eine neue Installation sauber blockiert: Der Katalog vergleicht die Gladys-Version mit der gladys_version des Manifests, der Installations-Button ist deaktiviert mit der Nachricht „Benötigt Gladys ≄ 4.86“. Nichts wird beschĂ€digt.

  3. FĂŒr eine bereits installierte Integration auf einer < 4.86: Wenn der Benutzer auf „Aktualisieren“ klickt, lehnt die alte Gladys-Version das neue Manifest ab (das Feld categories ist fĂŒr sie unbekannt), ignoriert es stillschweigend und kehrt zum bereits installierten Manifest zurĂŒck. Sie zieht einfach das aktuelle Bild erneut und der Benutzer bleibt auf seiner funktionierenden Version, ohne Fehler oder beschĂ€digten Zustand. Übrigens wurde der Validator des Stores genau dafĂŒr eingefĂŒhrt, um eine kryptische Fehlermeldung in einen einfachen KompatibilitĂ€tsfilter umzuwandeln, der gladys_version >= 4.86.0 erzwingt, sobald categories deklariert wird.

Der einzige Nebeneffekt ist kosmetischer Natur: Auf einer noch nicht aktualisierten Instanz kann das Badge „Update verfĂŒgbar“ angezeigt werden, obwohl das Update erst nach dem Upgrade auf 4.86 tatsĂ€chlich ĂŒbernommen wird. Wenn Sie das Ihren Benutzern ersparen wollen, können Sie einen Tag oder zwei warten, bis die meisten Instanzen auf 4.86 aktualisiert sind, aber das ist keine Sicherheitsfrage: Im schlimmsten Fall bleiben sie auf der aktuellen Version, bis sie Gladys aktualisieren, und alles richtet sich dann von selbst wieder ein.

4

Jetzt bin ich vollkommen beruhigt :wink:

Bearbeitung: Erledigt! Aus meinem Jacuzzi :sweat_smile:

5

Erledigt fĂŒr alle Integrationen, die ich veröffentlicht habe :slight_smile: