SitepingConfig est une union discriminée sur les deux modes de transport — endpointoustore, jamais les deux, jamais aucun. TypeScript rejette les combinaisons invalides à la compilation au lieu de vous les laisser découvrir à l'exécution :
initSiteping({ endpoint: "/api/siteping", store, projectName: "x" }); // ✗ les deux modesinitSiteping({ store, apiKey: "sk-…", projectName: "x" }); // ✗ option HTTP en mode storeinitSiteping({ projectName: "x" }); // ✗ aucun transport
Option
Type
Défaut
Ce que ça fait
endpoint
string
—
Mode HTTP. URL de votre API SitePing (ex. /api/siteping)
store
SitepingStore
—
Mode store. Écrit dans un store du navigateur au lieu de faire du HTTP — exclut endpoint, apiKey et headers
projectName
string
—
Obligatoire dans les deux modes. Cadre tout ce que le widget lit et écrit
apiKey
string
—
Mode HTTP uniquement. Envoyé en Authorization: Bearer <clé> sur chaque requête
headers
objet ou fonction
—
Mode HTTP uniquement. En-têtes supplémentaires, statiques ou calculés par requête (sync ou async). Fusionnés en dernier : un Authorization explicite ici l'emporte sur apiKey
Les deux moitiés sont exportées sous les noms SitepingHttpConfig et SitepingStoreConfig — exactement ce qu'il vous faut quand un composant d'enrobage reçoit la config en prop et ne gère qu'un seul mode :
import type { SitepingHttpConfig } from "@siteping/widget";function mountFeedback(config: SitepingHttpConfig) { /* endpoint garanti */ }
apiKey part dans votre bundle client — chaque visiteur peut le lire. Réservez-le aux outils internes déjà protégés par une authentification ; sur un site public, préférez headers avec une fonction qui renvoie un jeton à durée de vie courte.
Contourne les garde-fous production et taille d'écran (jamais celui du SSR)
minViewportWidth
number
0
En dessous de cette largeur, le widget passe son tour avec onSkip("mobile"). La valeur par défaut l'affiche à toutes les largeurs — les téléphones ont droit à la mise en page compacte. Avant la 0.11, elle valait 768 : remettez-la pour tenir le widget à l'écart des téléphones
position
"bottom-right" | "bottom-left"
"bottom-right"
Coin du bouton flottant
showAnnotationsToggle
boolean
true
Mettez false pour retirer le bouton d'affichage des marqueurs du menu radial
Hexadécimal uniquement (#RGB, #RRGGBB, #RRGGBBAA). Les couleurs nommées, rgb(), hsl() etc. affichent un avertissement et retombent sur la valeur par défaut
theme
"light" | "dark" | "auto"
"light"
auto lit la préférence système une seule fois à l'init — un changement de thème de l'OS en cours de session ne re-thème pas le widget
Joint les entrées console récentes (max 50) et les requêtes réseau en échec (max 20, URL enregistrée sans identifiants, query string ni fragment) à chaque feedback. true active les deux ; un objet choisit les canaux et des limites plus basses (maxConsoleEntries / maxNetworkEntries — au-delà, ramenées à 50 / 20, les plafonds du serveur)
deepLink
boolean ou { param?: string }
false
Au premier chargement, met en avant le feedback référencé par ?siteping=<id> (ou votre paramètre personnalisé). Chargement initial uniquement — pour les changements de route, appelez focusFeedback()
identity
{ name, email }
—
Pré-remplit les champs d'auteur depuis la session de l'application hôte (ex. SSO, ou Better Auth) : évite la modale d'identité, jamais persisté dans le localStorage. N'authentifie pas les requêtes API — une politique access côté serveur s'en charge, à partir de votre cookie de session sur la même origine ou d'un bearer envoyé avec headers. Lu à l'init : remontez le widget après un changement de compte
panelActions
tableau
—
Vos propres boutons et liens dans la vue détail d'un feedback — créer un ticket, l'ouvrir dans votre outil de suivi. Voir Actions du panneau
Masque ce qui trie les feedbacks — résoudre, rouvrir, supprimer, les actions groupées, « Tout supprimer ». Créer, parcourir et répondre restent possibles
Pour un client qui relit pendant que votre équipe trie. En plus, le widget masque ce que le serveur interdit à ce visiteur (ses permissions) : un widget public devant une apiKey ne propose aucun bouton qui répondrait 401, même sans readOnly. Dans les deux cas, il ne fait que masquer : c'est le serveur qui décide de ce qu'il accepte.
N'affiche que les marqueurs créés sur la page courante. Filtré côté serveur et côté client, donc les annotations ne peuvent pas fuiter d'une page à l'autre
getPageScope
() => { url, urlPattern }
pathname
Redéfinit ce que « la page courante » veut dire — renvoyez une url stable (et éventuellement un gabarit comme /produits/:id en urlPattern) pour que les routes dynamiques partagent leurs feedbacks
watchNavigation
boolean
true
Recharge les feedbacks lors d'une navigation SPA (patch de l'History API + popstate/hashchange). Données uniquement — ne fait jamais défiler ni ne redonne le focus. Mettez false et appelez refresh() vous-même pour vous en passer
Le cadrage par défaut est window.location.pathname — par construction il ne contient aucune query string, donc les tokens ou paramètres de recherche présents dans l'URL n'atteignent jamais le serveur. Si vous fournissez getPageScope, conservez cette propriété : renvoyez un chemin ou un gabarit, pas location.href.