脑鱼入App部件
这个软件包提供了将Brainfish in-app部件整合到您网站或网络应用程序的简单方法. 它支持带有上下文帮助功能的弹出部件.
安装
npm install @brainfish-ai/web-widget
直接输入您的 HTML
<script type="module">
import Brainfish from "https://cdn.jsdelivr.net/npm/@brainfish-ai/web-widget@latest/dist/web.js"
Brainfish.Widgets.init({ widgetKey: "your-key" });
</script>
弹出部件
弹出部件提供了一个浮动按钮,在模式覆盖中打开了搜索界面.
基本用途
<!-- The widget will automatically create a floating button -->
<script>
Brainfish.Widgets.init({
widgetKey: "your-widget-key",
environment: "production" // or "staging", "local"
});
</script>
部件控制 API
// Open the widget
Brainfish.Widgets.open();
// Open the widget with custom positioning
Brainfish.Widgets.open({
position: 'bottom-right' // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
});
// Close the widget
Brainfish.Widgets.close();
// Create a new conversation thread
// If widget is open, resets the current conversation
// If widget is closed, opens it with a new conversation
Brainfish.Widgets.createNewThread();
// Check if widget is ready
if (Brainfish.Widgets.isReady) {
// Widget is ready to use
}
用户管理
// Identify a user
Brainfish.Widgets.identify({
name: "John Doe",
email: "[email protected]",
userId: "user_123"
});
// Set secret attributes (for internal use)
Brainfish.Widgets.setSecretAttributes("internal_data_123");
带有覆盖的自定义
自定义部件的外观和行为 overrides 配置 :
Brainfish.Widgets.init({
widgetKey: "your-widget-key",
overrides: {
// Suggested questions that appear when widget opens
suggestions: [
'How do I reset my password?',
'How do I contact support?',
'What are your pricing plans?'
],
// Theme customization
theme: {
inputButtonBgColor: '#3b82f6',
inputButtonColor: '#ffffff'
},
// Widget settings
panelTitle: 'Help Center',
placeholder: 'Ask a question...',
// Action buttons
bodyActionButtons: [
{
icon: 'Calendar',
type: 'link',
label: 'Book a Demo',
value: 'https://calendly.com/your-company'
}
]
}
});
* 完整的定制选项见:
自定义定位
两者 open() 财务报告和审定财务报表 onContextHelp() 方法支持自定义定位,以控制屏幕上显示部件的位置。 这对于创造背景经验或避免UI冲突是有用的.
可用职位 :
'bottom-left'- 部件出现在左下角(默认)'bottom-right'- 部件出现在右下角'top-left'- 部件出现在左上角'top-right'- 部件出现在右上角
使用实例:
// Open widget in different positions
Brainfish.Widgets.open({ position: 'top-right' });
Brainfish.Widgets.open({ position: 'bottom-left' });
// Contextual help with positioning
Brainfish.Widgets.onContextHelp("How do I reset my password?", {
position: 'top-left'
});
// Dynamic positioning based on user interaction
function showHelpNearElement(question, element) {
const rect = element.getBoundingClientRect();
const position = rect.left < window.innerWidth / 2 ? 'bottom-left' : 'bottom-right';
Brainfish.Widgets.onContextHelp(question, { position });
}
背景帮助特性
上下文帮助功能允许您打开基于用户交互的预填问题部件 .
// Trigger contextual help with a specific question
Brainfish.Widgets.onContextHelp("How do I reset my password?");
// Trigger contextual help with custom positioning
Brainfish.Widgets.onContextHelp("How do I reset my password?", {
position: 'top-left' // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
});
执行实例
带有帮助图标的 HTML :
<div class="form-field">
<label>Email Address</label>
<input type="email" value="[email protected]">
<button class="help-icon"
data-question="How do I change my email address?"
data-position="top-left">
<i class="ph ph-question"></i>
</button>
</div>
<script>
// Add event listeners to help icons with custom positioning
document.querySelectorAll('.help-icon').forEach(icon => {
icon.addEventListener('click', (e) => {
const question = e.target.dataset.question;
const position = e.target.dataset.position || 'bottom-right';
Brainfish.Widgets.onContextHelp(question, { position });
});
});
</script>
直接按钮集成 :
<button onclick="Brainfish.Widgets.onContextHelp('How do I reset my password?', { position: 'top-right' })">
Reset Password
</button>
程序用途 :
function showHelp(question, position = 'bottom-right') {
Brainfish.Widgets.onContextHelp(question, { position });
}
// Usage with different positions
showHelp("How do I update my profile?", 'top-left');
showHelp("How do I contact support?", 'bottom-right');
活动听众
部件打开和关闭时会发出事件 。 你可以听这些事件:
// Set up the abort controller
const controller = new AbortController();
const { signal } = controller;
// Listen for widget events
window.addEventListener('onBrainfishWidgetOpen', (event) => {
console.log('Widget opened');
// Your custom logic here
}, { signal });
window.addEventListener('onBrainfishWidgetClose', (event) => {
console.log('Widget closed');
// Your custom logic here
}, { signal });
// Clean up event listeners when no longer needed
controller.abort();
分析事件
部件自动跟踪分析事件 :
- 打开部件 - 当部件打开时
- 打开部件 - 背景帮助 - 通过上下文帮助打开时
- 打开部件 - 自定义触发器 - 用自定义触发器打开时
- 关闭部件 - 当部件关闭时
构建
运行以下命令来构建部件 :
yarn build:web-widget
本地测试
启动本地服务器
cd packages/web-widget
npx serve ./ -p 8000 -C
打开游戏场
该游乐场为Brainfish部件提供了全面的测试环境:
open http://localhost:8000/playground/index.html
游乐场包括:
- 部件配置 - 设置环境、 API 密钥和部件设置
- 环境帮助测试 - 测试新的背景帮助功能,以抽样提问
- 现实世界民主 - 看看客户如何在应用程序中实施背景帮助
- API 测试 - 测试所有部件方法和功能
- 实时日志 - 监视部件事件并调试信息
测试不同的环境
您可以在不同的环境下测试部件, 方法是通过 env 参数 :
# Local environment
open http://localhost:8000/playground/index.html?env=local
# Staging environment
open http://localhost:8000/playground/index.html?env=staging
# Production environment
open http://localhost:8000/playground/index.html?env=prod
代理部件开发
如果您想用代理部件( Next.js app) 进行测试, 请在本地启动 :
cd packages/agent-widget
npm run dev
这将运行端口3000上的代理部件, 游乐场将在本地开发模式下自动连接到此部件 .