Aller au contenu

Plugins

Un plugin ajoute à KiwiDesk une fonction venue d’ailleurs : un onglet « Suivi transporteur » sur les tickets, un bouton « Commander chez le fournisseur », un widget du tableau de bord. Il s’installe depuis le back-office, sous forme d’un paquet .zip, sans toucher au code de KiwiDesk.

Un plugin est isolé : son interface s’affiche dans des cadres séparés de KiwiDesk, il n’agit que dans la limite des permissions et des boutiques que vous lui accordez à l’installation, et jamais au-delà des droits de l’utilisateur qui s’en sert. Un plugin en panne affiche « Plugin indisponible » sans bloquer la page.

La page Paramètres > Avancé > Plugins est réservée aux super administrateurs.

Page Plugins : avertissement de sécurité et liste des plugins installés avec leur version, auteur, état et boutiques autorisées

  1. Cliquez sur Installer un plugin et choisissez le fichier .zip (10 Mo au plus).
  2. KiwiDesk affiche l’écran de revue Installer … ?. Lisez :
    • Permissions demandées, avec la mention Sensible pour les plus délicates (réglages, sécurité, boutiques, journal d’audit, matériel, données protégées) ; chaque permission indique les routes de l’API qu’elle ouvre au plugin ;
    • Événements reçus par son serveur (ticket créé, statut changé…) ;
    • Serveur du plugin : l’adresse qui recevra les événements. Une adresse du réseau local est refusée. Pas de serveur signifie que le plugin n’agit que depuis l’interface ;
    • Boutiques autorisées : choisissez les boutiques, ou Toutes les boutiques, y compris les futures.
  3. Cliquez sur Accepter et installer, ou Refuser.
  4. Si le plugin a un serveur, KiwiDesk affiche une seule fois le Jeton du plugin et le Secret de signature des webhooks. Copiez-les dans la configuration du serveur du plugin, puis cliquez sur J’ai copié les identifiants.

Résultat : le plugin est Activé. Ses entrées de menu, onglets, boutons et widgets apparaissent pour les utilisateurs qui ont les permissions nécessaires. Si le plugin a des réglages, ils s’affichent dans sa fiche (Réglages du plugin) ; un réglage secret est chiffré et n’est jamais réaffiché.

Un plugin ne reçoit jamais certaines permissions, même s’il les demande : clés API, webhooks, rôles, utilisateurs, modification du profil. Il ne voit jamais les codes de déverrouillage, les liens de suivi des clients ni les secrets.

Cliquez sur sa ligne pour ouvrir sa fiche (version, auteur, empreinte SHA-256 du paquet, boutiques, webhook) :

  • Désactiver / Activer : désactivé, son jeton est refusé et ses webhooks sont suspendus aussitôt ;
  • Mettre à jour : installez un paquet d’une version plus récente. Si elle demande plus de droits (marqués Nouveau), une nouvelle acceptation est nécessaire. Une version égale ou plus ancienne est refusée ;
  • Régénérer les identifiants : l’ancien jeton et l’ancien secret cessent immédiatement de fonctionner ;
  • Désinstaller : ses emplacements disparaissent, son jeton est révoqué, ses fichiers sont supprimés. Vous pouvez conserver ses réglages et son stockage pour une réinstallation, ou les supprimer ensuite avec Supprimer les données.

Chaque étape (installation, mise à jour, droits, appels sensibles) est inscrite au journal d’audit.

Un plugin est un dossier avec un manifeste et des pages web statiques :

mon-plugin/
manifest.json
index.html
app.js
styles.css

manifest.json décrit le plugin et ce qu’il demande :

{
"id": "suivi-colis",
"name": "Suivi des colis",
"version": "1.0.0",
"author": "Atelier Exemple",
"kiwidesk": "^0.2.0",
"permissions": ["repair:tickets:read", "plugin:storage"],
"ui": {
"recordTabs": [{ "id": "colis", "record": "ticket", "label": "Colis", "entry": "index.html" }]
}
}
Champ Rôle
id Identifiant unique : minuscules, chiffres et tirets.
name, author Affichés à l’installation.
version Version stricte (1.2.0) ; une mise à jour doit être plus récente.
kiwidesk Versions de KiwiDesk compatibles (^1.0.0, >=0.2.0 <1.0.0).
permissions Permissions utilisées (codes de Rôles et permissions) et plugin:storage.
ui.navigation Entrée du menu et page complète.
ui.recordTabs Onglet d’une fiche : record vaut ticket, customer, invoice, refurbishedUnit ou stockItem.
ui.recordActions Bouton d’une fiche, qui ouvre le plugin dans une fenêtre.
ui.dashboardWidgets Widget du tableau de bord.
events Événements envoyés au serveur du plugin (webhooks signés HMAC-SHA256).
server.webhookUrl Adresse publique du serveur du plugin (facultatif).
settings.schema Fichier JSON des réglages : text, number, boolean, select, secret.

Pas de script dans le HTML : le code est dans app.js, chargé en module, qui importe le SDK de KiwiDesk copié à côté.

import { connect } from "./kiwidesk-plugin-sdk.js";
const kiwidesk = await connect();
const { record } = kiwidesk.context; // { type: "ticket", id: "..." } dans un onglet de ticket
const ticket = await kiwidesk.api.get(`/repair/tickets/${record.id}`);
await kiwidesk.toast(`Ticket ${ticket.number}`, "success");

Le SDK donne aussi kiwidesk.can(...), confirm, prompt, openRecord, print, navigate, storage et refresh. La page ne peut ni lire le jeton de l’utilisateur, ni ouvrir de fenêtres du navigateur, ni appeler une autre adresse que son propre serveur.

Depuis le dépôt KiwiDesk :

Fenêtre de terminal
pnpm --filter @kiwidesk/plugin-sdk build
node examples/plugins/zip-plugin.mjs chemin/vers/mon-plugin

Le script copie le SDK, garde les fichiers acceptés (HTML, JS, CSS, JSON, images, polices) et écrit dist/<id>-<version>.zip, à installer comme ci-dessus. L’exemple complet examples/plugins/hello-ticket ajoute un onglet aux tickets. La conception détaillée (sécurité, routes ouvertes, serveur et webhooks) est décrite dans docs/plugins.md du dépôt.

  • « Le paquet dépasse 10 Mo » : allégez les images du plugin.
  • Badge Incompatible : le plugin demande une autre version de KiwiDesk que celle installée. Demandez une mise à jour à son auteur.
  • « Cette adresse pointe vers le réseau local » : le serveur du plugin doit avoir une adresse publique.
  • « Plugin indisponible » dans une page : le plugin n’a pas répondu en 10 secondes. Réessayer, sinon désactivez-le et contactez son auteur.
  • « Plugin arrêté » : le cadre du plugin a tenté de charger une autre page ; KiwiDesk l’a fermé et l’a inscrit au journal d’audit.