Manifeste et autorisations

plugin.manifest.json indique à la ville qui vous êtes, où se trouve votre expérience et ce qu’elle peut demander. Nous approuvons une combinaison précise de version, d’entrée et d’autorisations. Toute modification exige une nouvelle approbation.

Exemple

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"]
}

Champs

Champ	Règle
`schema`	Toujours `zenclub.plugin/v1`.
`id`	De 1 à 80 lettres, chiffres, points, tirets bas ou traits d’union ; commence par une lettre ou un chiffre. Ne change jamais.
`name, description, coverLabel`	Texte brut de 2048 caractères maximum par champ. `coverLabel` est la courte légende de votre couverture.
`version`	Version sémantique, par exemple `1.4.0` ou `1.5.0-beta.1`. Elle doit correspondre à la `version` transmise à `connect()`.
`sdkProtocol`	Toujours `zenclub.rpc/1`.
`hostApi`	La version minimale de l’API de l’hôte nécessaire, sous la forme `{major, minMinor}`. Demandez la version mineure la plus basse qui convient.
`entry`	URL HTTPS absolue de votre page, sans nom d’utilisateur, mot de passe ni fragment. HTTP simple n’est accepté que sur localhost. L’origine doit être différente de celle de la plateforme.
`permissions`	Capacités indispensables au fonctionnement de votre expérience. Aucun doublon.
`optionalPermissions`	Jusqu’à 32 capacités utilisées lorsqu’elles sont accordées. Ne répétez aucune capacité requise.
`milestones`	Facultatif : une clé fixe, une version de règle et un niveau maximal, que l’opérateur approuve séparément en même temps que la capacité de signalement.
`modes`	Un ou plusieurs modes parmi `watch`, `manual` et `listen`. Vous ne pouvez signaler qu’un mode déclaré.
`tags`	Jusqu’à 10 étiquettes de 32 caractères maximum chacune.

Capacités

Chaque méthode du SDK correspond à une capacité. Un appel non autorisé échoue avec FORBIDDEN avant de quitter votre cadre. Vérifiez d’abord les capacités facultatives avec sdk.supports(name).

Capacité	API de l’hôte	Utilisation
`lifecycle.report`	1.0	Signaler le chargement, l’état prêt ou l’échec.
`storage.read`	1.0	Lire un emplacement de sauvegarde.
`storage.write`	1.0	Écrire dans un emplacement avec vérification de révision.
`session.report`	1.0	Signaler si la session est en cours, en pause ou terminée pour mesurer sa durée.
`runs.finish`	1.0	Enregistrer une partie terminée ou relancée avec jusqu’à 20 mesures numériques.
`moments.create`	1.0	Proposer au visiteur une image à conserver. La plateforme peut lui demander son accord.
`achievements.request`	1.0	Demander à la plateforme de vérifier et d’attribuer un badge.
`counters.add`	1.2	Ajouter une valeur à un total partagé défini par l’opérateur pour vous.
`events.report`	1.2	Signaler un événement nommé et bref, comme la fin d’un chapitre.
`shares.request`	1.2	Ouvrir le panneau de partage de la plateforme pour un badge ou votre expérience.
`navigation.exit`	1.2	Revenir discrètement à la page de détails de votre expérience.
`display.immersive`	1.3	Demander à la plateforme de masquer le cadre qui vous entoure.
`header.setActions`	1.4	Placer vos actions dans l’en-tête de la plateforme.
`milestones.report`	1.6	Signaler une décoration approuvée pour la ville personnelle à partir d’une sauvegarde confirmée, si la personne a activé l’enregistrement.

Valider avant de faire la demande

L’outil en ligne de commande effectue les mêmes vérifications que la plateforme et confirme la disponibilité de l’API de l’hôte demandée. La validation n’accorde aucune capacité ; seule une approbation le fait.

shell

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

Versions de l’API de l’hôte

L’API de l’hôte actuelle est en version 1.6 et accepte les plugins qui demandent une version de 1.0 à 1.6. Demandez la version mineure la plus basse dont vous avez besoin et vérifiez les méthodes facultatives avec sdk.supports(). Pour recevoir la préférence sonore, exigez la version 1.5 ou ultérieure dans le manifeste et dans connect(). Les anciens plugins sans déclaration d’étape conservent les mêmes autorisations et le même contexte qu’auparavant.

Étapes de la ville personnelle

Déclarez milestones.report comme capacité facultative et ajoutez exactement une entrée milestones. La première version comporte huit clés fixes : homestead, pond, clouds, bamboo, tea, stream, bell et lotus. Chaque version de règle correspond à sa clé suivie de .1, avec maxTier: 2. L’approbation fixe cette combinaison, cette version, cette entrée et cette capacité. Une déclaration rédigée par le plugin ne donne jamais accès à la fonction.

plugin.manifest.json

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

Un plugin créé avec le SDK 0.9 peut conserver une version minimale antérieure lorsque le signalement est facultatif. Sur un hôte 1.0–1.5, sans approbation ou avec un stockage limité à l’appareil, le jeu doit rester jouable et le signalement doit être ignoré. Les approbations des anciens hôtes doivent omettre la nouvelle autorisation. Le signalement obligatoire des étapes nécessite la version 1.6 ; l’enregistrement ne doit jamais être requis pour jouer ou se connecter.