Penyematan Agen Docs

Pelajari cara menyematkan widget Agen Docs di halaman dokumentasi Anda.

Ikhtisar

Agen Docs adalah widget khusus yang didukung AI yang dirancang khusus untuk halaman dokumentasi. Ini memberikan bantuan instan kepada pengguna Anda dengan menjawab pertanyaan tentang dokumentasi Anda menggunakan dialog interaktif layar penuh.

Coba sekarang!

Klik tombol di bawah untuk melihat Agen Docs beraksi di halaman ini.

Pengaturan Dasar

Memulai dengan widget Agen Docs sangat sederhana. Cukup ikuti dua langkah ini:

Jika halaman dokumen Anda memuat agen di dalam iframe, pastikan asal halaman host disertakan dalam allowed_origins aplikasi OAuth Anda. Titik akhir token widget memvalidasi asal ini sebelum mengeluarkan token.

Langkah 1: Tambahkan Skrip

Tambahkan skrip docs-widget.js ke halaman HTML Anda dengan konfigurasi yang diperlukan. Jika Anda memuat beberapa widget dokumen, berikan setiap skrip ID data-instance yang unik:

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

Langkah 2: Tambahkan Tombol Pemicu

Buat tombol atau elemen yang memanggil metode open() 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>

Contoh

Berikut adalah beberapa contoh praktis tentang cara mengintegrasikan Agen Docs:

Contoh 1: Integrasi HTML Dasar

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

Contoh 2: Tombol Kustom dengan Pendengar Acara

Untuk kontrol lebih, Anda dapat menambahkan pendengar acara ke tombol yang sudah ada:

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

Contoh 3: Integrasi React/Next.js

Dalam aplikasi React atau 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>  );}

Opsi Konfigurasi

Widget Docs Agent menerima beberapa parameter konfigurasi. Gunakan data-instance-id untuk kontrol per-instance yang deterministik saat menyematkan beberapa widget di satu halaman:

Parameter yang Diperlukan

data-widget-key: ID Widget widget Anda — nilai tunggal yang dibutuhkan sebagian besar instalasi. Ini menyelesaikan klien, agen, dan konfigurasi di sisi server.

Alternatif lanjutan untuk <code>data-widget-key</code> — kirimkan ketiga ini secara eksplisit hanya untuk pengaturan multi-instance:

data-client-id: Identifikasi klien unik Anda dari dasbor Companin
data-agent-id: ID agen yang ingin Anda gunakan
data-config-id: ID Konfigurasi untuk kustomisasi widget

Parameter Opsional

data-locale: Kode bahasa (default: 'en'). Mendukung: en, de, es, fr, it, nb, nl, pt, sv
data-dev: Setel ke 'true' untuk mode pengembangan (terhubung ke localhost:3001)

API JavaScript

Setelah dimuat, widget mengekspos API global untuk kontrol programatik. Untuk pengaturan multi-widget, lebih baik menggunakan registri instance (CompaninDocsWidgets.get(instanceId)) daripada hanya menggunakan referensi global terbaru:

open()

window.CompaninDocsWidget.open();

Membuka dialog Docs Agent dalam mode layar penuh.

close()

window.CompaninDocsWidget.close();

Menutup dialog Docs Agent dan menyembunyikan widget.

Gaya Kustom

Anda dapat menata tombol pemicu Anda dengan cara apa pun yang Anda suka. Berikut adalah contoh tombol bantuan mengambang:

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

Praktik Terbaik

Tempatkan tombol pemicu di lokasi yang menonjol dan mudah diakses (misalnya, header, tombol mengambang)
Gunakan teks tombol yang jelas dan berorientasi tindakan seperti 'Tanya AI' atau 'Butuh Bantuan?'
Pastikan skrip widget dimuat sebelum mencoba memanggil metode API-nya
Jaga kredensial klien Anda tetap aman - jangan pernah mengeksposnya dalam kode sisi klien

Pemecahan Masalah

Widget tidak dimuat?

Pastikan skrip dimuat sebelum memanggil API. Anda dapat memeriksa apakah widget tersedia:

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

Dialog tidak terbuka?

Verifikasi bahwa Anda telah memberikan data-widget-key yang valid (atau, untuk formulir eksplisit, client-id, agent-id, dan config-id) dan bahwa itu benar. Jika beberapa widget ada, pastikan setiap skrip memiliki data-instance-id yang unik.

Kembali Berikutnya: Ikhtisar