flux-web/docs/jverify-configuration.md

极光一键登录集成配置说明

🎯 功能概述

已成功集成极光一键登录功能到薇钱包H5应用中，支持：

• ✅ 极光一键登录（无需输入手机号和验证码）
• ✅ 自动降级到短信验证码登录（当一键登录不可用时）
• ✅ 智能检测运营商网络环境

---

📝 配置步骤

1. 配置极光应用ID

编辑文件：src/js/pages/index.page.js

找到第30行：

// 极光一键登录配置
this.jVerifyAppId = ''; // 需要配置极光应用ID

修改为：

// 极光一键登录配置
this.jVerifyAppId = '您的极光AppKey'; // 例如：'a1b2c3d4e5f6g7h8i9j0'

2. 获取极光AppKey

1. 登录 极光官网
2. 进入「JVerification」产品
3. 创建应用或使用现有应用
4. 在应用设置中获取 AppKey

---

🔄 工作流程

用户打开页面
    ↓
检测是否配置了极光AppKey？
    ↓
┌────────────┬────────────┐
│  已配置     │  未配置     │
│  检测SDK   │  直接使用   │
│  可用性    │  短信验证  │
└────────────┴────────────┘
    ↓
SDK可用？
    ↓
┌────────────┬────────────┐
│  是        │  否         │
│  显示"一键  │  降级到    │
│  登录"按钮  │  短信验证  │
└────────────┴────────────┘
    ↓
用户点击"一键登录"
    ↓
获取Token → 验证成功？
    ↓
┌────────────┬────────────┐
│  成功      │  失败       │
│  自动登录  │  降级到    │
│  跳转页面  │  短信验证  │
└────────────┴────────────┘

---

🎨 UI展示

一键登录可用时：

┌─────────────────────────┐
│   📱 一键登录            │  ← 紫色渐变按钮
├─────────────────────────┤
│   ─────────── 或 ───────  │
│                         │
│  手机号: [____________] │
│  立即申请                │
└─────────────────────────┘

一键登录不可用时（自动降级）：

┌─────────────────────────┐
│                         │
│  手机号: [____________] │
│  立即申请                │
└─────────────────────────┘

---

🔧 后端API配置

后端服务部署在服务器上（非本地开发环境）

1. API端点

   • 一键登录验证：POST /zcore/jpush/login
   • 请求参数：

     {
       "appId": "您的极光AppKey",
       "loginToken": "极光SDK获取的token"
     }
     

2. 本地开发配置

   • 如需本地调试前端，请在 src/js/config/index.js 中配置 API 代理
   • 或直接修改 src/js/services/jverify.service.js 中的 apiUrl 指向服务器地址

3. 确保后端服务运行

   • 服务器上的后端服务需要正常运行并可访问
   • 确保CORS配置正确，允许前端域名访问

---

📱 测试步骤

1. 配置AppKey

编辑 src/js/pages/index.page.js，设置 this.jVerifyAppId

2. 启动前端服务

# 在 IDEA 中右键 index.html → Open In Browser

3. 观察行为

场景A：极光SDK可用

• ✅ 显示"一键登录"按钮
• ✅ 点击后自动登录
• ✅ 成功后跳转页面

场景B：极光SDK不可用

• ✅ 自动隐藏"一键登录"按钮
• ✅ 直接显示手机号输入框
• ✅ 使用短信验证码登录

场景C：一键登录失败

• ✅ 显示降级提示
• ✅ 自动切换到短信验证码登录

---

🐛 调试方法

查看控制台日志

// 一键登录初始化
[IndexPage] 未配置极光应用ID，跳过一键登录  // 需要配置AppKey
[OneClickLoginButton] 一键登录可用          // SDK加载成功
[OneClickLoginButton] 一键登录不可用        // SDK加载失败，会自动降级

// 一键登录过程
[JVerifyService] 极光SDK初始化成功
[JVerifyService] 获取token成功
[JVerifyService] 一键登录成功: 138****8000
[IndexPage] 一键登录后注册成功

常见问题

问题1：不显示一键登录按钮

• ✅ 检查是否配置了 this.jVerifyAppId
• ✅ 打开控制台查看错误信息
• ✅ 确认用户未登录状态

问题2：点击后无反应

• ✅ 检查后端服务是否运行
• ✅ 检查网络请求（F12 → Network标签）
• ✅ 查看控制台错误

问题3：登录失败但未降级

• ✅ 检查 onFallback 回调是否正常
• ✅ 查看后端返回的错误信息

---

🔐 安全建议

1. 保护AppKey

   • 不要将AppKey硬编码在前端（考虑从后端获取）
   • 生产环境使用环境变量

2. 手机号保护

   • 后端响应已包含 phoneMasked（脱敏手机号）
   • 生产环境建议移除 phone 字段

3. HTTPS传输

   • 生产环境强制使用HTTPS
   • 防止中间人攻击

---

📚 相关文件清单

新增文件

src/js/
├── services/
│   └── jverify.service.js          # 极光一键登录服务
├── ui/
│   └── one-click-login.js          # 一键登录按钮组件
└── pages/
    └── index.page.js               # 主页面（已集成）

src/css/components/
└── one-click-login.css             # 一键登录样式

修改文件

index.html                           # 添加了一键登录容器和CSS引用

---

✅ 完成检查清单

• 配置极光AppKey（在 index.page.js 中）
• 启动后端服务 ali-sms
• 测试一键登录功能（手机端访问）
• 测试降级逻辑（关闭WiFi，使用4G/5G）
• 测试登录失败场景
• 检查生产环境配置

---

🎉 完成效果

配置完成后，用户将享受：

1. 更快的登录体验 - 无需输入手机号和验证码
2. 无缝降级 - 一键登录不可用时自动切换
3. 更好的用户体验 - 减少操作步骤

一键登录成功率通常达到 85%+！ 📈

---

配置完成日期： 2025-01-22 集成人员： Claude Code 版本： 2.1.0