InstaFixConfig 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 :
initInstaFix({ endpoint: "/api/instafix", store, projectName: "x" }); // ✗ les deux modesinitInstaFix({ store, apiKey: "sk-…", projectName: "x" }); // ✗ option HTTP en mode storeinitInstaFix({ projectName: "x" }); // ✗ aucun transport
Option
Type
Défaut
Ce que ça fait
endpoint
string
—
Mode HTTP. URL de votre API InstaFix (ex. /api/instafix)
store
InstaFixStore
—
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 InstaFixHttpConfig et InstaFixStoreConfig — 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 { InstaFixHttpConfig } from "@instafix/widget";function mountFeedback(config: InstaFixHttpConfig) { /* 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.
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
Capture un JPEG de la zone annotée à l'envoi — voir Captures d'écran
captureDiagnostics
boolean ou objet
false
Joint les entrées console récentes (max 50) et les requêtes réseau (max 20) à chaque feedback. true active les deux ; un objet choisit les canaux et les limites
deepLink
boolean ou { param?: string }
false
Au premier chargement, met en avant le feedback référencé par ?instafix=<id> (ou votre paramètre personnalisé). Chargement initial uniquement — pour les changements de route, appelez focusFeedback()
identity
{ name, email }
—
Pré-remplit l'auteur (applis avec SSO) : évite complètement la modale d'identité, jamais persisté dans le localStorage
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.