betaflow-sdk

v1.3.9

Published

16 days ago

BetaFlow SDK for web applications - A powerful tool for managing beta testing campaigns and user feedback

0High
0Medium
0Low

submit2mxh

betaflow sdk beta-testing feedback user-testing campaign-management javascript typescript web

BetaFlow SDK

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

npm install betaflow-sdk

CDN 引入

国内用户（阿里云 CDN）

<script src="https://fuli-img.oss-cn-beijing.aliyuncs.com/sdk/latest/betaflow.min.js"></script>

海外用户（GitHub Pages CDN）

<script src="https://saudm.github.io/betaflow-sdk/sdk/latest/betaflow.min.js"></script>

在线演示

🎮 查看在线演示页面

我们提供了一个完整的交互式演示页面，您可以：

实时测试所有 SDK 功能
查看不同配置选项的效果
测试 API 调用和错误处理
体验响应式设计和主题切换
查看完整的使用示例代码

演示页面包含：

📦 安装指南: NPM 和 CDN 两种安装方式
🎮 功能演示: 表单显示/隐藏、浮动按钮控制
⚙️ 配置面板: 语言、主题、位置、调试模式设置
🔧 API 测试: 活动信息获取、申请提交、连接测试
📝 代码示例: 完整的集成代码参考
📊 状态监控: SDK 运行状态实时显示

快速开始

NPM 使用方式

如果您使用现代前端框架，可以通过 NPM 安装：

npm install betaflow-sdk

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 使用方式

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

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

配置选项

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

响应格式：

{
  "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 从后端动态获取。

betaflow.showApplicationForm();

动态表单功能：

表单标题、字段配置和头部样式从后端获取
支持多种字段类型：text、email、tel、url、textarea、select、radio、checkbox、number、date
支持字段验证规则和默认值
支持自定义表单头部（标题、副标题、描述、图标、背景色等）
如果后端获取失败，将使用默认表单配置

hideApplicationForm()

隐藏申请表单

betaflow.hideApplicationForm();

showFloatingButton()

显示浮动按钮

betaflow.showFloatingButton();

hideFloatingButton()

隐藏浮动按钮

betaflow.hideFloatingButton();

submitApplication(data)

提交申请数据

const response = await betaflow.submitApplication({
  name: '张三',
  email: '[email protected]',
  company: '示例公司',
  position: '产品经理',
  reason: '希望体验新功能'
});
### getCampaignInfo()
获取活动信息

```javascript
const campaignInfo = await betaflow.getCampaignInfo();

verifyUserApplication(request)

验证用户申请状态 - 新功能

通过用户邮箱或手机号验证其公测申请状态，返回详细的状态信息和错误码。

参数:

request.email (string, 可选): 用户邮箱
request.phone (string, 可选): 用户手机号
注意：邮箱和手机号至少提供一个

返回值:

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; // 申请数据（如果存在）
}

使用示例:

// 通过邮箱验证
const result = await betaflow.verifyUserApplication({
  email: "[email protected]",
});

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: "[email protected]",
  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 了解更多使用场景。

updateConfig(newConfig)

更新配置

betaflow.updateConfig({
  theme: "dark",
  language: "en-US",
});

setLanguage(language)

设置语言

betaflow.setLanguage("en-US");

setTheme(theme)

设置主题

betaflow.setTheme("dark");

diagnose()

运行完整的 SDK 诊断 - 🎉 v1.2.7+ 功能

这是一个强大的调试工具，可以帮助您快速定位和解决 SDK 集成问题。

// 运行完整诊断
const diagnosis = await betaflow.diagnose();
console.log("诊断结果:", diagnosis);

// 诊断结果包含：
// - 配置验证
// - 网络连接测试
// - API 端点检查
// - 活动信息验证
// - 详细的错误信息和建议

诊断结果示例:

{
  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 实例

betaflow.destroy();

浮动按钮位置

支持以下位置选项：

bottom-right (默认)
bottom-left
top-right
top-left
bottom-center

主题定制

内置主题

light (默认)
dark

自定义样式

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 类型定义：

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: "[email protected]",
  company: "示例公司",
};

// 提交申请
await betaflow.submitApplication(applicationData);

// 🎉 v1.2.7+ 功能：运行诊断
const diagnosis = await betaflow.diagnose();
console.log("SDK 诊断结果:", diagnosis);

示例和演示

📁 示例文件

我们在 examples/ 目录中提供了多个示例文件：

demo.html - 完整的交互式演示页面
- 包含所有功能的实时演示
- 可配置的选项面板
- API 测试工具
- 完整的使用示例
npm-usage.js - NPM 使用示例
- Node.js 环境使用方法
- 浏览器环境集成
- React/Vue 组件示例
- 错误处理最佳实践

🚀 本地运行演示

# 克隆项目
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 增强的错误处理

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() 获取详细信息 |

调试技巧

// 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 文件

贡献

欢迎提交 Issue 和 Pull Request！

支持

如果您在使用过程中遇到问题，请：

🎮 查看在线演示 - 实时测试和学习 SDK 功能
📖 查看文档 - 完整的 API 文档和使用指南
💡 查看示例 - 多种使用场景的代码示例
🔍 搜索 Issues - 查看已知问题和解决方案
🆘 提交 Issue - 报告新问题或功能请求

版本更新说明

🎉 v1.2.9 (最新版本)

重大改进：

🔑 统一认证: apiKey 现在是必需参数，移除 tenantId 参数
✅ 简化配置: 只需 campaignId 和 apiKey 两个必需参数即可开始
🚀 智能初始化: 自动检测和配置 API 端点，减少配置复杂度
🌐 默认服务器: 使用官方服务器 https://betaflow.fulitimes.com/api 作为默认端点
🛠️ 新增诊断工具: diagnose() 方法提供完整的 SDK 状态诊断
📱 增强错误处理: 详细的错误码、调试信息和解决建议
🎯 更好的开发体验: 推荐开启 debug 模式获得详细日志

迁移指南：

// 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 测试更简单！