Intégration de l'agent Docs

Aperçu

L'agent Docs est un widget spécialisé alimenté par l'IA conçu spécifiquement pour les pages de documentation. Il fournit une aide instantanée à vos utilisateurs en répondant à des questions sur votre documentation via un dialogue interactif en plein écran.

Configuration de base

Commencer avec le widget de l'agent Docs est simple. Suivez simplement ces deux étapes :

Si votre page docs charge l'agent à l'intérieur d'un iframe, assurez-vous que l'origine de la page hôte est incluse dans les allowed_origins de votre application OAuth. Le point de terminaison du jeton de widget valide cette origine avant de délivrer un jeton.

Étape 1 : Ajouter le script

Ajoutez le script docs-widget.js à votre page HTML avec la configuration requise. Si vous chargez plusieurs widgets docs, donnez à chaque script un data-instance-id unique :

<script  src="https://widget.companin.tech/docs-widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="docs-help"  data-locale="en"  async></script>

Étape 2 : Ajouter un bouton de déclenchement

Créez un bouton ou un élément qui appelle la méthode open() du widget :

<button id="help-btn" type="button">Ask Documentation Agent</button><script>  const handleOpen = (event) => {    console.log('Docs widget opened', event?.context);  };  // Generic event API (returns unsubscribe function)  const unsubscribeOpen = window.CompaninDocsWidget?.on?.('open', handleOpen);  document.getElementById('help-btn')?.addEventListener('click', () => {    window.CompaninDocsWidget?.open();  });  // Cleanup on page unload or SPA route change  window.addEventListener('beforeunload', () => {    if (typeof unsubscribeOpen === 'function') unsubscribeOpen();  });</script>

Barre de recherche inférieure

Par défaut, le widget de documentation n'a pas de lanceur visible — il ne s'ouvre que lorsque votre page appelle l'API. Donnez-lui plutôt une barre de recherche : un champ compact épinglé en bas de chaque page, qui ouvre le panneau complet lorsqu'un visiteur clique dessus ou commence à taper. Tout ce qui a déjà été tapé est transféré dans la zone de recherche du panneau.

Activez-le dans votre tableau de bord sous Widget → Contenu → Texte du champ de recherche. Le texte est stocké par langue, donc chaque locale a sa propre formulation et les visiteurs voient la barre dans leur propre langue.

Widget → Les contrôles de comportement lorsqu'il apparaît :

• Délai — millisecondes avant que la barre n'apparaisse. 0 l'affiche immédiatement.
• Masquer automatiquement après — millisecondes jusqu'à ce que la barre se cache elle-même. 0 la garde jusqu'à ce que le visiteur la rejette.

La barre se cache pendant que le panneau est ouvert et revient lorsque le visiteur le ferme, elle sert donc toujours de chemin de retour. La fermer avec le × la retire uniquement pour cette vue de page ; elle revient lors du prochain chargement de page.

Exemples

Voici quelques exemples pratiques de la façon d'intégrer l'agent Docs :

Exemple 1 : Intégration HTML de base

<!DOCTYPE html><html lang="en"><head>  <meta charset="UTF-8">  <meta name="viewport" content="width=device-width, initial-scale=1.0">  <title>My Documentation</title></head><body>  <header>    <h1>Product Documentation</h1>    <button onclick="window.CompaninDocsWidget.open()">      Need Help?    </button>  </header>  <main>    <!-- Your documentation content -->  </main>  <script    src="https://widget.companin.tech/docs-widget.js"    data-widget-key="your-widget-key"    data-locale="en">  </script></body></html>

Exemple 2 : Bouton personnalisé avec écouteur d'événements

Pour plus de contrôle, vous pouvez ajouter des écouteurs d'événements à vos boutons existants :

// Wait for the widget to loadwindow.addEventListener('load', () => {  const unsubscribeResponse = window.CompaninDocsWidget?.on?.('response', (event) => {    console.log('Agent response:', event?.data);  });  document.getElementById('help-btn').addEventListener('click', () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  });  window.addEventListener('beforeunload', () => {    if (typeof unsubscribeResponse === 'function') unsubscribeResponse();  });});

Exemple 3 : Intégration React/Next.js

Dans une application React ou Next.js :

import React from 'react';export default function Documentation() {  const openDocsAgent = () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  };  return (    <div>      <h1>API Documentation</h1>      <button        onClick={openDocsAgent}        className="help-button"      >        Ask Customer Support AI Agent      </button>    </div>  );}

Options de configuration

Le widget Docs Agent accepte plusieurs paramètres de configuration. Utilisez data-instance-id pour un contrôle déterministe par instance lors de l'intégration de plusieurs widgets sur une page :

Paramètres requis

• data-widget-key: L'ID de votre widget docs — la seule valeur dont la plupart des installations ont besoin. Il résout votre client, agent et configuration côté serveur.

Alternative avancée à <code>data-widget-key</code> — passez ces trois explicitement uniquement pour des configurations multi-instances :

• data-client-id: Votre identifiant client unique depuis le tableau de bord Companin
• data-agent-id: L'ID de l'agent que vous souhaitez utiliser
• data-config-id: ID de configuration pour la personnalisation du widget

Paramètres optionnels

• data-locale: Code de langue (par défaut : 'en'). Prend en charge : en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Définissez sur 'true' pour le mode développement (se connecte à localhost:3001)

API JavaScript

Une fois chargé, le widget expose une API globale pour un contrôle programmatique. Pour les configurations multi-widgets, préférez les registres d'instance (CompaninDocsWidgets.get(instanceId)) plutôt que d'utiliser uniquement la dernière référence globale :

open()

window.CompaninDocsWidget.open();

Ouvre la boîte de dialogue Docs Agent en mode plein écran.

close()

window.CompaninDocsWidget.close();

Ferme la boîte de dialogue Docs Agent et masque le widget.

Style personnalisé

Vous pouvez styliser vos boutons de déclenchement comme vous le souhaitez. Voici un exemple d'un bouton d'aide flottant :

.my-help-button {  position: fixed;  bottom: 20px;  right: 20px;  padding: 12px 24px;  background: #2563eb;  color: white;  border: none;  border-radius: 8px;  font-weight: 600;  cursor: pointer;  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);  transition: all 0.2s;}.my-help-button:hover {  background: #1d4ed8;  transform: translateY(-2px);  box-shadow: 0 6px 8px rgba(0, 0, 0, 0.15);}

Meilleures pratiques

• Placez le bouton de déclenchement dans un endroit proéminent et facilement accessible (par exemple, en-tête, bouton flottant)
• Utilisez un texte de bouton clair et orienté action comme 'Demander à l'IA' ou 'Besoin d'aide ?'
• Assurez-vous que le script du widget se charge avant d'essayer d'appeler ses méthodes API
• Gardez vos identifiants client sécurisés - ne les exposez jamais dans le code côté client

Dépannage

Widget ne se charge pas ?

Assurez-vous que le script est chargé avant d'appeler l'API. Vous pouvez vérifier si le widget est disponible :

window.addEventListener('load', () => {  console.log('Widget loaded:', !!window.CompaninDocsWidget);});

Dialogue ne s'ouvre pas ?

Vérifiez que vous avez fourni un data-widget-key valide (ou, pour le formulaire explicite, le client-id, agent-id et config-id) et qu'il est correct. Si plusieurs widgets sont présents, assurez-vous que chaque script a un data-instance-id unique.