betaflow-sdk
Version:
BetaFlow SDK for web applications - A powerful tool for managing beta testing campaigns and user feedback
771 lines (607 loc) • 19.5 kB
Markdown
# BetaFlow SDK
[](https://badge.fury.io/js/betaflow-sdk)
[](https://opensource.org/licenses/MIT)
BetaFlow SDK 是一个强大的工具，用于管理 Beta 测试活动和用户反馈收集。它提供了简单易用的 API，帮助开发者快速集成 Beta 测试功能到他们的 Web 应用中。
> 当前版本：v1.3.0
> **🚀 v1.3.0 重大更新**
>
> - 🎨 **动态表单**: 表单标题、字段和头部样式根据 `campaignId` 从后端动态获取
> - 🔧 **丰富字段类型**: 支持 text、email、tel、url、textarea、select、radio、checkbox、number、date
> - ✅ **字段验证**: 支持字段验证规则（长度、正则表达式等）和默认值
> - 🎨 **自定义头部**: 支持自定义表单头部（标题、副标题、描述、图标、背景色等）
> - 🔄 **智能降级**: 后端获取失败时自动使用默认表单配置
> - 📚 **完整文档**: 新增后端API接口格式说明和使用示例
## 特性
- 🚀 **轻量级**: 压缩后仅 ~15KB
- 📱 **响应式设计**: 完美适配桌面和移动设备
- 🎨 **可定制**: 支持自定义主题、位置和样式
- 🌍 **国际化**: 内置中英文支持
- 🔧 **TypeScript**: 完整的 TypeScript 类型定义
- ⚡ **零依赖**: 无需额外的第三方库
- 🔒 **安全**: 支持 API 密钥认证
## 安装
### NPM 安装
```bash
npm install betaflow-sdk
```
### CDN 引入
#### 国内用户（阿里云 CDN）
```html
<script src="https://fuli-img.oss-cn-beijing.aliyuncs.com/sdk/latest/betaflow.min.js"></script>
```
#### 海外用户（GitHub Pages CDN）
```html
<script src="https://saudm.github.io/betaflow-sdk/sdk/latest/betaflow.min.js"></script>
```
## 在线演示
🎮 **[查看在线演示页面](examples/demo.html)**
我们提供了一个完整的交互式演示页面，您可以：
- 实时测试所有 SDK 功能
- 查看不同配置选项的效果
- 测试 API 调用和错误处理
- 体验响应式设计和主题切换
- 查看完整的使用示例代码
演示页面包含：
- 📦 **安装指南**: NPM 和 CDN 两种安装方式
- 🎮 **功能演示**: 表单显示/隐藏、浮动按钮控制
- ⚙️ **配置面板**: 语言、主题、位置、调试模式设置
- 🔧 **API 测试**: 活动信息获取、申请提交、连接测试
- 📝 **代码示例**: 完整的集成代码参考
- 📊 **状态监控**: SDK 运行状态实时显示
## 快速开始
### NPM 使用方式
如果您使用现代前端框架，可以通过 NPM 安装：
```bash
npm install betaflow-sdk
```
```javascript
import BetaFlow from "betaflow-sdk";
// 🎉 v1.2.8 统一认证 - campaignId 和 apiKey 为必需参数
const betaflow = new BetaFlow({
campaignId: "YOUR_CAMPAIGN_ID",
apiKey: "YOUR_API_KEY",
debug: true, // 可选：开启调试模式
});
// 显示申请表单
betaflow.showApplicationForm();
```
### CDN 使用方式
```html
<!DOCTYPE html>
<html>
<head>
<title>BetaFlow SDK Demo</title>
</head>
<body>
<!-- 🎉 v1.2.9 统一认证自动初始化 -->
<script
src="https://fuli-img.oss-cn-beijing.aliyuncs.com/sdk/latest/betaflow.min.js"
data-auto-init="true"
data-campaign-id="YOUR_CAMPAIGN_ID"
data-api-key="YOUR_API_KEY"
data-debug="true"
></script>
<!-- 或者手动初始化 -->
<script>
const betaflow = new BetaFlow({
campaignId: "YOUR_CAMPAIGN_ID",
apiKey: "YOUR_API_KEY",
debug: true, // 可选：开启调试模式
});
</script>
</body>
</html>
```
### 自动选择最优 CDN
```html
<script>
// 自动选择最优 CDN
function loadBetaFlowSDK() {
const isChina =
/\.cn$/.test(window.location.hostname) ||
navigator.language.includes("zh");
const cdnUrl = isChina
? "https://fuli-img.oss-cn-beijing.aliyuncs.com/sdk/latest/betaflow.min.js"
: "https://saudm.github.io/betaflow-sdk/sdk/latest/betaflow.min.js";
const script = document.createElement("script");
script.src = cdnUrl;
script.onload = function () {
// 🎉 v1.2.9 统一认证初始化
const betaflow = new BetaFlow({
campaignId: "YOUR_CAMPAIGN_ID",
apiKey: "YOUR_API_KEY",
debug: true, // 可选：开启调试模式
});
};
document.head.appendChild(script);
}
loadBetaFlowSDK();
</script>
```
## 配置选项
```javascript
const betaflow = new BetaFlow({
// 🎉 v1.2.9 必需参数
campaignId: "YOUR_CAMPAIGN_ID", // 活动ID（必需）
apiKey: "YOUR_API_KEY", // API密钥（必需）
// 可选参数
apiEndpoint: "https://betaflow.fulitimes.com/api", // API端点地址（可选，默认使用官方服务器）
// UI 配置
language: "zh-CN", // 语言设置 ('zh-CN' | 'en-US')
theme: "light", // 主题 ('light' | 'dark')
position: "bottom-right", // 浮动按钮位置
autoShow: true, // 自动显示浮动按钮
// 自定义文本
buttonText: "申请 Beta 测试", // 浮动按钮文本
formTitle: "申请 Beta 测试", // 表单标题
// 开发配置
debug: false, // 调试模式（推荐开启以获得详细日志）
// 回调函数
onFormSubmit: (data) => {
console.log("表单提交:", data);
},
onFormSuccess: (response) => {
console.log("提交成功:", response);
},
onFormError: (error) => {
console.error("提交失败:", error);
},
});
```
## 后端API接口
### 获取项目信息接口
SDK 会调用以下接口获取项目的表单配置：
**接口地址：** `GET /campaigns/{campaignId}`
**请求头：**
```
Authorization: Bearer {apiKey}
Content-Type: application/json
```
**响应格式：**
```json
{
"id": "campaign-123",
"name": "产品 Beta 测试",
"description": "产品描述",
"formTitle": "申请 Beta 测试资格",
"formHeader": {
"title": "欢迎申请 Beta 测试",
"subtitle": "体验最新功能",
"description": "填写以下信息即可申请测试资格",
"iconUrl": "https://example.com/icon.png",
"backgroundColor": "#f0f9ff",
"textColor": "#1e40af"
},
"formFields": [
{
"name": "name",
"label": "姓名",
"type": "text",
"required": true,
"placeholder": "请输入您的姓名",
"validation": {
"minLength": 2,
"maxLength": 50
}
},
{
"name": "email",
"label": "邮箱",
"type": "email",
"required": true,
"placeholder": "请输入邮箱地址"
},
{
"name": "company",
"label": "公司",
"type": "text",
"required": false,
"placeholder": "请输入公司名称"
},
{
"name": "role",
"label": "职位",
"type": "select",
"required": true,
"options": [
{"value": "developer", "label": "开发者"},
{"value": "designer", "label": "设计师"},
{"value": "pm", "label": "产品经理"}
]
},
{
"name": "experience",
"label": "工作经验",
"type": "radio",
"required": true,
"options": [
{"value": "1-3", "label": "1-3年"},
{"value": "3-5", "label": "3-5年"},
{"value": "5+", "label": "5年以上"}
]
},
{
"name": "reason",
"label": "申请理由",
"type": "textarea",
"required": true,
"rows": 4,
"placeholder": "请简述您申请测试的理由",
"description": "请详细说明您的使用场景和期望"
}
],
"status": "ACTIVE"
}
```
## API 方法
### showApplicationForm()
显示申请表单。表单的标题、字段和头部样式将根据 `campaignId` 从后端动态获取。
```javascript
betaflow.showApplicationForm();
```
**动态表单功能：**
- 表单标题、字段配置和头部样式从后端获取
- 支持多种字段类型：text、email、tel、url、textarea、select、radio、checkbox、number、date
- 支持字段验证规则和默认值
- 支持自定义表单头部（标题、副标题、描述、图标、背景色等）
- 如果后端获取失败，将使用默认表单配置
### hideApplicationForm()
隐藏申请表单
```javascript
betaflow.hideApplicationForm();
```
### showFloatingButton()
显示浮动按钮
```javascript
betaflow.showFloatingButton();
```
### hideFloatingButton()
隐藏浮动按钮
```javascript
betaflow.hideFloatingButton();
```
### submitApplication(data)
提交申请数据
````javascript
const response = await betaflow.submitApplication({
name: '张三',
email: 'zhangsan@example.com',
company: '示例公司',
position: '产品经理',
reason: '希望体验新功能'
});
### getCampaignInfo()
获取活动信息
```javascript
const campaignInfo = await betaflow.getCampaignInfo();
````
### verifyUserApplication(request)
验证用户申请状态 - **新功能**
通过用户邮箱或手机号验证其公测申请状态，返回详细的状态信息和错误码。
**参数:**
- `request.email` (string, 可选): 用户邮箱
- `request.phone` (string, 可选): 用户手机号
- 注意：邮箱和手机号至少提供一个
**返回值:**
```typescript
interface UserVerificationResponse {
success: boolean; // 验证是否成功
message: string; // 响应消息
status?: "NOT_APPLIED" | "PENDING" | "APPROVED" | "REJECTED"; // 申请状态
errorCode?:
| "USER_NOT_APPLIED"
| "USER_NOT_APPROVED"
| "INVALID_PARAMS"
| "NETWORK_ERROR"; // 错误码
applicationData?: any; // 申请数据（如果存在）
}
```
**使用示例:**
```javascript
// 通过邮箱验证
const result = await betaflow.verifyUserApplication({
email: "user@example.com",
});
if (result.success) {
console.log("✅ 用户已通过审核");
// 允许访问公测功能
enableBetaFeatures();
} else {
// 根据错误码处理不同情况
switch (result.errorCode) {
case "USER_NOT_APPLIED":
console.log("❌ 用户未申请公测");
betaflow.showApplicationForm(); // 引导用户申请
break;
case "USER_NOT_APPROVED":
if (result.status === "PENDING") {
console.log("⏳ 申请审核中");
} else if (result.status === "REJECTED") {
console.log("❌ 申请已被拒绝");
}
break;
case "MISSING_API_KEY":
console.log("🔑 API Key 未配置");
break;
case "NETWORK_ERROR":
console.log("🌐 网络错误，请稍后重试");
break;
}
}
// 通过手机号验证
const phoneResult = await betaflow.verifyUserApplication({
phone: "+86 138 0013 8000",
});
// 同时提供邮箱和手机号（优先使用邮箱）
const combinedResult = await betaflow.verifyUserApplication({
email: "user@example.com",
phone: "+86 138 0013 8000",
});
```
**错误码说明:**
- `USER_NOT_APPLIED`: 用户未申请公测
- `USER_NOT_APPROVED`: 用户已申请但未通过审核（包括待审核、已拒绝等状态）
- `MISSING_API_KEY`: API Key 未配置，需要在初始化时提供 apiKey
- `INVALID_PARAMS`: 参数无效，需要提供邮箱或手机号
- `NETWORK_ERROR`: 网络错误或服务器错误
**完整示例:** 查看 [examples/user-verification.js](examples/user-verification.js) 了解更多使用场景。
### updateConfig(newConfig)
更新配置
```javascript
betaflow.updateConfig({
theme: "dark",
language: "en-US",
});
```
### setLanguage(language)
设置语言
```javascript
betaflow.setLanguage("en-US");
```
### setTheme(theme)
设置主题
```javascript
betaflow.setTheme("dark");
```
### diagnose()
运行完整的 SDK 诊断 - **🎉 v1.2.7+ 功能**
这是一个强大的调试工具，可以帮助您快速定位和解决 SDK 集成问题。
```javascript
// 运行完整诊断
const diagnosis = await betaflow.diagnose();
console.log("诊断结果:", diagnosis);
// 诊断结果包含：
// - 配置验证
// - 网络连接测试
// - API 端点检查
// - 活动信息验证
// - 详细的错误信息和建议
```
**诊断结果示例:**
```javascript
{
timestamp: "2024-01-15T10:30:00.000Z",
config: {
apiEndpoint: "https://betaflow.fulitimes.com/api",
campaignId: "test-campaign",
hasApiKey: false,
debug: true
},
tests: [
{
name: "配置验证",
status: "passed",
message: "所有必需配置项都已正确设置"
},
{
name: "网络连接",
status: "passed",
message: "API 端点可访问",
responseTime: 45
}
],
summary: {
passed: 4,
failed: 0,
warnings: 1
}
}
```
### destroy()
销毁 SDK 实例
```javascript
betaflow.destroy();
```
## 浮动按钮位置
支持以下位置选项：
- `bottom-right` (默认)
- `bottom-left`
- `top-right`
- `top-left`
- `bottom-center`
## 主题定制
### 内置主题
- `light` (默认)
- `dark`
### 自定义样式
```javascript
const betaflow = new BetaFlow({
tenantId: "YOUR_TENANT_ID",
campaignId: "YOUR_CAMPAIGN_ID",
customStyles: `
.betaflow-button {
background: linear-gradient(135deg, #ff6b6b 0%, #ee5a24 100%) !important;
}
.betaflow-form {
border-radius: 20px !important;
}
`,
});
```
## TypeScript 支持
SDK 提供完整的 TypeScript 类型定义：
```typescript
import BetaFlow, { BetaFlowConfig, ApplicationData } from "betaflow-sdk";
// 🎉 v1.2.9 统一认证配置
const config: BetaFlowConfig = {
campaignId: "YOUR_CAMPAIGN_ID", // 必需
apiKey: "YOUR_API_KEY", // 必需
language: "zh-CN",
theme: "light",
debug: true, // 推荐开启调试模式
};
const betaflow = new BetaFlow(config);
const applicationData: ApplicationData = {
name: "张三",
email: "zhangsan@example.com",
company: "示例公司",
};
// 提交申请
await betaflow.submitApplication(applicationData);
// 🎉 v1.2.7+ 功能：运行诊断
const diagnosis = await betaflow.diagnose();
console.log("SDK 诊断结果:", diagnosis);
```
## 示例和演示
### 📁 示例文件
我们在 `examples/` 目录中提供了多个示例文件：
- **[demo.html](examples/demo.html)** - 完整的交互式演示页面
- 包含所有功能的实时演示
- 可配置的选项面板
- API 测试工具
- 完整的使用示例
- **[npm-usage.js](examples/npm-usage.js)** - NPM 使用示例
- Node.js 环境使用方法
- 浏览器环境集成
- React/Vue 组件示例
- 错误处理最佳实践
### 🚀 本地运行演示
```bash
# 克隆项目
git clone https://github.com/saudm/betaflow-sdk.git
cd betaflow-sdk
# 安装依赖并构建
npm install
npm run build
# 启动本地服务器
python3 -m http.server 8080
# 访问演示页面
# http://localhost:8080/examples/demo.html
```
## 错误处理
### 🎉 v1.2.9 增强的错误处理
```javascript
const betaflow = new BetaFlow({
campaignId: "YOUR_CAMPAIGN_ID",
apiKey: "YOUR_API_KEY", // 必需参数
debug: true, // 开启调试模式获取详细错误信息
onFormError: (error) => {
console.error("SDK 错误:", error.message);
console.error("错误码:", error.code);
// 根据错误码处理不同情况
switch (error.code) {
case "FETCH_FAILED":
console.log("💡 建议：检查网络连接和 API 端点");
break;
case "CAMPAIGN_NOT_FOUND":
console.log("💡 建议：验证 campaignId 是否正确");
break;
case "UNAUTHORIZED":
console.log("💡 建议：检查 apiKey 配置");
break;
case "MISSING_API_KEY":
console.log("💡 建议：确保在初始化时提供 apiKey 参数");
break;
}
},
});
// 使用 try-catch 和诊断工具
try {
const response = await betaflow.submitApplication(data);
console.log("提交成功:", response);
} catch (error) {
console.error("提交失败:", error.message);
// 🎉 v1.2.7+ 功能：运行诊断获取详细信息
const diagnosis = await betaflow.diagnose();
console.log("诊断结果:", diagnosis);
}
```
### 常见错误码
| 错误码 | 描述 | 解决方案 |
| -------------------- | ------------ | -------------------------------- |
| `FETCH_FAILED` | 网络请求失败 | 检查 API 端点和网络连接 |
| `CAMPAIGN_NOT_FOUND` | 活动不存在 | 验证 `campaignId` 是否正确 |
| `UNAUTHORIZED` | API 认证失败 | 检查 `apiKey` 配置是否正确 |
| `MISSING_API_KEY` | API 密钥缺失 | 确保在初始化时提供 `apiKey` 参数 |
| `TIMEOUT` | 请求超时 | 检查网络连接稳定性 |
| `INVALID_CONFIG` | 配置无效 | 运行 `diagnose()` 获取详细信息 |
### 调试技巧
```javascript
// 1. 开启调试模式
const betaflow = new BetaFlow({
campaignId: "YOUR_CAMPAIGN_ID",
apiKey: "YOUR_API_KEY", // 必需参数
debug: true, // 获取详细日志
});
// 2. 运行完整诊断
const diagnosis = await betaflow.diagnose();
if (diagnosis.summary.failed > 0) {
console.error(
"发现问题:",
diagnosis.tests.filter((t) => t.status === "failed")
);
}
// 3. 检查配置
console.log("当前配置:", betaflow.config);
```
## 浏览器兼容性
- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+
- IE 11+ (需要 polyfill)
## 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件
## 贡献
欢迎提交 Issue 和 Pull Request！
## 支持
如果您在使用过程中遇到问题，请：
1. 🎮 **[查看在线演示](examples/demo.html)** - 实时测试和学习 SDK 功能
2. 📖 **[查看文档](https://github.com/saudm/betaflow-sdk#readme)** - 完整的 API 文档和使用指南
3. 💡 **[查看示例](examples/)** - 多种使用场景的代码示例
4. 🔍 **[搜索 Issues](https://github.com/saudm/betaflow-sdk/issues)** - 查看已知问题和解决方案
5. 🆘 **[提交 Issue](https://github.com/saudm/betaflow-sdk/issues/new)** - 报告新问题或功能请求
## 版本更新说明
### 🎉 v1.2.9 (最新版本)
**重大改进：**
- 🔑 **统一认证**: `apiKey` 现在是必需参数，移除 `tenantId` 参数
- ✅ **简化配置**: 只需 `campaignId` 和 `apiKey` 两个必需参数即可开始
- 🚀 **智能初始化**: 自动检测和配置 API 端点，减少配置复杂度
- 🌐 **默认服务器**: 使用官方服务器 `https://betaflow.fulitimes.com/api` 作为默认端点
- 🛠️ **新增诊断工具**: `diagnose()` 方法提供完整的 SDK 状态诊断
- 📱 **增强错误处理**: 详细的错误码、调试信息和解决建议
- 🎯 **更好的开发体验**: 推荐开启 `debug` 模式获得详细日志
**迁移指南：**
```javascript
// v1.2.7 及之前版本
const betaflow = new BetaFlow({
campaignId: "YOUR_CAMPAIGN_ID", // 必需
apiEndpoint: "https://your-domain.com/api", // 必需
});
// 🎉 v1.2.9 统一认证版本 - 使用默认官方服务器
const betaflow = new BetaFlow({
campaignId: "YOUR_CAMPAIGN_ID", // 必需
apiKey: "YOUR_API_KEY", // 必需
debug: true, // 推荐开启调试模式
});
// 如需使用自定义服务器
const betaflow = new BetaFlow({
campaignId: "YOUR_CAMPAIGN_ID",
apiEndpoint: "https://your-custom-server.com/api",
});
// 如果遇到问题，运行诊断
const diagnosis = await betaflow.diagnose();
```
**向后兼容性：** v1.2.9 完全向后兼容，现有代码无需修改即可正常工作。
---
**BetaFlow Team** - 让 Beta 测试更简单！