Docs Agent Insluiting

Overzicht

De Docs Agent is een gespecialiseerde AI-aangedreven widget die specifiek is ontworpen voor documentatiepagina's. Het biedt directe hulp aan je gebruikers door vragen over je documentatie te beantwoorden met een interactieve dialoog op volledig scherm.

Basisinstelling

Aan de slag met de Docs Agent widget is eenvoudig. Volg gewoon deze twee stappen:

Als uw documentpagina de agent binnen een iframe laadt, zorg er dan voor dat de hostpagina-oorsprong is opgenomen in de toegestane_origins van uw OAuth-toepassing. Het widget-token-eindpunt valideert deze oorsprong voordat een token wordt uitgegeven.

Stap 1: Voeg het Script toe

Voeg het docs-widget.js script toe aan je HTML-pagina met de vereiste configuratie. Als je meerdere docs widgets laadt, geef elke script een unieke data-instance-id:

<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>

Stap 2: Voeg een Triggerknop toe

Maak een knop of element dat de open() methode van de widget aanroept:

<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>

Onderzoekbalk onderaan

Out of the box heeft de docs-widget geen zichtbare launcher — deze opent alleen wanneer je pagina de API aanroept. Geef het in plaats daarvan een zoekbalk: een compact veld dat aan de onderkant van elke pagina is vastgepind, dat het volledige paneel opent wanneer een bezoeker erop klikt of begint te typen. Alles wat al is getypt, wordt meegenomen in het zoekvak van het paneel.

Zet het aan in je dashboard onder Widget → Inhoud → Zoekveldtekst. De tekst wordt per taal opgeslagen, zodat elke locale zijn eigen formulering krijgt en bezoekers de balk in hun eigen taal zien.

Widget → Gedragsinstellingen wanneer het verschijnt:

• Vertraging — milliseconden voordat de balk verschijnt. 0 toont het onmiddellijk.
• Auto-verbergen na — milliseconden totdat de balk zichzelf verbergt. 0 houdt het totdat de bezoeker het afwijst.

De balk verbergt zichzelf terwijl het paneel open is en komt terug wanneer de bezoeker het sluit, zodat het altijd als de weg terug dient. Het afwijzen met de × verwijdert het alleen voor die paginaweergave; het komt terug bij de volgende paginalading.

Voorbeelden

Hier zijn enkele praktische voorbeelden van hoe je de Docs Agent kunt integreren:

Voorbeeld 1: Basis HTML Integratie

<!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>

Voorbeeld 2: Aangepaste Knop met Evenement Luisteraar

Voor meer controle kun je gebeurtenisluiters aan je bestaande knoppen toevoegen:

// 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();  });});

Voorbeeld 3: React/Next.js Integratie

In een React of Next.js applicatie:

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>  );}

Configuratieopties

De Docs Agent-widget accepteert verschillende configuratieparameters. Gebruik data-instance-id voor deterministische per-instance controle bij het insluiten van meerdere widgets op één pagina:

Vereiste parameters

• data-widget-key: De Widget ID van uw docs-widget — de enige waarde die de meeste installaties nodig hebben. Het lost uw client, agent en config server-side op.

Geavanceerd alternatief voor <code>data-widget-key</code> — geef deze drie expliciet door alleen voor multi-instance setups:

• data-client-id: Uw unieke clientidentificatie van het Companin-dashboard
• data-agent-id: De ID van de agent die u wilt gebruiken
• data-config-id: Configuratie-ID voor widgetaanpassing

Optionele parameters

• data-locale: Taalcode (standaard: 'en'). Ondersteunt: en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Stel in op 'true' voor ontwikkelingsmodus (verbindt met localhost:3001)

JavaScript API

Zodra geladen, stelt de widget een globale API beschikbaar voor programmatische controle. Voor multi-widget setups, geef de voorkeur aan instance registries (CompaninDocsWidgets.get(instanceId)) boven alleen het gebruik van de laatste globale referentie:

open()

window.CompaninDocsWidget.open();

Opent de Docs Agent-dialoog in de volledige schermmodus.

close()

window.CompaninDocsWidget.close();

Sluit de Docs Agent-dialoog en verbergt de widget.

Aangepaste styling

U kunt uw triggerknoppen op elke gewenste manier stylen. Hier is een voorbeeld van een zwevende helpknop:

.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);}

Beste praktijken

• Plaats de triggerknop op een prominente, gemakkelijk toegankelijke locatie (bijv. header, zwevende knop)
• Gebruik duidelijke, actiegerichte knoptekst zoals 'Vraag AI' of 'Hulp nodig?'
• Zorg ervoor dat het widget-script wordt geladen voordat u probeert de API-methoden aan te roepen
• Houd uw clientreferenties veilig - stel ze nooit bloot in client-side code

Probleemoplossing

Widget laadt niet?

Zorg ervoor dat het script is geladen voordat u de API aanroept. U kunt controleren of de widget beschikbaar is:

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

Dialoog opent niet?

Controleer of u een geldige data-widget-key (of, voor de expliciete vorm, de client-id, agent-id en config-id) hebt opgegeven en dat deze correct is. Als er meerdere widgets aanwezig zijn, zorg ervoor dat elk script een unieke data-instance-id heeft.