Manifest und Berechtigungen

plugin.manifest.json teilt der Stadt mit, wer du bist, wo dein Erlebnis liegt und worum es bitten darf. Wir genehmigen genau eine Kombination aus Version, Einstieg und Berechtigungen. Ändere einen dieser Werte, muss die neue Version erneut genehmigt werden.

Beispiel

plugin.manifest.json

{
  "schema": "zenclub.plugin/v1",
  "id": "my-garden",
  "name": "My garden",
  "description": "Tend a small garden at your own pace.",
  "coverLabel": "A small garden",
  "version": "1.0.0",
  "sdkProtocol": "zenclub.rpc/1",
  "hostApi": {"major": 1, "minMinor": 2},
  "entry": "https://my-garden.example/v1.0.0/",
  "permissions": ["lifecycle.report", "storage.read", "storage.write", "session.report"],
  "optionalPermissions": ["moments.create", "header.setActions"],
  "modes": ["watch", "manual"],
  "tags": ["garden", "slow"]
}

Felder

Feld	Regel
`schema`	Immer `zenclub.plugin/v1`.
`id`	1 bis 80 Buchstaben, Ziffern, Punkte, Unterstriche oder Bindestriche, beginnend mit einem Buchstaben oder einer Ziffer. Der Wert bleibt unverändert.
`name, description, coverLabel`	Einfacher Text mit bis zu 2048 Zeichen pro Feld. `coverLabel` ist die kurze Bildunterschrift auf deinem Titelbild.
`version`	Semantische Version, zum Beispiel `1.4.0` oder `1.5.0-beta.1`. Sie muss der `version` entsprechen, die du an `connect()` übergibst.
`sdkProtocol`	Immer `zenclub.rpc/1`.
`hostApi`	Die niedrigste benötigte Host-API als `{major, minMinor}`. Gib die niedrigste funktionierende Nebenversion an.
`entry`	Absolute HTTPS-URL deiner Seite ohne Benutzername, Passwort oder Hash. Einfaches HTTP ist nur auf localhost zulässig. Sie darf nicht denselben Origin wie die Plattform verwenden.
`permissions`	Fähigkeiten, ohne die dein Erlebnis nicht funktioniert. Keine Duplikate.
`optionalPermissions`	Bis zu 32 Fähigkeiten, die du bei Freigabe verwendest. Eine erforderliche Fähigkeit darfst du nicht erneut aufführen.
`milestones`	Optional: ein fester Schlüssel, eine Regelversion und die Höchststufe. Der Betreiber gibt diese gemeinsam mit der Meldeberechtigung separat frei.
`modes`	Einer oder mehrere der Modi `watch`, `manual` und `listen`. Du kannst nur einen Modus melden, den du angegeben hast.
`tags`	Bis zu 10 Tags mit höchstens 32 Zeichen.

Fähigkeiten

Jede SDK-Methode entspricht einer Fähigkeit. Ein Aufruf ohne Freigabe schlägt mit FORBIDDEN fehl, bevor er dein Frame verlässt. Prüfe optionale Fähigkeiten zuerst mit sdk.supports(name).

Fähigkeit	Host-API	Verwendung
`lifecycle.report`	1.0	Laden, Bereit oder Fehlgeschlagen melden.
`storage.read`	1.0	Einen Speicherplatz lesen.
`storage.write`	1.0	Mit Revisionsprüfung in einen Speicherplatz schreiben.
`session.report`	1.0	Laufend, pausiert oder beendet zur Zeiterfassung melden.
`runs.finish`	1.0	Einen abgeschlossenen oder neu gestarteten Durchlauf mit bis zu 20 numerischen Messwerten erfassen.
`moments.create`	1.0	Den Besuchenden ein Bild zum Aufbewahren anbieten. Die Plattform kann vorher fragen.
`achievements.request`	1.0	Die Plattform bitten, einen Nachweis zu prüfen und ein Abzeichen zu verleihen.
`counters.add`	1.2	Einen gemeinsamen Zähler erhöhen, den die Administration für dich eingerichtet hat.
`events.report`	1.2	Ein kurzes Ereignis mit Namen melden, zum Beispiel ein abgeschlossenes Kapitel.
`shares.request`	1.2	Die Teilen-Ansicht der Plattform für ein Abzeichen oder dein Erlebnis öffnen.
`navigation.exit`	1.2	Leise zur Detailseite deines Erlebnisses zurückkehren.
`display.immersive`	1.3	Die Plattform bitten, den Rahmen um dich auszublenden.
`header.setActions`	1.4	Deine Aktionen in der Kopfzeile der Plattform platzieren.
`milestones.report`	1.6	Eine freigegebene Dekoration der privaten Stadt aus einem bestätigten Spielstand melden, wenn die spielende Person die Aufzeichnung aktiviert hat.

Vor der Anfrage prüfen

Das Kommandozeilenwerkzeug führt dieselben Prüfungen wie die Plattform aus und bestätigt, dass die angeforderte Host-API verfügbar ist. Die Prüfung erteilt keine Berechtigungen. Das geschieht erst mit einer Genehmigung.

shell

npx zenclub-plugin validate plugin.manifest.json --host=https://zenclub.app

Versionen der Host-API

Die aktuelle Host-API ist 1.6 und akzeptiert Plugins mit Anforderungen von 1.0 bis 1.6. Fordere die niedrigste benötigte Nebenversion an und sichere optionale Methoden mit sdk.supports() ab. Um die Klangpräferenz zu erhalten, fordere 1.5 oder höher sowohl im Manifest als auch in connect() an. Ältere Plugins ohne Meilensteindeklarationen erhalten dieselben Freigaben und denselben Kontext wie zuvor.

Optionale Stadtmeilensteine

Deklariere milestones.report als optional und füge genau einen Eintrag unter milestones hinzu. Die erste Version hat acht feste Schlüssel: homestead, pond, clouds, bamboo, tea, stream, bell und lotus. Jede Regelversion setzt sich aus dem Schlüssel und .1 zusammen; für jede gilt maxTier: 2. Die Freigabe gilt genau für diese Kombination, Version, diesen Eintrag und diese Fähigkeit. Selbst geschriebene Deklarationen erteilen keinen Zugriff.

plugin.manifest.json

{
  "hostApi": {"major": 1, "minMinor": 6},
  "optionalPermissions": ["milestones.report"],
  "milestones": [{"key": "tea", "ruleVersion": "tea.1", "maxTier": 2}]
}

Ein mit SDK 0.9 erstelltes Plugin kann eine ältere Mindestversion beibehalten, wenn die Meldung optional ist. Auf einem Host mit API 1.0–1.5, ohne Freigabe oder bei Speicherung nur auf dem Gerät: Spiele normal weiter und überspringe die Meldung. Ältere Host-Freigaben dürfen die neue Berechtigung nicht enthalten. Erforderliche Stadtmeilensteine setzen 1.6 voraus; die Aufzeichnung darf nie Voraussetzung zum Spielen oder Anmelden sein.