Docs Agent Integrering

Oversikt

Docs Agent er en spesialisert AI-drevet widget designet spesielt for dokumentasjonssider. Den gir umiddelbar hjelp til brukerne dine ved å svare på spørsmål om dokumentasjonen din ved hjelp av en interaktiv dialog i fullskjerm.

Grunnleggende oppsett

Å komme i gang med Docs Agent-widgeten er enkelt. Følg bare disse to trinnene:

Hvis dokumentsiden din laster agenten inne i en iframe, må du sørge for at vertssideopprinnelsen er inkludert i de tillatte opprinnelsene for OAuth-applikasjonen din. Widget-tokenendepunktet validerer denne opprinnelsen før det utsteder et token.

Trinn 1: Legg til skriptet

Legg til docs-widget.js-skriptet på HTML-siden din med den nødvendige konfigurasjonen. Hvis du laster inn flere docs-widgets, gi hvert skript en unik 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>

Trinn 2: Legg til en utløserknapp

Opprett en knapp eller et element som kaller widgetens open() metode:

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

Bunnsøkefelt

Uten tilpasninger har dokumentwidgeten ingen synlig lanserer — den åpnes kun når siden din kaller API-en. Gi den en søkefelt i stedet: et kompakt felt festet til bunnen av hver side, som åpner det fullstendige panelet når en besøkende klikker på det eller begynner å skrive. Alt som allerede er skrevet, blir overført til panellets søkeboks.

Slå det på i dashbordet ditt under Widget → Innhold → Tekst for søkefelt. Teksten lagres per språk, så hvert område får sin egen formulering og besøkende ser linjen på sitt eget språk.

Widget → Atferdsinnstillinger når den vises:

• Forsinkelse — millisekunder før baren vises. 0 viser den umiddelbart.
• Auto-skjul etter — millisekunder til baren skjuler seg selv. 0 holder den til besøkende avviser den.

Baren skjuler seg selv mens panelet er åpent og kommer tilbake når besøkende lukker det, så det fungerer alltid som veien tilbake. Å avvise det med × fjerner det for den siden visningen; det kommer tilbake ved neste sideinnlasting.

Eksempler

Her er noen praktiske eksempler på hvordan du kan integrere Docs Agent:

Eksempel 1: Grunnleggende HTML-integrasjon

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

Eksempel 2: Tilpasset knapp med hendelseslytter

For mer kontroll kan du legge til hendelseslyttere til eksisterende knapper:

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

Eksempel 3: React/Next.js-integrasjon

I en React- eller Next.js-applikasjon:

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

Konfigurasjonsalternativer

Docs Agent-widgeten aksepterer flere konfigurasjonsparametere. Bruk data-instance-id for deterministisk per-instans kontroll når du integrerer flere widgets på én side:

Obligatoriske parametere

• data-widget-key: Widget-ID-en til dokumentwidgeten din — den eneste verdien de fleste installasjoner trenger. Den løser opp klienten, agenten og konfigurasjonen på serversiden.

Avansert alternativ til <code>data-widget-key</code> — send disse tre eksplisitt kun for multi-instans oppsett:

• data-client-id: Din unike klientidentifikator fra Companin-dashbordet
• data-agent-id: ID-en til agenten du ønsker å bruke
• data-config-id: Konfigurasjons-ID for widgettilpasning

Valgfri parametere

• data-locale: Språk kode (standard: 'en'). Støtter: en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Sett til 'true' for utviklingsmodus (kobler til localhost:3001)

JavaScript API

Når den er lastet, eksponerer widgeten et globalt API for programmatisk kontroll. For multi-widget oppsett, foretrekk instansregistre (CompaninDocsWidgets.get(instanceId)) fremfor kun å bruke den nyeste globale referansen:

open()

window.CompaninDocsWidget.open();

Åpner Docs Agent-dialogen i fullskjermmodus.

close()

window.CompaninDocsWidget.close();

Lukker Docs Agent-dialogen og skjuler widgeten.

Egendefinert styling

Du kan style triggerknappene dine på hvilken som helst måte du liker. Her er et eksempel på en flytende hjelpeknapp:

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

• Plasser triggerknappen på et fremtredende, lett tilgjengelig sted (f.eks. header, flytende knapp)
• Bruk klar, handlingsorientert knappetekst som 'Spør AI' eller 'Trenger hjelp?'
• Sørg for at widget-scriptet lastes før du prøver å kalle API-metodene
• Hold klientlegitimasjonen din sikker - aldri eksponer dem i klient-side kode

Feilsøking

Widgeten lastes ikke?

Sørg for at skriptet er lastet før du kaller API-en. Du kan sjekke om widgeten er tilgjengelig:

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

Dialogen åpnes ikke?

Bekreft at du har gitt en gyldig data-widget-key (eller, for den eksplisitte formen, klient-id, agent-id og konfig-id) og at den er korrekt. Hvis flere widgets er til stede, må du sørge for at hvert skript har en unik data-instance-id.