Doküman Ajanı Gömme

Genel Bakış

Doküman Ajanı, özellikle dokümantasyon sayfaları için tasarlanmış özel bir AI destekli widget'tır. Kullanıcılarınıza, dokümantasyonunuz hakkında soruları yanıtlayarak anında yardım sağlar.

Temel Kurulum

Belgeler Ajan widget'ı ile başlamak basittir. Bu iki adımı takip edin:

Belgeler sayfanız ajanın bir iframe içinde yükleniyorsa, ana sayfa kökeninin OAuth uygulamanızın allowed_origins'ine dahil edildiğinden emin olun. Widget token uç noktası, bir token vermeden önce bu kökeni doğrular.

Adım 1: Script'i Ekleyin

Gerekli yapılandırma ile docs-widget.js script'ini HTML sayfanıza ekleyin. Birden fazla belgeler widget'ı yüklüyorsanız, her script'e benzersiz bir data-instance-id verin:

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

Adım 2: Bir Tetikleme Düğmesi Ekleyin

Widget'ın open() yöntemini çağıran bir düğme veya öğe oluşturun:

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

Alt kısıt arama çubuğu

Kutudan çıktığında, belgeler widget'ının görünür bir başlatıcısı yoktur — yalnızca sayfanız API'yi çağırdığında açılır. Bunun yerine bir arama çubuğu verin: her sayfanın altına sabitlenmiş kompakt bir alan, bir ziyaretçi üzerine tıkladığında veya yazmaya başladığında tam paneli açar. Zaten yazılmış olan her şey panelin arama kutusuna taşınır.

Bunu kontrol panelinizde Widget → İçerik → Arama alanı metni altında açın. Metin her dil için saklanır, bu nedenle her yerelleştirme kendi kelimelerini alır ve ziyaretçiler çubuğu kendi dillerinde görür.

Widget → Davranış, ne zaman göründüğünde kontrol eder:

• Gecikme — çubuğun görünmeden önceki milisaniyeleri. 0, hemen gösterir.
• Bantı otomatik olarak — milisaniye sonra kendini gizler. 0, ziyaretçi onu kapatana kadar açık tutar.

Çubuk, panel açıkken kendini gizler ve ziyaretçi kapattığında geri gelir, bu yüzden her zaman geri dönüş yolu olarak işlev görür. × ile kapatmak, yalnızca o sayfa görüntüsü için onu devre dışı bırakır; bir sonraki sayfa yüklemesinde geri döner.

Örnekler

Belgeler Ajanı'nı entegre etmenin bazı pratik örnekleri:

Örnek 1: Temel HTML Entegrasyonu

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

Örnek 2: Olay Dinleyicisi ile Özelleştirilmiş Düğme

Daha fazla kontrol için mevcut düğmelerinize olay dinleyicileri ekleyebilirsiniz:

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

Örnek 3: React/Next.js Entegrasyonu

Bir React veya Next.js uygulamasında:

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

Yapılandırma Seçenekleri

Docs Agent widget, birkaç yapılandırma parametresini kabul eder. Bir sayfada birden fazla widget yerleştirirken belirleyici örnek başına kontrol için data-instance-id kullanın:

Gerekli Parametreler

• data-widget-key: Belgeler widget'ınızın Widget ID'si — çoğu kurulumun ihtiyaç duyduğu tek değer. Bu, istemcinizi, ajanınızı ve yapılandırmanızı sunucu tarafında çözer.

Birden fazla örnek kurulumu için <code>data-widget-key</code>'in gelişmiş alternatifi — bu üç değeri yalnızca çoklu örnek kurulumları için açıkça geçirin:

• data-client-id: Companin kontrol panelinden benzersiz istemci tanımlayıcınız
• data-agent-id: Kullanmak istediğiniz ajanın ID'si
• data-config-id: Widget özelleştirmesi için yapılandırma ID'si

İsteğe Bağlı Parametreler

• data-locale: Dil kodu (varsayılan: 'en'). Destekler: en, de, es, fr, it, nb, nl, pt, sv
• data-dev: Geliştirme modu için 'true' olarak ayarlayın (localhost:3001'e bağlanır)

JavaScript API

Yüklendikten sonra, widget programatik kontrol için küresel bir API sunar. Çoklu widget kurulumları için, yalnızca en son küresel referansı kullanmak yerine örnek kayıt defterlerini (CompaninDocsWidgets.get(instanceId)) tercih edin:

open()

window.CompaninDocsWidget.open();

Docs Agent iletişim kutusunu tam ekran modunda açar.

close()

window.CompaninDocsWidget.close();

Docs Agent iletişim kutusunu kapatır ve widget'ı gizler.

Özel Stil

Tetikleyici düğmelerinizi istediğiniz gibi stillendirebilirsiniz. İşte yüzen bir yardım düğmesi örneği:

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

En İyi Uygulamalar

• Tetikleyici düğmesini belirgin, kolay erişilebilir bir konuma yerleştirin (örneğin, başlık, yüzen düğme)
• 'AI Sor' veya 'Yardım Gerekli?' gibi net, eylem odaklı düğme metinleri kullanın.
• Widget betiğinin API yöntemlerini çağırmadan önce yüklendiğinden emin olun
• İstemci kimlik bilgilerinizi güvende tutun - bunları istemci tarafı kodunda asla açığa çıkarmayın

Sorun Giderme

Widget yüklenmiyor mu?

API'yi çağırmadan önce betiğin yüklendiğinden emin olun. Widget'ın mevcut olup olmadığını kontrol edebilirsiniz:

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

Diyalog açılmıyor mu?

Geçerli bir data-widget-key (veya açık form için client-id, agent-id ve config-id) sağladığınızdan ve bunun doğru olduğundan emin olun. Birden fazla widget varsa, her betiğin benzersiz bir data-instance-id'ye sahip olduğundan emin olun.