多渠道接入指南
· 1 min read
多渠道接入指南
概述
掌上意见箱是一个智能意见收集与管理平台，支持通过多种渠道接入，以便开发者或高级用户能够灵活地将意见收集功能集成到现有系统或应用中。本文档旨在提供全面的技术指导。
核心概念
- 意见箱：一个独立的意见收集单元，可配置收集规则、字段和通知方式。
- 渠道：意见提交的入口，如API、Web表单、SDK嵌入等。
- 接入点：每个渠道对应的具体技术实现端点。
主要接入方式
1. REST API 接入
通过标准的HTTP REST API提交意见，适用于服务器端集成。
基础端点
POST https://api.feedbackbox.com/v1/feedbacks
请求示例 (cURL)
curl -X POST https://api.feedbackbox.com/v1/feedbacks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"box_id": "box_123456",
"content": "产品建议：希望增加暗色模式。",
"contact": "user@example.com",
"metadata": {
"source": "mobile_app",
"version": "2.1.0"
}
}'
响应示例
{
"id": "fb_789012",
"status": "received",
"created_at": "2023-10-27T08:30:00Z"
}
2. Webhook 接收
配置Webhook URL以接收平台推送的新意见通知，实现实时处理。
配置步骤
- 在掌上意见箱管理后台进入「设置」->「Webhook」。
- 添加新的Webhook URL，并选择触发事件（如
feedback.created）。 - 保存后，平台将在事件发生时向该URL发送POST请求。
Webhook 载荷示例
{
"event": "feedback.created",
"timestamp": "2023-10-27T08:30:00Z",
"data": {
"feedback_id": "fb_789012",
"box_id": "box_123456",
"content": "产品建议：希望增加暗色模式。",
"contact": "user@example.com"
}
}
安全验证
建议在Webhook端点验证请求头中的 X-FeedbackBox-Signature，以确保请求来源可信。
3. JavaScript SDK 嵌入
在前端网页中嵌入SDK，快速生成意见提交浮窗或组件。
引入SDK
<script>
(function(f,e,e,d,b,o,x){f["FeedbackBoxObject"]=b;f[b]=f[b]||function(){
(f[b].q=f[b].q||[]).push(arguments);};f[b].l=1*new Date();o=e.createElement(e),
x=e.getElementsByTagName(e)[0];o.async=1;o.src=d;x.parentNode.insertBefore(o,x);
})(window,document,"script","https://cdn.feedbackbox.com/sdk/v1.js","fbx");
fbx("init", {
boxId: "box_123456",
position: "bottom-right"
});
</script>
高级配置 SDK支持自定义触发器、样式和回调函数，详情请参考SDK专属文档。
4. 邮件转发接入
将特定邮箱设置为转发地址，系统会自动解析邮件内容并创建为意见。
- 在意见箱设置中获取专属的转发邮箱地址（如
box_123456@in.feedbackbox.com）。 - 配置你的邮件系统，将用户反馈邮件自动转发或BCC至该地址。
- 邮件主题和正文将被自动捕获。
接入流程与最佳实践
- 规划与准备：明确收集场景，在管理后台创建对应的意见箱并获取
box_id和API Key。 - 选择接入方式：根据技术栈和需求（实时性、用户体验、数据控制）选择最合适的渠道。
- 开发与测试：在沙箱环境或使用测试
box_id完成集成开发与测试。 - 上线与监控：切换至生产环境，并监控接入点的可用性与性能。
安全建议
- 妥善保管
API Key，切勿在前端代码中硬编码。 - 为API请求和Webhook启用HTTPS。
- 定期轮换API Key。
- 对接收到的用户输入内容进行适当的清理和验证（即使在平台侧也会进行基础处理）。
故障排除
- API返回4xx错误：检查请求体格式、认证信息及
box_id是否正确。 - 未收到Webhook：检查端点URL可访问性、网络防火墙设置，并验证签名。
- SDK组件未加载：检查网络连接，确认
box_id有效，并查看浏览器控制台是否有错误信息。
更多资源
文档最后更新：2023年10月27日 如有疑问，请联系技术支持：support@feedbackbox.com