Intégrer, personnaliser et facturer Findy
Cette page rassemble les informations nécessaires pour installer le widget, connecter le catalogue, régler le style, comprendre les tarifs et expliquer la consommation des requêtes à un client ou à une équipe technique.
Produit
Vue d'ensemble
Recherche
Style
Tarifs
Usage
Source de vérité
Snippet
Installation rapide
Poser le conteneur à l'endroit où la recherche doit apparaître, charger le script avant</body>, puis appeler Findy.init. Remplacer VOTRE_CLE_WIDGET_FINDY par la clé widget du client.
<div id="findy-search"></div>
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
containerId: 'findy-search',
apiBaseUrl: 'https://findysearch.com'
});
</script>- Récupérer l'URL publique Findy, généralement https://findysearch.com.
- Créer ou récupérer la clé widget du client dans le dashboard.
- Vérifier que le catalogue est connecté ou en cours de synchronisation.
- Tester desktop, mobile, clic produit, ajout panier et remontée analytics.
- Ne jamais exposer de clés WooCommerce, PrestaShop ou API serveur dans le code du site marchand.
Findy.init
Options JavaScript
| Option | Type | Rôle |
|---|---|---|
| apiKey | string, requis | Clé widget publique qui identifie l'organisation Findy. |
| lang | string | Langue de l'interface et des résultats : fr, en, es, it, de. Valeur 'auto' pour la lire depuis l'attribut lang de la page. Sans cette option, le widget reste en français. |
| translations | objet | Surcharge de libellés, par exemple { 'product.addToCart': 'Acheter' }. Les valeurs sont échappées avant insertion. |
| containerId | string | ID du conteneur où Findy rend sa barre de recherche. |
| triggerSelector | string | Sélecteur CSS d'un champ ou bouton existant qui ouvre Findy. |
| mobileTriggerSelector | string | Sélecteur spécifique mobile si le thème utilise un DOM différent. |
| triggerMode | searchbar ou selector | Force le comportement d'ouverture souhaité. |
| apiBaseUrl | string | URL de l'instance Findy à appeler. |
| logoUrl, logoText | string | Branding optionnel si la configuration serveur ne définit pas déjà le logo. |
| popularSearches | string[] | Suggestions de secours côté client. |
| adaptive | boolean | Laisse Findy adapter le mode d'affichage selon le contexte. |
| closeOnClickOutside, closeOnEscape | boolean | Contrôle de fermeture de l'overlay. |
| priceMode | auto, net ou gross | Suit le sélecteur HT/TTC du site ou propose un mode local; une règle fixe définie dans Findy reste prioritaire. |
| priceModeDetector | function | Détection personnalisée du mode HT/TTC pour une plateforme headless ou propriétaire. |
| onContextChange | function(context) | Callback appelé en mode adaptive quand le contexte viewport change. |
| onAddToCart | async function(params) | Intégration panier custom côté site marchand. |
Synchroniser le choix HT / TTC du site
En mode auto (valeur par défaut), Findy détecte le réglage natif PrestaShop. Sur toute autre plateforme, placezdata-findy-price-mode="net" oudata-findy-price-mode="gross" sur la balisehtml. Après un changement sans rechargement, appelezFindy.setPriceMode('net') ou émettez l’événementfindy:price-mode-change. Les résultats et filtres prix sont alors rechargés dans la bonne base.
Cette API constitue le bridge universel pour WooCommerce, Shopify, Magento, BigCommerce, Shopware, un site headless ou un switcher propriétaire. Findy ne cherche pas le bouton HT/TTC dans le DOM : le site lui transmet son état. UtilisezFindy.getPriceModeDiagnostics() pour connaître le mode, la source détectée et savoir si le fallback est utilisé.
Pendant l’installation, démarrez d’abord une fenêtre de test depuis l’onboarding ou les paramètres. Rechargez ensuite le site, ouvrez-le une fois dans chaque mode, puis confirmez explicitement le contrôle avec un compte administrateur. La fenêtre expire après 30 minutes et chaque nouveau test crée une révision différente. Une clé widget publique ne peut pas valider seule cette étape.
Exemple avec événements publics
Les événements de lecture se branchent avec Findy.on aprèsFindy.init. Les callbacks d'analyticsonSearch et onProductClick ne font pas partie du contrat public actuel.
<script>
Findy.on('open', function() {
console.log('Findy opened');
});
Findy.on('searchStart', function(event) {
console.log('Findy search:', event.query);
});
Findy.on('searchComplete', function(event) {
console.log('Findy results:', event.total);
});
Findy.on('addToCartSuccess', function(event) {
console.log('Findy add to cart:', event.productId);
});
</script>Design
Style et personnalisation
Le style du widget est configuré côté Findy et livré au widget via l'API de configuration. Le site marchand garde uniquement le snippet d'intégration; les équipes peuvent donc ajuster le design sans redéployer le thème.
| Réglage | Valeurs | Impact |
|---|---|---|
| Template | MINIMAL, ELEGANT, BOLD, ECOMMERCE | Base visuelle du widget. |
| Couleurs | primaryColor, buttonColor, buttonTextColor, iconColor, badgeColor, availabilityLabelColor, inStockLabelColor | Couleurs principales, boutons, icônes d'action, promotions et délais de disponibilité. |
| Typographie | fontFamily, fontBold, fontItalic, priceFontBold, priceFontItalic, buttonFontBold, buttonFontItalic, titleFontSize, refFontSize, priceFromFontSize, priceValueFontSize, priceTaxFontSize | Police, styles gras/italique par zone et tailles indépendantes pour « À partir de », la valeur du prix et la mention fiscale. |
| Rayon | borderRadius de 0 à 32 | Arrondi des champs, cartes et boutons. |
| Logo | logoUrl | Logo client dans l'overlay de résultats. |
| Disposition | layoutMode: grid ou slider | Affichage produits en grille ou carrousel. |
| Fenêtre | windowMode: fullscreen, compact, megamenu | Comportement de l'overlay sur desktop. |
| Volume affiché | 10, 20, 50, 100 ou scroll infini | Nombre de produits demandés par page. |
| Grille | gridColumns: auto ou 2 à 8 | Contrôle du nombre de colonnes desktop. |
| Design par élément | design (JSON v1), mode Avancé de l'onglet Design | Réglages par élément (Offres & sélections, grille, carte, image, badges, textes, boutons), par appareil et au survol, et ordre des blocs de la carte. Passe devant les réglages ci-dessus. |
| Commerce | addToCartBehavior, showQuantitySelector, showVariantSelector, uniformProductButtons | Après un ajout réussi : REDIRECT_TO_CART, SHOW_POPUP ou CONTINUE_SHOPPING. uniformProductButtons applique les couleurs configurées à toutes les actions produit (désactivé par défaut). Les anciens champs showCartPopup et closeOnAddToCart restent compatibles mais sont dépréciés. |
Templates disponibles
Comportement mobile
Conseil de recette design
Thème de la boutique
Plans
Tarifs publics et requêtes incluses
| Plan | Abonnement | Requêtes incluses / mois | Hors forfait | Assistant IA | Usage conseillé |
|---|---|---|---|---|---|
| Free | 0 € | 1 000 | 0 € | Non inclus — disponible dès Starter | Pour découvrir Findy gratuitement |
| Starter | 29 €/mois | 10 000 | 0,0050 €/requête | Inclus — chaque conversation vaut 10 requêtes | Idéal pour les petites boutiques qui démarrent |
| Pro | 99 €/mois | 150 000 | 0,0040 €/requête | Inclus — 250 conversations/mois, puis 10 requêtes par conversation | Pour les boutiques en croissance |
| Business | 199 €/mois | 400 000 | 0,0030 €/requête | Inclus — 500 conversations/mois, puis 10 requêtes par conversation | Pour les grandes boutiques à fort trafic |
Offres commerciales
Usage
Consommation des requêtes
Le compteur Findy est conçu pour refléter les interactions qui ont une valeur produit: recherche, clic et ajout panier. Les appels techniques nécessaires au chargement du widget ne sont pas tous facturés, mais certains vérifient le quota pour éviter de servir une expérience inactive.
| Action | Consomme ? | Détail |
|---|---|---|
| Recherche produit | Oui | 1 requête par appel à /api/widget/search, y compris pagination, filtres et scroll infini. |
| Clic produit | Oui | 1 requête quand l'événement CLICK est traité et que le quota est disponible. Au-delà de 10 clics d'un même visiteur sur un même produit dans la journée, les suivants ne sont ni enregistrés ni facturés : ils ne relèvent plus d'un comportement humain et fausseraient le classement. |
| Ajout panier | Oui | 1 requête quand l'événement ADD_TO_CART est traité. Selon le bouton et le template, un CLICK produit peut aussi être enregistré avant l'ajout panier. Un même appel au serveur facture au plus 3 clics et ajouts panier : le widget envoie chaque clic dès qu'il a lieu, et les événements au-delà restent comptés dans les statistiques sans être facturés. |
| Conversation avec l'assistant IA | Oui, au-delà de l'inclus | 10 requêtes par conversation, débitées à la première réponse ; les messages suivants de la même conversation ne coûtent rien. Free n'ouvre pas l'assistant ; Starter l'ouvre sans volume inclus, chaque conversation est décomptée du quota ; Pro inclut 250 conversations par période de facturation et Business 500, hors quota. Une conversation ouverte sans réponse n'est jamais comptée. Un plafond mensuel de conversations, réglable dans le dashboard, met l'assistant en pause au-delà. |
| Configuration widget | Non | Charge le design et les réglages serveur. Ne décrémente pas le quota. |
| Trending, recherches populaires, catégories, collections | Non direct | Vérifie le quota pour éviter de servir le widget sans crédit, mais ne décrémente pas directement. |
| OPTIONS CORS | Non | Préflight navigateur ignoré par la facturation et par le quota fonctionnel. |
Ordre de consommation
Hors forfait
Blocage
Cas du bouton panier
CLICK puisADD_TO_CART. Une sélection de variante validée dans la fenêtre de variante ne déclenche que l'ajout panier.Prix
Calcul de la facture
Le prix mensuel est la somme de l'abonnement et de la consommation hors forfait. Les requêtes incluses et bonus déjà disponibles ne génèrent pas de coût supplémentaire.
requêtes_disponibles = requêtes_plan_restantes + requêtes_bonus
requêtes_hors_forfait = overageRequestsThisPeriod
coût_hors_forfait = requêtes_hors_forfait x tarif_pay_as_you_go
total_mensuel = abonnement_mensuel + coût_hors_forfait| Plan | Scénario | Calcul |
|---|---|---|
| Free | 1 200 interactions facturables | Les 1 000 premières passent, puis le widget est bloqué. Pas de hors-forfait. |
| Starter | 12 500 interactions facturables | 29 € + 2 500 x 0,0050 € = 41,50 €. |
| Pro | 180 000 interactions facturables | 99 € + 30 000 x 0,0040 € = 219 €. |
| Business | 450 000 interactions facturables | 199 € + 50 000 x 0,0030 € = 349 €. |
| Pro + assistant IA | 350 conversations | Les 250 premières sont incluses ; les 100 suivantes valent 100 x 10 = 1 000 requêtes, prises sur le quota du plan (0 € tant que les 150 000 requêtes ne sont pas dépassées, sinon 0,0040 € l'une). |
- Le compteur mensuel d'usage s'appuie sur le compteur interne et les événements du mois en cours.
- Les requêtes bonus sont séparées du quota du plan et consommées en priorité.
- Les dépassements sont comptés dans overageRequestsThisPeriod.
- La date de reset affichée vient de la période d'abonnement Stripe.
- En cas de paiement suspendu sur un plan payant, l'accès peut être bloqué même si des compteurs existent.
CMS
Installation WooCommerce
Accès catalogue
Dans WordPress, aller dansWooCommerce > Réglages > Avancé > REST API, créer une clé dédiée Findy avec l’accès Lecture uniquement, puis copier leConsumer Key et le Consumer Secret. Dans Findy, renseigner l'URL de la boutique, tester la connexion, puis synchroniser.
Recherche existante du thème
Si le client veut conserver le champ de recherche du thème WooCommerce, utiliser un sélecteur CSS adapté au DOM desktop et mobile.
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
apiBaseUrl: 'https://findysearch.com',
triggerSelector: '.woocommerce-product-search, input[type="search"]',
mobileTriggerSelector: '.mobile-search input[type="search"]'
});
</script>Panier WooCommerce
- Tester l'ajout panier sur un produit simple.
- Tester un produit variable avec tailles ou couleurs.
- Vérifier la mise à jour du mini-panier ou du compteur panier.
- Tester les boutiques en sous-répertoire, multisite ou contexte multilingue.
- Utiliser onAddToCart si le thème est fortement personnalisé ou headless.
CMS
Installation PrestaShop
Accès catalogue
Dans PrestaShop, aller dans Paramètres avancés > Webservice, activer le Webservice et créer une clé Findy avec des permissions de lecture.
| Bloc | Permissions | Note |
|---|---|---|
| Catalogue | products, categories, images, stock_availables | Base minimale pour indexer les produits. |
| Déclinaisons | combinations | Recherche par référence de déclinaison. |
| Fonctionnalités | specific_prices, product_features, product_feature_values, tags | Prix spécifiques, filtres et enrichissement. |
- Ne pas accorder de droits d'écriture.
- Ne pas activer
orders,customersou d'autres ressources sensibles si elles ne sont pas nécessaires. - Renseigner le taux de TVA uniquement si les prix PrestaShop remontent hors taxes. Exemple:
20.
Recherche existante du thème
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
apiBaseUrl: 'https://findysearch.com',
triggerSelector: '#search_widget form, #search_widget input[type="text"]',
mobileTriggerSelector: '.header-mobile #search_widget input'
});
</script>Panier PrestaShop
Findy reconnaît les URL d'ajout panier PrestaShop générées lors de la synchronisation. Pour les produits à déclinaisons, le sélecteur transmet automatiquement l'identifiant natifid_product_attribute. La clé Webservice doit autoriser la lecture des combinaisons, groupes d'options et valeurs d'options.
CMS
Installation Shopify
En attendant l'application Shopify Findy, l'intégration passe par le canal de vente gratuit Headless de Shopify : Findy lit le catalogue côté serveur via l'API Storefront GraphQL avec un jeton d'accès privé, le widget est collé dans le thème de la boutique en ligne et l'ajout panier utilise les API panier de Shopify. L'abonnement Findy reste facturé par Findy.
Intégration transitoire
Accès catalogue
Installer le canal Headless (édité par Shopify, gratuit) depuis le Shopify App Store avec un compte qui a la permission Applications et canaux de vente, cliquer sur Create storefront, vérifier que les trois permissions de lecture ci-dessous sont cochées dans Storefront API permissions, puis copier le Private access token. Avant de décocher quoi que ce soit : ces permissions sont communes à tous les storefronts Headless de la boutique. Si le canal ne sert qu'à Findy, décocher toutes les autres. S'il sert déjà à un autre site du marchand, ne rien retirer (cet autre site cesserait de fonctionner) : le jeton Findy hérite alors aussi de ses permissions supplémentaires.
| Permission Storefront API | Usage | Note |
|---|---|---|
| unauthenticated_read_product_listings | Produits, variantes et collections | Base minimale pour indexer le catalogue. |
| unauthenticated_read_product_tags | Tags produits | Enrichissement de la recherche. |
| unauthenticated_read_product_inventory | Quantités en stock | Stock des produits et des variantes. |
- Rendre les produits disponibles sur le storefront Headless et sur la
Boutique en ligne: l'API Storefront ne renvoie que les produits publiés sur Headless, et le panier du thème exige la Boutique en ligne. Publié seulement sur Headless, un produit apparaît dans Findy mais son ajout au panier est refusé (« Ajout non confirmé ») ; publié seulement sur la Boutique en ligne, il n'est jamais trouvé par Findy. - Findy n'utilise jamais le jeton public du storefront.
Jeton privé = secret serveur
Connexion dans Findy
Choisir Shopify et renseigner l'adresse https://boutique-client.myshopify.com (visible dans Paramètres > Domaines de l'admin Shopify) : un domaine personnalisé est refusé, une URL admin.shopify.com/store/… est convertie automatiquement. Coller le Jeton d’accès privé Storefront API et laisser vide le chemin de la page panier : sur la boutique, le widget ouvre alors le panier de la langue courante (/cart, /fr/cart… d'après Shopify.routes.root), sans tenir compte des liens du thème. Un autre chemin saisi est utilisé tel quel. Tester la connexion puis synchroniser. La loupe de détection reconnaît une adresse .myshopify.com, une URL d'admin Shopify et en général une boutique sur son propre domaine ; si elle propose une autre plateforme, choisir alors Shopify à la main.
- Findy lit les produits, variantes, images, prix, prix barrés, disponibilité, stock, type de produit, collections, tags, marque (vendor), SKU et codes-barres.
- Les cartes-cadeaux sont exclues ; les produits brouillons, archivés ou non publiés sur Headless ne sont pas renvoyés par Shopify.
- La disponibilité suit l'état « disponible à la vente » de Shopify : un produit sans suivi de stock reste disponible.
- Boutique multilingue : les URL produits reprennent le préfixe de langue et le handle traduit.
- Comparer ensuite quelques prix, variantes et prix barrés avec les fiches Shopify.
Widget dans le thème
Dans Boutique en ligne > Thèmes > Personnaliser, ajouter une section Liquid personnalisé dans le groupe en-tête ou pied de page, pour qu'elle s'affiche sur toutes les pages, puis coller le snippet. Autre option : Modifier le code > layout/theme.liquid, avec le script avant </body>. Modifier le code retire le thème des mises à jour automatiques : préférer le bloc Liquid personnalisé et tester d'abord sur une copie non publiée du thème.
<div id="findy-search"></div>
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
containerId: 'findy-search',
apiBaseUrl: 'https://findysearch.com'
});
</script>Recherche existante du thème
Exemple pour le thème Dawn, à adapter au DOM réel du thème. Vérifier que la recherche native ne s'ouvre pas en même temps que Findy.
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
apiBaseUrl: 'https://findysearch.com',
triggerSelector: '.header__icon--search, predictive-search input[type="search"]'
});
</script>Compte collaborateur
Le marchand ouvre Paramètres > Utilisateurs > Sécurité et transmet le code de demande de collaborateur à 4 chiffres. Le prestataire envoie sa demande depuis son compte partenaire Shopify avec le domaine boutique-client.myshopify.com et ce code, puis le marchand relit les permissions et accepte la demande.
| Permission | Usage | Note |
|---|---|---|
| Applications et canaux de vente | Installer et gérer le canal Headless | Nécessaire pour créer le storefront et lire le jeton privé. |
| Boutique en ligne > Thèmes | Ajouter le widget au thème | Dupliquer le thème pour tester sur une copie non publiée. |
| Produits | Recette et publication sur les canaux | La lecture suffit si le marchand publie lui-même les produits. |
- Ne jamais demander un rôle administrateur ou toutes les permissions.
- Le compte du prestataire doit avoir l'authentification en deux étapes activée : sans 2FA, un collaborateur ne peut pas se connecter à la boutique.
- Ne pas demander l'accès aux commandes, clients ou paiements ; le marchand retire l'accès en fin d'intervention.
Panier Shopify
Findy ajoute la variante au panier dans la boutique, avec la session du visiteur. Il utilise Shopify.actions.updateCart quand les actions standard Shopify sont disponibles : Shopify rafraîchit alors le compteur ou le drawer des thèmes qu'il reconnaît. Sinon, Findy appelle l'API AJAX Cart (/cart/add.js) en suivant window.Shopify.routes.root, puis émet cart:refresh et cart:updated. Un produit à plusieurs variantes passe par le sélecteur de variante ou par la fiche produit.
En secours, onAddToCart remplace complètement ce flux natif, par exemple pour une app de panier tierce. Le panier Shopify attend l'identifiant numérique de variante, pas l'identifiant produit.
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
containerId: 'findy-search',
apiBaseUrl: 'https://findysearch.com',
onAddToCart: async function({ variationId, quantity, addToCartUrl }) {
// Variante choisie dans Findy, sinon variante par défaut du lien panier /cart/<variante>:1
var cartPath = addToCartUrl ? new URL(addToCartUrl, window.location.href).pathname : '';
var variantId = Number(variationId || (cartPath.split('/cart/')[1] || '').split(':')[0]);
if (!variantId) {
return { success: false };
}
var root = (window.Shopify && window.Shopify.routes && window.Shopify.routes.root) || '/';
var response = await fetch(root + 'cart/add.js', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json'
},
credentials: 'same-origin',
body: JSON.stringify({
items: [{ id: variantId, quantity: quantity || 1 }]
})
});
// Rafraîchir ici le compteur ou le drawer du thème, y compris en cas de 422 :
// si le stock est insuffisant, Shopify a pu ajouter la quantité disponible.
return { success: response.ok };
}
});
</script>- Tester un produit à variante unique et un produit à variantes.
- Variante épuisée ou quantité supérieure au stock : vérifier le contenu réel du panier, pas seulement le message Findy. Shopify peut ajuster la quantité au stock disponible (avertissement avec
Shopify.actions, réponse422, parfois après un ajout partiel, avec/cart/add.js). - Si le compteur ou le drawer ne se met pas à jour, choisir
REDIRECT_TO_CARTou brancheronAddToCart. - Tester les boutiques multilingues ou multi-marchés (/fr/, /en-us/) et les apps de panier tierces.
Prix HT / TTC
L'API Storefront ne dit pas si les prix incluent les taxes : choisir dans Findy Le prix source est TTC ou Le prix source est HT selon le réglage de taxes de la boutique. Comme pour WooCommerce, l'affichage suit le bridge universel décrit dans les options JavaScript : le thème initialise data-findy-price-mode depuis Liquid, avant le script Findy, et un switcher HT/TTC appelle Findy.setPriceMode('net') ou Findy.setPriceMode('gross'). Vérifier avec Findy.getPriceModeDiagnostics(), puis valider la fenêtre de test dans l'onboarding.
<script>
document.documentElement.dataset.findyPriceMode = {% if cart.taxes_included %}'gross'{% else %}'net'{% endif %};
</script>| Limite | Impact | Contournement |
|---|---|---|
| Synchronisation horaire | Une modification produit, prix ou stock peut mettre jusqu'à une heure à apparaître. | Lancer une synchronisation manuelle depuis Findy après un changement important. |
| Pas d'extension de thème | Tant qu'il n'y a pas d'app Findy, le snippet est lié au thème et disparaît lors d'un changement de thème. | Reposer la section Liquid personnalisé sur le nouveau thème avant sa publication. |
| Boutique protégée par mot de passe | La synchronisation fonctionne, mais le widget et les liens panier restent derrière le mot de passe. | Saisir le mot de passe de la boutique dans le navigateur pour la recette. |
| Canaux de vente | Seuls les produits publiés sur Headless sont synchronisés, et seuls ceux publiés sur la Boutique en ligne peuvent être ajoutés au panier. | Publier aussi les nouveaux produits sur les deux canaux. |
| Plus de 25 000 produits | Limite de pagination Shopify : la synchronisation s'arrête avec une erreur, sans supprimer de produits. | Contacter l'équipe Findy. |
| Jeton privé | Désinstaller le canal, supprimer le storefront ou supprimer le jeton coupe la synchronisation. | Mettre à jour le jeton dans Findy puis relancer une synchronisation. |
CMS
Installation Magento
Findy lit le catalogue côté serveur avec l'API REST d'administration de Magento Open Source ou Adobe Commerce 2.4, authentifiée par le jeton d'une intégration Magento. Findy n'installe rien dans Magento : le marchand crée l'intégration et colle le script du widget dans l'en-tête de sa vue magasin.
1. Connecter la boutique
- Dans l’admin Magento, ouvrez Système > Extensions > Intégrations, puis « Ajouter une nouvelle intégration » et nommez-la Findy.
- Dans l’onglet API, choisissez des ressources personnalisées : Catalogue, Magasins (paramètres et configuration, dont la section Inventaire) et, si elle existe, Inventaire (dont Stock de vente : sans lui, Findy n’indexe pas les quantités en stock). Enregistrez.
- Activez l’intégration (Enregistrer, Activer, Autoriser), puis copiez le jeton d’accès (Access Token).
- Dans Magasins > Configuration > Services > OAuth > Consumer Settings, passez « Allow OAuth Access Tokens to be used as standalone Bearer tokens » sur Oui (désactivé par défaut depuis Magento 2.4.4).
Dans Findy, choisir Magento, saisir l'URL de base de la vue magasin à indexer (Magasins > Configuration > Général > Web) et coller le jeton, puis tester la connexion et synchroniser. Le jeton se colle uniquement dans Findy, jamais dans l'en-tête de la boutique ni dans le script du widget.
2. Installer le widget
- Dans l'admin, ouvrir
Contenu > Design > Configurationet modifier la vue magasin (ou le site) concerné. - Dans
En-tête HTML > Scripts et feuilles de style, coller le script Findy ci-dessous, puis enregistrer. - Ouvrir
Système > Gestion du cacheet cliquer surVider le stockage du cache(Flush Cache Storage) : sans cela, la vitrine garde l'ancien en-tête.Purger le cache Magentone vide pas toujours le cache des pages. - Ouvrir une page catalogue de la boutique et vérifier que la recherche s'ouvre.
Recommandé : ouvrir Findy depuis la recherche de l'en-tête Magento, en mode sélecteur CSS sur #search, #menu-search-icon : soit dans Findy (Design > Mode de déclenchement), puis copier le script de l'installation, soit avec le code ci-dessous, qui fixe ce sélecteur sur la vitrine (un sélecteur changé plus tard dans Design ne s'y appliquera pas). #search est le champ de recherche de l'en-tête Luma ; #menu-search-icon est l'icône de recherche de l'en-tête Hyvä, dont le champ reste caché tant qu'on ne l'a pas cliquée. Testé sur Luma et Hyvä 1.5.4 (Magento 2.4.9).
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
apiBaseUrl: 'https://findysearch.com',
triggerSelector: '#search, #menu-search-icon'
});
</script>Sinon, la barre de recherche Findy : placer <div id="findy-search"></div> dans un bloc CMS, un widget « Bloc HTML » ou Contenu > Design > Configuration > Pied de page > HTML divers.
<div id="findy-search"></div>
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
containerId: 'findy-search',
apiBaseUrl: 'https://findysearch.com'
});
</script>Panier Magento
Le widget ajoute au panier Magento natif de la vitrine, avec la session du visiteur : produits simples et configurables en stock. Les produits groupés, les bundles et les produits à options personnalisées obligatoires ouvrent leur fiche produit. Après l'ajout, le mini-panier se recharge sur les thèmes Luma et Hyvä.
Prix et stock
Findy lit le prix final et le stock vendable comme un visiteur non connecté de chaque vue magasin, par l'API GraphQL publique de la vitrine : règles de prix catalogue, prix spéciaux datés et stock multi-sources (MSI) sont appliqués par Magento. Un produit que la vitrine masque (rupture de stock) reste dans Findy, hors stock. Le réglage HT ou TTC de Findy s'applique au prix saisi dans l'admin : si la vitrine affiche un autre prix normal (catalogue affiché TTC, taxe fixe), la synchronisation s'arrête en nommant le produit plutôt que de compter la taxe deux fois.
Pages de paiement et CSP
Après la mise en place
| Limite | Impact | Contournement |
|---|---|---|
| Prix des clients connectés | Seuls les prix invités sont lus : prix par groupe de clients, par paliers et prix B2B ne sont pas indexés. | Aucun : le client connecté voit son prix sur la fiche produit et au panier. |
| Règles de prix catalogue | Magento les applique depuis un index mis à jour par son cron : sans cron actif, une règle nouvelle ou arrivée à sa date n'apparaît ni sur la vitrine ni dans Findy. | Vérifier que le cron Magento tourne, puis lancer une synchronisation Findy. |
| Produits non visibles individuellement | Absents de l'API de la vitrine, ils gardent le prix et le stock de l'API REST (sans règle catalogue ni MSI). | Aucun : ils ne s'affichent pas seuls sur la vitrine. |
| Catalogue affiché TTC | Si la vitrine affiche les prix du catalogue TTC ou avec une taxe fixe (FPT), la synchronisation s'arrête : Findy ne peut pas savoir si la taxe est comprise. | Afficher les prix du catalogue hors taxe (Magasins > Configuration > Ventes > Taxes), ou contacter Findy. |
| Vitrine fermée aux visiteurs | Catalogues partagés B2B ou droits de catégorie : la vitrine ne montre rien aux invités, tous les produits sont indexés hors stock. | Aucun pour l'instant : ouvrir le catalogue aux invités. |
| Devise d'affichage | Les prix sont lus dans la devise de base de la vue magasin, sans conversion vers une autre devise d'affichage. | Aucun pour l'instant. |
| Thèmes Hyvä | Le mini-panier se recharge par l'événement de Hyvä (vérifié sur Hyvä 1.5.4). Un module tiers qui charge RequireJS sur une page Hyvä la fait traiter comme une page Luma. | Recharger la page si le mini-panier ne se met pas à jour, et le signaler à Findy. |
| Synchronisation | Pas de temps réel : une modification peut mettre un moment à apparaître. | Lancer une synchronisation manuelle depuis Findy après un changement important. |
API
Installation custom ou headless
Utiliser ce mode pour les sites Next.js, Nuxt, React, Vue, Svelte, les paniers internes ou les frontends découplés. Dans Findy, choisir Site custom / API, renseigner un endpoint catalogue HTTPS, puis valider avec l'équipe Findy comment les produits et le panier sont connectés.
- Exposer un endpoint JSON stable, public côté serveur Findy mais protégé par token.
- Retourner les champs requis: externalId, name, price, url et inStock.
- Utiliser une pagination cursor via nextCursor et hasMore pour les catalogues volumineux.
- Vérifier que productId et variationId correspondent aux identifiants attendus par l'API panier.
- Définir la stratégie des variantes: ajout direct, sélecteur de variante ou redirection fiche produit.
- Sur une SPA, initialiser Findy côté client après le montage du champ cible et éviter les doubles initialisations.
Contrat catalogue custom
L'endpoint configuré dans Findy doit répondre en application/json. Findy ajoute les paramètres limit et cursor à l'URL, sauf configuration spécifique. L'authentification utilise par défautAuthorization: Bearer VOTRE_TOKEN.
{
"items": [
{
"externalId": "sku-123",
"sku": "SKU-123",
"gtins": ["3760123456784"],
"name": "Chaussure de running",
"description": "Modele leger pour entrainement quotidien",
"price": 89.9,
"originalPrice": 109.9,
"currency": "EUR",
"imageUrl": "https://boutique.example/products/sku-123.jpg",
"categories": ["Running", "Chaussures"],
"brand": "Acme",
"tags": ["nouveaute", "route"],
"inStock": true,
"stockQuantity": 42,
"url": "https://boutique.example/products/sku-123",
"addToCartUrl": "https://boutique.example/cart/add?sku=sku-123",
"variantAttributes": [
{ "name": "Taille", "slug": "taille", "values": ["40", "41"] }
],
"variants": [
{
"id": "sku-123-40",
"sku": "SKU-123-40",
"name": "Taille 40",
"price": 89.9,
"inStock": true,
"attributes": { "Taille": "40" }
}
]
}
],
"hasMore": true,
"nextCursor": "page-2",
"total": 240
}Mode sélecteur CSS
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
apiBaseUrl: 'https://findysearch.com',
triggerSelector: '#site-search, .js-open-search'
});
</script>Panier custom
Le contrat catalogue synchronise les produits; onAddToCart branche l'action panier côté site marchand. Adapter data.success au format réel de l'API panier. Ne pas considérer un HTTP 200 comme une réussite si l'API peut retourner une erreur métier dans le JSON.
<script src="https://findysearch.com/widget-v2/findy-widget.js"></script>
<script>
Findy.init({
apiKey: 'VOTRE_CLE_WIDGET_FINDY',
apiBaseUrl: 'https://findysearch.com',
triggerSelector: '#site-search',
onAddToCart: async function({
productId,
variationId,
quantity,
selectedAttributes,
product,
variant,
price,
currency,
query,
collectionSlug
}) {
var csrfToken = window.CSRF_TOKEN;
if (!csrfToken) {
throw new Error('Missing CSRF token');
}
var response = await fetch('/api/cart/add', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': csrfToken
},
credentials: 'include',
body: JSON.stringify({
productId: productId,
variationId: variationId || null,
quantity: quantity || 1,
selectedAttributes: selectedAttributes || {},
sku: variant?.sku || product?.sku || null,
price: price || null,
currency: currency || 'EUR',
findyContext: {
query: query || null,
collectionSlug: collectionSlug || null
}
})
});
if (!response.ok) {
return { success: false };
}
var data = await response.json().catch(function() {
return {};
});
return { success: data.success === true };
}
});
</script>- L'API panier doit revalider côté serveur l'existence du produit et de la variante.
- Les quantités, attributs, permissions utilisateur, stock et prix doivent être validés côté serveur.
- La fonction doit transmettre le token CSRF, nonce ou jeton anti-fraude attendu.
- Le site reste responsable de la mise à jour du mini-panier ou drawer panier après succès.
- Ne jamais mettre de secrets serveur dans ce JavaScript.
Déclencher Findy manuellement
<button type="button" id="findy-open-button">Rechercher</button>
<script>
document.getElementById('findy-open-button')?.addEventListener('click', function() {
Findy.open();
});
</script>Sécurité
Sécurité, CSP et limites opérationnelles
Clé widget
CORS et préflight
- Autoriser le script Findy dans script-src, par exemple https://findysearch.com.
- Autoriser les appels API Findy dans connect-src.
- Charger Findy.init avec un nonce CSP, un hash CSP ou un fichier JavaScript du site déjà autorisé.
- Prévoir style-src pour les styles injectés et fonts.googleapis.com si la police Google configurée est utilisée.
- Prévoir font-src pour fonts.gstatic.com et img-src pour les images produits ou CDN.
- Si une URL versionnée et un attribut integrity sont fournis, les utiliser avec crossorigin="anonymous".
Recette
Validation après installation
- Le script findy-widget.js se charge sans erreur dans l'onglet Network.
- La console navigateur ne contient pas d'erreur Findy is not defined.
- La barre Findy ou le déclencheur CSS ouvre l'overlay.
- Une recherche affiche des produits synchronisés.
- Les filtres, les tris et la pagination ou le scroll infini fonctionnent.
- Les images produits se chargent.
- Le clic produit ouvre la bonne page produit.
- L'ajout panier fonctionne quand il est activé.
- Les variantes produits se comportent comme prévu.
- Le mini-panier ou le compteur panier se met à jour si le thème le gère.
- Les recherches, clics et ajouts panier remontent dans les analytics Findy après quelques minutes.
- La consommation de requêtes correspond au scénario testé.
- La recherche fonctionne sur mobile.
- Les contraintes CSP sont respectées sans ajouter 'unsafe-inline' dans script-src.
Support
Dépannage rapide
| Symptôme | Cause probable | Correction |
|---|---|---|
| Findy is not defined | Script chargé après Findy.init ou bloqué | Charger findy-widget.js avant Findy.init et vérifier la CSP. |
| Rien ne s'affiche | containerId absent, mauvais sélecteur ou élément monté trop tard | Vérifier le DOM, attendre le montage client sur SPA, tester document.querySelector(...). |
| Le clic ne fait rien | Mauvais triggerSelector ou élément remplacé par le thème | Utiliser un sélecteur plus stable ou déclencher Findy.open manuellement. |
| Résultats vides | Catalogue non synchronisé, filtres trop stricts ou produits masqués | Tester la connexion CMS, relancer une synchronisation et vérifier les règles de visibilité. |
| Erreur 401 widget | Clé widget invalide ou révoquée | Récupérer une nouvelle clé widget Findy. |
| Message Plus de requêtes disponibles | Quota épuisé ou abonnement suspendu | Vérifier le plan, les requêtes restantes, le hors-forfait et l'état de paiement. |
| Facture plus élevée que prévu | Clics, ajouts panier ou recherches paginées générant du hors-forfait | Comparer usage mensuel, overageRequestsThisPeriod et tarif pay-as-you-go du plan. |
| Ajout panier instable | Thème ou panier personnalisé | Utiliser onAddToCart et valider stock, variante, prix, CSRF côté serveur. |
| Adresse Shopify refusée | Domaine personnalisé saisi à la place de l'adresse .myshopify.com | Récupérer l'adresse xxx.myshopify.com dans Paramètres > Domaines de l'admin Shopify. |
| Catalogue Shopify vide | Produits non publiés sur le canal Headless | Inclure les produits dans le storefront Headless puis relancer une synchronisation. |
| Connexion Shopify refusée | Jeton public collé à la place du jeton privé, jeton supprimé, canal désinstallé ou permission manquante | Copier le Private access token du storefront Headless, vérifier les trois permissions produit et mettre le jeton à jour dans Findy. |
| Synchronisation Shopify en échec (ACCESS_DENIED) | Permission Storefront API décochée après le test de connexion, ou non vérifiable au test faute de produit publié (tags ou stock) ; le message Findy nomme la permission manquante | Re-cocher les trois permissions unauthenticated_read_product_* du storefront Headless, enregistrer puis relancer la synchronisation. |
| Compteur panier Shopify figé | Le thème ne recharge pas son drawer après un ajout externe | Choisir REDIRECT_TO_CART ou brancher onAddToCart sur la fonction panier du thème. |
| Connexion Magento refusée (401) | Jeton faux ou intégration inactive, option Bearer désactivée, ou ressource API manquante | Vérifier que l'intégration est activée, passer « Allow OAuth Access Tokens to be used as standalone Bearer tokens » sur Oui, et cocher les ressources Catalogue, Magasins et Inventaire. |
| Magento : « Could not create an acl object: Role 'N' not found » | Magento 2.4.9 : après la suppression d'une intégration, l'admin peut échouer tant que le cache n'est pas purgé | Vider le cache : Système > Gestion du cache > Vider le stockage du cache (Flush Cache Storage), ou bin/magento cache:flush. |
| Widget absent sur la vitrine Magento | Cache des pages Magento non vidé après l'ajout du script, ou script collé sur une autre vue magasin | Vider le stockage du cache (Système > Gestion du cache > Flush Cache Storage) et vérifier la vue magasin modifiée dans Contenu > Design > Configuration. |
| Widget absent au paiement Magento | CSP de Magento restreinte sur les pages de paiement | Prévu pour les pages catalogue ; un module d'autorisation CSP est nécessaire pour l'afficher au paiement. |