Встраивание агента документации

Узнайте, как встроить виджет агента документации на ваши страницы документации.

Обзор

Агент документации — это специализированный виджет на базе ИИ, разработанный специально для страниц документации. Он предоставляет мгновенную помощь вашим пользователям, отвечая на вопросы о вашей документации с помощью полноэкранного интерактивного диалога.

Попробуйте сейчас!

Нажмите кнопку ниже, чтобы увидеть агента документации в действии на этой странице.

Базовая настройка

Начать работу с виджетом агента документации просто. Просто выполните эти два шага:

Если ваша страница документов загружает агента внутри iframe, убедитесь, что источник страницы хоста включен в разрешенные источники вашего OAuth-приложения. Точка токена виджета проверяет этот источник перед выдачей токена.

Шаг 1: Добавьте скрипт

Добавьте скрипт docs-widget.js на вашу HTML-страницу с необходимой конфигурацией. Если вы загружаете несколько виджетов документации, дайте каждому скрипту уникальный 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>

Шаг 2: Добавьте кнопку триггера

Создайте кнопку или элемент, который вызывает метод open() виджета:

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

Примеры

Вот несколько практических примеров того, как интегрировать агента документации:

Пример 1: Базовая интеграция HTML

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

Пример 2: Индивидуальная кнопка с обработчиком событий

Для большего контроля вы можете добавить обработчики событий к вашим существующим кнопкам:

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

Пример 3: Интеграция React/Next.js

В приложении React или 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>  );}

Опции конфигурации

Виджет Docs Agent принимает несколько параметров конфигурации. Используйте data-instance-id для детерминированного управления на уровне экземпляра при встраивании нескольких виджетов на одной странице:

Обязательные параметры

data-widget-key: Идентификатор виджета вашего документа — единственное значение, необходимое большинству установок. Он разрешает ваш клиент, агент и конфигурацию на стороне сервера.

Расширенная альтернатива <code>data-widget-key</code> — передайте эти три значения явно только для многократных установок:

data-client-id: Ваш уникальный идентификатор клиента из панели управления Companin
data-agent-id: Идентификатор агента, который вы хотите использовать
data-config-id: Идентификатор конфигурации для настройки виджета

Необязательные параметры

data-locale: Код языка (по умолчанию: 'en'). Поддерживает: en, de, es, fr, it, nb, nl, pt, sv
data-dev: Установите на 'true' для режима разработки (подключается к localhost:3001)

JavaScript API

После загрузки виджет предоставляет глобальный API для программного управления. Для многовиджетных установок предпочтительнее использовать реестры экземпляров (CompaninDocsWidgets.get(instanceId)) вместо использования только последней глобальной ссылки:

open()

window.CompaninDocsWidget.open();

Открывает диалог Docs Agent в полноэкранном режиме.

close()

window.CompaninDocsWidget.close();

Закрывает диалог Docs Agent и скрывает виджет.

Пользовательский стиль

Вы можете стилизовать ваши кнопки-триггеры любым способом. Вот пример плавающей кнопки помощи:

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

Лучшие практики

Разместите кнопку-триггер в заметном, легко доступном месте (например, в заголовке, плавающая кнопка)
Используйте четкий, ориентированный на действие текст кнопки, например 'Спросить ИИ' или 'Нужна помощь?'
Убедитесь, что скрипт виджета загружается перед тем, как пытаться вызвать его методы API
Держите свои учетные данные клиента в безопасности - никогда не раскрывайте их в коде на стороне клиента

Устранение неполадок

Виджет не загружается?

Убедитесь, что скрипт загружен перед вызовом API. Вы можете проверить, доступен ли виджет:

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

Диалог не открывается?

Проверьте, что вы предоставили действительный data-widget-key (или, для явной формы, client-id, agent-id и config-id) и что он правильный. Если присутствует несколько виджетов, убедитесь, что каждый скрипт имеет уникальный data-instance-id.

Назад Next: Обзор