Empaqueter, installer, mettre à jour
Le paquet
Section intitulée « Le paquet »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 script d’empaquetage
Section intitulée « Le script d’empaquetage »Le dépôt fournit examples/plugins/zip-plugin.mjs, sans dépendance :
-
Construisez le SDK une fois (depuis la racine du dépôt) :
Fenêtre de terminal pnpm installpnpm --filter @kiwidesk/plugin-sdk build -
Empaquetez le dossier du plugin :
Fenêtre de terminal node examples/plugins/zip-plugin.mjs chemin/vers/mon-pluginzip-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.
Installer
Section intitulée « Installer »- Connecté en super administrateur, ouvrez Paramètres > Plugins (groupe Avancé).
- Cliquez sur Installer un plugin et choisissez le fichier
.zip. - 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.
- Choisissez les Boutiques autorisées.
- Cliquez sur Accepter et installer, ou Refuser (le paquet est alors supprimé).
- 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.

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.
Par l’API
Section intitulée « Par l’API »Les mêmes étapes existent dans l’API, avec une session de super administrateur (les clés API n’y ont pas accès) :
# 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 demandecurl -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).
Mettre à jour
Section intitulée « Mettre à jour »- Augmentez
versiondans le manifeste (1.0.0vers1.1.0) et refaites le paquet. - Dans Paramètres > Plugins, Installer un plugin avec le nouveau
.zip: KiwiDesk reconnaît le plugin à sonidet affiche Mettre à jour <nom> ?. - 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, désinstaller
Section intitulée « Désactiver, désinstaller »- 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.
Déboguer
Section intitulée « Déboguer »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.