Externe Integrationen: Aktualisieren auf Gladys 5.3, das JS SDK 0.16 und den Store

[pierre-gilles]

Hallo zusammen!

In den letzten Wochen hat sich vieles im Bereich der externen Integrationen verändert: neue Version des JavaScript-SDK (@gladysassistant/integration-sdk v0.16.0), neue Felder im Manifest, neue Validierungsregeln im Store… Dieser Beitrag fasst alles zusammen, was Sie tun müssen, um Ihre Integration zu aktualisieren, und was Sie zusätzlich tun können, wenn Sie möchten.

Gute Nachricht: es gibt keine zwingenden Breaking Changes. Eine heute veröffentlichte Integration bleibt indexiert. Aber einige Punkte verdienen eine Überprüfung, und die Neuerungen sind einen Blick wert

---

Die schnelle Checkliste

• SDK auf ^0.16.0 aktualisieren (Node.js ≥ 20)
• Ihre poll_frequency überprüfen: in Millisekunden, und nur aus den zulässigen Werten
• publishChangedStates verwenden, wenn Sie viele Zustände veröffentlichen (Grenze von 300 Zuständen/Minute)
• categories (und ggf. keywords / countries) zum Manifest hinzufügen
• Überprüfen, dass gladys_version alle von Ihnen deklarierten Felder abdeckt
• docs/en.md und docs/fr.md haben (jeweils mindestens 300 Zeichen)
• Cover überprüfen: JPEG oder PNG, genau 800×534 px, maximal 150 KB
• Lokalen Validator starten: npx github:GladysAssistant/integration-store
• Veröffentlichen: version + docker_image inkrementieren, wobei das Bild vor dem Manifest gepusht wird

Die Details zu jedem Punkt finden Sie unten.

---

1. SDK aktualisieren

npm install @gladysassistant/integration-sdk@^0.16.0

Das SDK erfordert Node.js ≥ 20. Denken Sie daran, das Basisbild Ihres Dockerfile zu überprüfen.

Was sich seit der v0.11 geändert hat:

Version	Hauptneuerungen
0.12	Synchronisation mit Gladys 4.86: Netzwerkstrom-/Gassensoren, PTZ-Kameras, wakeOnLan(), Konfigurationsfeld account_link
0.13	Sechs neue Wetterphänomene im Pivot-Format, Sirenen, Batterieladung, Scan-Ergebnisformat
0.14	Szenenauslöser und -aktionen, Dashboard-Widgets, getHouses(), Netzwerk-Kohlenstoff- und Rauchsensoren
0.15	DEVICE_POLL_FREQUENCIES, Gladys-Testumgebung für Ihre Tests, parseMdnsTxt(), publishChangedStates(), Typ calendar, Energieverträge, Formulare in Widget-Schaltflächen, Hausauswahl, publishEnergyConsumption()
0.16	Musikplayer, Typen ai und tts, should_poll wird optional

Das vollständige Changelog finden Sie auf GitHub.

---

2. Punkte zur Überprüfung in Ihrem Code

poll_frequency: in Millisekunden, und nur bestimmte Werte

Das ist die häufigste Falle. poll_frequency wird in Millisekunden angegeben, und nur diese Werte sind zulässig: 1 s, 2 s, 10 s, 15 s, 30 s oder 1 min. Jeder andere Wert (300 in Sekunden gedacht, 300000 für 5 Minuten…) führt zum Scheitern von publishDiscoveredDevices mit einem Fehler 400.

Verwenden Sie die vom SDK exportierten Konstanten:

import { DEVICE_POLL_FREQUENCIES } from '@gladysassistant/integration-sdk';

await gladys.publishDiscoveredDevices([
  {
    name: 'Wetterstation',
    external_id: ids.device,
    should_poll: true,
    poll_frequency: DEVICE_POLL_FREQUENCIES.EVERY_MINUTES, // 60000 ms
    features: [/* … */],
  },
]);

Einige Klarstellungen:

