Widget — Intégration

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://www.ragweb.fr/widget/v1.js"
  data-ragweb-widget
  data-api-key="rw_VOTRE_CLE_API"
  data-color="#2563eb"
  data-position="bottom-right"
  data-shape="circle"
  data-icon="search"
  data-lang="fr">
</script>

Le widget apparaît sous forme d’un bouton flottant. Au clic, un panneau de recherche s’ouvre. La forme et l’icône du bouton sont personnalisables.

Personnalisation (data-attributes)

Formes du bouton (data-shape)

La forme pill affiche automatiquement le texte de data-title à côté de l’icône, créant un bouton plus explicite pour les utilisateurs.

Icônes du bouton (data-icon)

Exemples de personnalisation

Widget vert, en bas à gauche, en anglais

<script src="https://www.ragweb.fr/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 carré avec icône chat

<script src="https://www.ragweb.fr/widget/v1.js"
  data-ragweb-widget
  data-api-key="rw_xxx"
  data-shape="square"
  data-icon="chat"
  data-title="Assistant">
</script>

Widget pilule avec icône IA

La forme pilule affiche le titre à côté de l’icône — idéal pour un bouton bien visible et explicite.

<script src="https://www.ragweb.fr/widget/v1.js"
  data-ragweb-widget
  data-api-key="rw_xxx"
  data-shape="pill"
  data-icon="sparkle"
  data-color="#7c3aed"
  data-title="Demander à l'IA">
</script>

Widget arrondi, icône documentation

<script src="https://www.ragweb.fr/widget/v1.js"
  data-ragweb-widget
  data-api-key="rw_xxx"
  data-shape="rounded"
  data-icon="book"
  data-color="#0891b2"
  data-title="Explorer la doc">
</script>

Widget avec escalade vers Calendly

<script src="https://www.ragweb.fr/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 vers Chatwoot

<script src="https://www.ragweb.fr/widget/v1.js"
  data-ragweb-widget
  data-api-key="rw_xxx"
  data-escalation-url="https://app.chatwoot.com/widget?website_token=VOTRE_TOKEN"
  data-escalation-label="Chat en direct">
</script>

Widget avec escalade par email

<script src="https://www.ragweb.fr/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

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"

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 n’importe quelle URL :

N’importe quel lien HTTP ou mailto: fonctionne — le widget ouvre l’URL dans un nouvel onglet.

Configurateur visuel (dashboard)

L’onglet Widget du tableau de bord propose un configurateur interactif :

1. Choisissez la couleur avec un color picker
2. Sélectionnez la position
3. Choisissez la forme du bouton (rond, arrondi, carré, pilule)
4. Choisissez l’icône du bouton (loupe, chat, IA, aide, documentation)
5. Personnalisez les textes (titre, placeholder, message d’accueil)
6. Configurez l’escalade
7. Définissez les filtres de pages
8. Testez en direct (preview live)
9. Copiez le code d’intégration généré
10. Cliquez Enregistrer la configuration pour persister les choix

Compatibilité

Exemple React / Next.js

import { useEffect } from 'react';

export default function RagWebWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://www.ragweb.fr/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