Le widget RagWeb est un Custom Element (<ragweb-search>) qui s’intègre sur n’importe quel site avec une seule ligne de code. Il utilise un Shadow DOM fermé pour une isolation CSS complète.
Installation#
Collez ce snippet avant la balise </body> de votre site :
<script src="https://yannick.services/ragweb/widget/v1.js"
data-ragweb-widget
data-api-key="rw_VOTRE_CLE_API"
data-color="#2563eb"
data-position="bottom-right"
data-lang="fr">
</script>Le widget apparaît sous forme d’un bouton rond. Au clic, un panneau de recherche s’ouvre.
Personnalisation (data-attributes)#
| Attribut | Valeur par défaut | Description |
|---|---|---|
data-api-key | (requis) | Clé API RagWeb (commence par rw_) |
data-color | #2563eb | Couleur principale (bouton, accents) |
data-position | bottom-right | Position du bouton : bottom-right, bottom-left, top-right, middle-right |
data-lang | fr | Langue de l’interface : fr ou en |
data-title | “Recherche IA” | Titre affiché en haut du panneau |
data-placeholder | “Posez votre question…” | Placeholder du champ de saisie |
data-welcome | (vide) | Message d’accueil affiché à l’ouverture |
data-branding | true | Affiche “Propulsé par yannick.services” (masqué sur plans payants) |
data-stream-url | (auto) | URL de streaming SSE (activé automatiquement) |
data-escalation-url | (vide) | URL d’escalade vers un humain (Crisp, Calendly, mailto:, etc.) |
data-escalation-label | “Parler à un humain” | Libellé du bouton d’escalade |
data-include-paths | (vide) | Pages où afficher le widget (glob, séparées par virgule) |
data-exclude-paths | (vide) | Pages où masquer le widget (glob, séparées par virgule) |
Exemples de personnalisation#
Widget vert, en bas à gauche, en anglais#
<script src="https://yannick.services/ragweb/widget/v1.js"
data-ragweb-widget
data-api-key="rw_xxx"
data-color="#16a34a"
data-position="bottom-left"
data-lang="en"
data-title="AI Search"
data-placeholder="Ask anything...">
</script>Widget avec escalade vers Calendly#
<script src="https://yannick.services/ragweb/widget/v1.js"
data-ragweb-widget
data-api-key="rw_xxx"
data-escalation-url="https://calendly.com/votre-lien"
data-escalation-label="Prendre rendez-vous">
</script>Widget avec escalade par email#
<script src="https://yannick.services/ragweb/widget/v1.js"
data-ragweb-widget
data-api-key="rw_xxx"
data-escalation-url="mailto:contact@monsite.fr?subject=Question%20site"
data-escalation-label="Nous écrire">
</script>Filtrage par pages#
Contrôlez les pages où le widget apparaît avec data-include-paths et data-exclude-paths.
Syntaxe glob#
| Pattern | Correspond à |
|---|---|
/docs/* | Toutes les pages directement sous /docs/ |
/docs/** | Toutes les pages sous /docs/ (récursif) |
/pricing | Uniquement /pricing ou /pricing/ |
* | Toutes les pages |
Exemples#
Afficher uniquement sur la documentation :
data-include-paths="/docs/**,/help/**"Afficher partout sauf sur le blog :
data-exclude-paths="/blog/*,/blog/**"Afficher uniquement sur la page d’accueil et les prix :
data-include-paths="/,/pricing"Si
data-include-pathsest défini, le widget n’apparaît que sur les pages correspondantes. Si seuldata-exclude-pathsest défini, le widget apparaît partout sauf sur les pages exclues.
Fonctionnalités du widget#
Streaming temps réel#
Les réponses s’affichent progressivement (effet typewriter) grâce au streaming SSE. L’utilisateur voit la réponse se construire en direct.
Multi-turn (conversation)#
Le widget maintient un historique de conversation (max 6 messages). L’utilisateur peut poser des questions de suivi sans répéter le contexte.
Exemple : “Quels sont vos tarifs ?” → “Et pour le plan Pro ?” — l’IA comprend le contexte.
Reformulation intelligente#
Avant chaque recherche, la question est reformulée en interne pour améliorer la pertinence (ajout de synonymes et vocabulaire professionnel).
Rendu Markdown#
Les réponses supportent le formatage basique :
- Gras et italique
- Listes à puces et numérotées
- Liens cliquables
- Code inline
- Titres (niveaux 1 à 4)
Sources#
Chaque réponse inclut les pages sources utilisées, avec des liens cliquables vers votre site.
Escalade vers un humain#
Si configurée (data-escalation-url), un lien “Parler à un humain” apparaît sous les réponses. Compatible avec :
- Crisp, Intercom, Chatwoot (URL du chat)
- Calendly (prise de rendez-vous)
mailto:(email)- Tout lien HTTP
Configurateur visuel (dashboard)#
L’onglet Widget du tableau de bord propose un configurateur interactif :
- Choisissez la couleur avec un color picker
- Sélectionnez la position
- Personnalisez les textes (titre, placeholder, message d’accueil)
- Configurez l’escalade
- Définissez les filtres de pages
- Testez en direct (preview live)
- Copiez le code d’intégration généré
- Cliquez Enregistrer la configuration pour persister les choix
Compatibilité#
| Plateforme | Compatible | Notes |
|---|---|---|
| HTML statique | Oui | Collez le script avant </body> |
| WordPress | Oui | Dans le footer via un plugin “Insert Headers & Footers” |
| Webflow | Oui | Project Settings → Custom Code → Footer |
| Shopify | Oui | Online Store → Themes → Edit code → theme.liquid |
| Next.js / React | Oui | Utilisez useEffect pour charger le script dynamiquement |
| Hugo / Astro | Oui | Dans le partial footer ou extend-footer |
| Wix | Partiel | Via l’ajout de code HTML personnalisé |
Exemple React / Next.js#
import { useEffect } from 'react';
export default function RagWebWidget() {
useEffect(() => {
const script = document.createElement('script');
script.src = 'https://yannick.services/ragweb/widget/v1.js';
script.setAttribute('data-ragweb-widget', '');
script.setAttribute('data-api-key', 'rw_VOTRE_CLE');
script.setAttribute('data-color', '#2563eb');
document.body.appendChild(script);
return () => { document.body.removeChild(script); };
}, []);
return null;
}Poids et performance#
- < 5 KB gzipped (pas de dépendance externe)
- Shadow DOM fermé : aucun conflit CSS avec votre site
- Chargement asynchrone : pas de blocage du rendu
- Aucun cookie posé, aucun tracking des visiteurs