• Eine Minute ist das langsamste Tempo. Um langsamer zu gehen (Cloud-API mit Kontingent, Benutzereinstellung in Minuten), behalten Sie EVERY_MINUTES bei und ignorieren Sie unnötige Polls in onPoll, oder verwenden Sie Ihren eigenen Timer.
• Seit Gladys 5.3 reicht poll_frequency aus: Der Core aktiviert should_poll automatisch. Wenn Ihre gladys_version ältere Versionen akzeptiert, behalten Sie should_poll: true bei. Wenn Sie should_poll setzen, muss es ein Boolescher Wert sein.
• Diese beiden Felder werden bei der Erstellung des Geräts gelesen: Eine spätere Änderung aktualisiert kein bereits erstelltes Gerät.

Grenze von 300 Zuständen pro Minute: publishChangedStates

Die Host-API begrenzt POST /state auf 300 Zustände pro Minute und pro Integration. Wenn Sie viele Geräte abfragen, veröffentlichen Sie nur, was sich geändert hat:

// ersetzt publishStates: Nur die geänderten Werte gehen an Gladys
await gladys.publishChangedStates(states);

// und wir geben trotzdem einen unveränderten Wert alle 30 Minuten zurück
await gladys.publishChangedStates(states, { heartbeat: 30 * 60 * 1000 });

Das SDK unterteilt Batches mit mehr als 100 Zuständen, gibt zurück, was Gladys abgelehnt hat, und vergisst die Werte eines Geräts, wenn der Benutzer es erstellt, ändert oder löscht.

Verwenden Sie Konstanten, keine festen Zeichenfolgen

DEVICE_FEATURE_CATEGORIES, DEVICE_FEATURE_TYPES und DEVICE_FEATURE_UNITS sind eine exakte Kopie von server/utils/constants.js in Gladys und werden mit jeder Version aktualisiert. Wenn Sie Zeichenfolgen manuell kopiert haben, ist jetzt der richtige Zeitpunkt, um zu Konstanten zu wechseln: Sie vermeiden Tippfehler und haben die Autovervollständigung.

Wetter-Integrationen: night ist veraltet

Die Bedingung night wird zwar noch akzeptiert, ist aber veraltet. Eine regnerische Nacht wird als weather: 'rain', is_day: false geschrieben. Denken Sie auch an die neuen Bedingungen des Pivot-Formats und das Feld type der Warnungen (WEATHER_ALERT_TYPES).

Szenenauslöser und -aktionen: Die Schlüssel sind endgültig

Wenn Sie scene_triggers / scene_actions deklarieren, darf ein veröffentlichter Schlüssel nie umbenannt werden. Und das Hinzufügen eines Feldes required ohne default zu einer bestehenden Aktion macht Szenen, die sie verwenden, unbrauchbar.

---

3. Manifest aktualisieren

Die goldene Regel: gladys_version muss das abdecken, was Sie deklarieren

Ältere Versionen von Gladys lehnen Felder ab, die sie nicht kennen. Der Store überprüft daher, ob das Minimum Ihrer gladys_version jedes deklarierte Feld abdeckt, andernfalls wird die Integration abgelehnt. So sieht der Benutzer einfach „erfordert Gladys ≥ X“ im Katalog, anstatt einer Installation, die ohne Erklärung scheitert.

Sie deklarieren…	Mindest-gladys_version
categories	>=4.86.0
type: "provider", widgets, scene_triggers, scene_actions	>=5.1.0
type: "calendar", account_schema, energy_contracts, ein Feld mit source: "houses"	>=5.2.0
type: "ai", type: "tts", music, keywords, countries	>=5.3.0

In die andere Richtung: erhöhen Sie gladys_version nicht ohne Grund: Ihre Integration würde für Benutzer ausgeblendet, die Gladys noch nicht aktualisiert haben.

categories: Ihr Platz im Katalog

Zwischen 1 und 3 Kategorien aus: climate, lighting, energy, security, multimedia, appliances, environment, protocols, network, notifications, assistants, services, transport, vehicles, servers, leisure.

