Aller au contenu

Empaqueter, installer, mettre à jour

Un plugin s’installe à partir d’un fichier .zip qui contient, à la racine, le manifest.json, les pages et le SDK :

mon-plugin-1.0.0.zip
manifest.json
index.html
app.js
styles.css
settings.schema.json (si le manifeste déclare des réglages)
kiwidesk-plugin-sdk.js
images/logo.png
Limite Valeur
Taille du .zip 10 Mo
Taille décompressée totale 30 Mo
Taille d’un fichier 10 Mo
Nombre de fichiers 500
Chemin 200 caractères, 10 niveaux de dossiers au plus
Types acceptés html, js, mjs, css, json, images (png, jpg, jpeg, gif, webp, avif, svg, ico), polices (woff, woff2, ttf, otf)

Un autre type de fichier refuse le paquet. Sont aussi refusés : les chemins absolus ou qui remontent (../), les fichiers cachés (.env, .git), les liens symboliques, les doublons (même à la casse près), les noms réservés de Windows (con, nul, com1…), les archives chiffrées ou ZIP64, et les taux de compression anormaux.

Le dépôt fournit examples/plugins/zip-plugin.mjs, sans dépendance :

  1. Construisez le SDK une fois (depuis la racine du dépôt) :

    Fenêtre de terminal
    pnpm install
    pnpm --filter @kiwidesk/plugin-sdk build
  2. Empaquetez le dossier du plugin :

    Fenêtre de terminal
    node examples/plugins/zip-plugin.mjs chemin/vers/mon-plugin
    zip-plugin: 5 files -> chemin/vers/mon-plugin/dist/mon-plugin-1.0.0.zip

Le script copie le SDK à côté de vos fichiers, ignore les dossiers dist et node_modules et les fichiers cachés, laisse de côté (avec un avertissement) les types refusés, comme un README.md, et écrit dist/<id>-<version>.zip.

  1. Connecté en super administrateur, ouvrez Paramètres > Plugins (groupe Avancé).
  2. Cliquez sur Installer un plugin et choisissez le fichier .zip.
  3. Lisez l’écran Installer <nom> ? : Permissions demandées (avec le badge Sensible et les routes de l’API que chacune ouvre), Événements reçus par son serveur, Serveur du plugin (refusé s’il pointe vers le réseau local), version requise de KiwiDesk.
  4. Choisissez les Boutiques autorisées.
  5. Cliquez sur Accepter et installer, ou Refuser (le paquet est alors supprimé).
  6. Si le plugin a un serveur, copiez les Identifiants affichés une seule fois (voir Serveur du plugin).

Le plugin est aussitôt Activé : ses emplacements apparaissent pour les utilisateurs des boutiques autorisées qui ont les permissions voulues (rechargez la page s’ils ne sont pas encore visibles). Un paquet téléversé mais ni accepté ni refusé est effacé au bout d’une heure.

Page Paramètres, Plugins : avertissement de sécurité, bouton Installer un plugin et tableau de trois plugins activés avec leur version, auteur, état, boutiques autorisées et date d'installation.
Paramètres > Plugins, avec les trois plugins d’exemple installés.

La fiche d’un plugin (clic sur sa ligne) montre ses informations, ses boutiques, ses Réglages du plugin, son jeton et son webhook, et les boutons Activer / Désactiver, Régénérer les identifiants et Désinstaller. La partie administrateur est aussi décrite dans Plugins.

Les mêmes étapes existent dans l’API, avec une session de super administrateur (les clés API n’y ont pas accès) :

Fenêtre de terminal
# 1. Téléverser : rien n'est installé, la réponse décrit le paquet (uploadId, permissions, routes...)
curl -X POST "$KIWIDESK_URL/plugins/packages" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@dist/mon-plugin-1.0.0.zip"
# 2. Accepter : "accept" doit reprendre exactement ce que le paquet demande
curl -X POST "$KIWIDESK_URL/plugins" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"uploadId": "01a1f676-835a-733a-8a73-f96e106b04fb",
"allStores": false,
"storeIds": ["01a1bafb-6510-738f-98da-85c97912cce8"],
"accept": {
"permissions": ["core:customers:read", "plugin:storage"],
"events": [],
"webhookUrl": null
}
}'

La réponse de l’installation contient plugin et credentials (token, webhookSecret, null sans serveur). Autres routes : DELETE /api/plugins/packages/{uploadId} (refuser), GET /api/plugins et GET /api/plugins/{id}, POST /api/plugins/{id}/enable et /disable, PUT /api/plugins/{id}/stores ({ allStores, storeIds }), PUT /api/plugins/{id}/settings ({ values }), POST /api/plugins/{id}/credentials (régénérer), DELETE /api/plugins/{id}?keepData=true|false (désinstaller).

  1. Augmentez version dans le manifeste (1.0.0 vers 1.1.0) et refaites le paquet.
  2. Dans Paramètres > Plugins, Installer un plugin avec le nouveau .zip : KiwiDesk reconnaît le plugin à son id et affiche Mettre à jour <nom> ?.
  3. Si la nouvelle version ne demande pas plus de droits, cliquez sur Mettre à jour. Si elle demande une permission, un événement ou un serveur de plus (marqués Nouveau), il faut Accepter les nouveaux droits et mettre à jour.
  • Les boutiques autorisées, les réglages, le stockage et les identifiants sont conservés.
  • Une version égale ou plus ancienne est refusée (« la mise à jour est impossible »).
  • L’ancienne version reste servie 10 minutes pour les cadres déjà ouverts, puis est supprimée.
  • Désactiver : les emplacements disparaissent, le jeton est refusé, les webhooks sont suspendus. Activer remet tout en service.
  • Désinstaller : le jeton est révoqué, le webhook supprimé, les fichiers effacés. Cochez Conserver ses réglages et son stockage pour une réinstallation plus tard (état Désinstallé (données conservées)), ou décochez pour tout supprimer. Supprimer les données efface ensuite définitivement ce qui a été conservé.

Chaque étape est inscrite au journal d’audit.

Les outils de développement du navigateur (F12) fonctionnent dans les cadres des plugins : choisissez le cadre du plugin dans le sélecteur de contexte de la Console.

Ce que vous voyez Cause probable
Plugin indisponible, Réessayer La page n’a pas appelé connect() en 10 secondes : erreur JavaScript, script en ligne bloqué par la CSP, kiwidesk-plugin-sdk.js absent du paquet, import mal écrit
Plugin arrêté La page a chargé un autre document (lien, location.href, formulaire) : utilisez une ancre ou kiwidesk.navigate()
« Refused to execute inline script » dans la console Déplacez le code dans un fichier .js
« Refused to connect » dans la console fetch vers une autre adresse que le serveur du plugin
ApiError PLUGIN_SCOPE Route non ouverte aux plugins
ApiError PERMISSION_DENIED Permission absente du manifeste, ou que l’utilisateur n’a pas
HostError TOO_MANY_REQUESTS Plus de 3 actions visibles en 10 secondes, ou une fenêtre déjà ouverte
L’emplacement n’apparaît pas Plugin désactivé, boutique active non autorisée, permissions de l’emplacement non détenues, ou page à recharger

Une page de plugin ne fonctionne qu’à l’intérieur de KiwiDesk : pour la tester, installez-la sur une instance de développement.