Doküman Ajanı Gömme

Doküman sayfalarınıza Doküman Ajanı widget'ını nasıl gömeceğinizi öğrenin.

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.

Şimdi deneyin!

Bu sayfada Doküman Ajanı'nın nasıl çalıştığını görmek için aşağıdaki düğmeye tıklayın.

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>

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

Geri Sonraki: Genel Bakış