Die letzten vier (transport, vehicles, servers, leisure) wurden gerade hinzugefügt. Ohne categories bleibt Ihre Integration in „Alle“ und in der Suche sichtbar, erscheint aber in keiner Rubrik. Für bereits veröffentlichte Integrationen wendet der Store vorerst eine Notfallabbildung an (data/category-fallback.json). Die Kategorien selbst zu deklarieren ist der beste Weg, gut platziert zu werden. Eine unbekannte Kategorie wird einfach ignoriert, mit einer Warnung.

keywords und countries (Gladys ≥ 5.3)

{
  "gladys_version": ">=5.3.0",
  "categories": ["energy"],
  "keywords": ["linky", "enedis", "téléinfo"],
  "countries": ["FR"]
}

• keywords : 1 bis 10 Begriffe mit 2 bis 30 Zeichen, nie angezeigt, nur für die Suche verwendet (Marken, Modelle, Synonyme, Städte oder bediente Netzwerke…).
• countries : 1 bis 20 ISO-Ländercodes in Großbuchstaben. Setzen Sie es nicht, wenn Ihre Integration überall funktioniert (das ist das Standardverhalten). Wenn Sie es deklarieren, sehen Instanzen in anderen Ländern die Integration nicht mehr in den Katalogrubriken (sie bleibt über die Suche auffindbar). Denken Sie daran für eine regionale Integration: nationaler Wetterdienst, Verkehrsnetz, Energieversorger, ISP…

Verlassen Sie sich nicht darauf: Die Deklaration von keywords oder countries erfordert gladys_version ≥ 5.3.0.

---

4. Dokumentation und Cover

• Pflicht-Dokumentation : docs/en.md und docs/fr.md im Stammverzeichnis des Repositories, mindestens 300 Zeichen jeweils, gemäß den Abschnitten der Vorlage (Präsentation / Voraussetzungen / Konfiguration / Problembehebung). Fehlt einer, wird die Integration abgelehnt. Die Dateien werden vom Store gehostet und in den Installations- und Konfigurationsbildschirmen von Gladys angezeigt.
• Neu : docs/de.md und docs/es.md sind optional. Wenn sie vorhanden sind (mindestens 300 Zeichen), werden sie deutschen und spanischen Nutzern angezeigt.
• Cover : JPEG oder PNG, genau 800×534 px, max. 150 KB, direkte https-URL (ohne Umleitung). Am einfachsten: eine URL raw.githubusercontent.com zu einer Datei Ihres Repositories. Ein ungültiges Cover blockiert nicht die Indizierung, aber Sie erhalten ein Standardbild im Katalog.

---

5. Lokal validieren, bevor Sie veröffentlichen

Kein Warten mehr auf die stündliche Indizierung, um eine Ablehnung zu entdecken! Im Stammverzeichnis Ihres Repositories:

npx github:GladysAssistant/integration-store

Der Validator führt genau die gleichen Überprüfungen wie der Store-Roboter durch (Schema, Regeln gladys_version, Kategorien, Dokumentation, Existenz der Docker-Bilder, Cover) und zeigt alle Probleme auf einmal an. Exit-Code 0 = die Integration würde indiziert werden, 1 = sie würde abgelehnt werden.

In der CI Ihrer Pull Requests

In einem PR, das die Version erhöht, ist das Docker-Bild in der Regel noch nicht veröffentlicht: Fügen Sie --skip-image-check hinzu, um nur diese Überprüfung zu überspringen.

- uses: actions/setup-node@v4
  with:
    node-version: 24
- run: npx github:GladysAssistant/integration-store --skip-image-check

Führen Sie es ohne die Option aus, sobald die Bilder veröffentlicht sind, z. B. als letzter Schritt in Ihrem Release-Workflow.

---

6. Neue Version veröffentlichen

1. Erhöhen Sie version (strikte SemVer) und docker_image (mit einem expliziten Tag) im Manifest.
2. Veröffentlichen Sie das Docker-Bild, bevor das Manifest, das darauf verweist, in den Standardzweig gelangt: Der Store überprüft, dass das Bild existiert und ohne Authentifizierung heruntergeladen werden kann. Fehlt das Bild, wird die Integration aus dem Katalog entfernt, bis zur nächsten Indizierung.
3. Pushen. Bei der nächsten Indizierung (stündlich) zeigt Gladys „Update verfügbar“ Ihren Nutzern an.

Ihre Integration wird nicht angezeigt? Schauen Sie sich die öffentliche Datei rejected.json des Stores an: Jede Ablehnung wird dort mit ihrem Grund aufgelistet (error = nicht indiziert, warning = indiziert mit einer Verschlechterung, z. B. das Standard-Cover).

---

7. Testen Sie Ihre Integration mit dem fiktiven Gladys

Das SDK bietet jetzt einen Gladys im Speicher für Ihre Unit-Tests: Es ist eine echte GladysIntegration, die an einen falschen Gladys statt an das Netzwerk angeschlossen ist.

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { createFakeGladys } from '@gladysassistant/integration-sdk/testing';
import { registerHandlers } from '../src/app.js';

test('veröffentlicht die Temperatur beim Poll', async () => {
  const gladys = createFakeGladys({ config: { api_key: 'key' } });
  registerHandlers(gladys);
  await gladys.connect();

  const [device] = gladys.fake.discoveredDevices;
  assert.deepEqual(await gladys.fake.poll(device), { success: true });
  assert.equal(gladys.fake.lastState(`${device.external_id}:temperature`), 21.5);
});

Es führt die gleichen Überprüfungen wie die Host-API durch (Präfix der external_id, bekannte Kategorien/Typen/Einheiten, poll_frequency…) und antwortet mit den gleichen Fehlern 400. Sie sehen also die Fehler in Ihren Tests, nicht bei Ihren Nutzern.

---

8. Weitergehen (optional)

Wenn Sie Ihre Integration erweitern möchten, hier ist alles, was jetzt möglich ist:

Funktion	Manifest	SDK	Gladys
Dashboard-Widgets	widgets	onWidgetGet, onWidgetAction, requestWidgetRefresh	≥ 5.1
Szenenauslöser / Aktionen	scene_triggers, scene_actions	publishSceneEvent, onSceneAction	≥ 5.1
„Nur Fähigkeiten“-Integration	type: "provider"	—	≥ 5.1
Kalenderanbieter	type: "calendar", account_schema	publishCalendars, publishCalendarEvents…	≥ 5.2
Energieverträge und -kalender	energy_contracts	publishEnergyCalendar, onEnergyPrice…	≥ 5.2
Datierte Verbrauchsdaten (nachträglich empfangene Zählerstände)	—	publishEnergyConsumption	≥ 5.2
Hausauswahl in einem Formular	source: "houses"	—	≥ 5.2
KI-Anbieter (kompatibel mit OpenAI)	type: "ai"	onAiChat	≥ 5.3
Sprachsynthese	type: "tts"	onTtsSynthesize	≥ 5.3
Musikplayer (Navigation, Suche, Warteschlange)	music	publishNowPlaying, onMusicBrowse, onMusicPlay…	≥ 5.3
Wake-on-LAN	network_wake: true	wakeOnLan	≥ 4.86
Verbindung zu einem Konto ohne Umleitung (QR-Code…)	Feld account_link	onOAuthAuthorizeUrl	≥ 4.86

Alles ist im README des SDK dokumentiert, und alle Manifest-Regeln sind im README des Stores.

---

Wenn Sie bei einer Migration stecken bleiben oder eine Validierungsregel seltsam erscheint, antworten Sie in diesem Thema oder öffnen Sie ein Issue auf integration-sdk-js / integration-store.

Vielen Dank an alle, die Integrationen entwickeln, der Katalog wächst sehr schnell!