1 产品概述

闪验 SDK 是基于运营商网关认证能力的一键登录解决方案。用户只需点击"一键登录"按钮，即可自动获取本机手机号码，完成登录/注册，无需手动输入手机号和短信验证码。

2 核心能力

• 一键登录：用户在授权页点击确认，SDK自动获取当前流量卡对应的token，通过服务端可置换完整手机号码。

• 三网支持：自动适配移动、联通、电信三大运营商，一套配置三网共用。

• 网络支持：支持WiFi+数据网络和纯数据流量网络。

3 接入准备

3.1 平台申请

1. 在微信公众平台申请微信小程序能力，获取 wxappid

2. 在创蓝平台注册账号，创建应用并获取 appId 和 appkey

3. 在腾讯公众平台小程序后台添加取号插件："设置" → "第三方服务" → "插件管理" → 搜索 "智能链接" 申请添加

3.2 重要参数说明

4 SDK 快速接入

4.1 安装 SDK

在小程序项目根目录下执行：

复制成功⧉
npm install shanyan-miniprogram-sdk@latest

安装完成后，在微信开发者工具中点击 工具 → 构建 npm，生成 npm 依赖。

4.2 引入插件包

注意：下面5项必须按要求配置，否则可能无法启动授权页。

① app.json 中引用插件：

复制成功⧉
{
  "pages": [
    "pages/index/index"
  ],
  "plugins": {
    "auth-plugin": {
      "version": "2.3.5",
      "provider": "wx35678fec06d475b4"
    }
  }
}

② 页面 json 文件中声明插件组件：

复制成功⧉
{
  "usingComponents": {
    "onekeylogin": "plugin://auth-plugin/onekeylogin"
  }
}

③ 页面wxml文件引用：

复制成功⧉
<onekeylogin/>

④ js 文件中引入 SDK：

复制成功⧉
const SDK = require('shanyan-miniprogram-sdk');

⑤ 配置服务器域名：

登录微信小程序平台，进入 管理→ 开发管理→ 服务器域名，在request合法域名中配置下列地址：

复制成功⧉
https://api.253.com;https://fs.cl2009.com;https://sy.cl2m.cn;https://h5.253.com;https://h5auth.cmpassport.com;https://log-h5.cmpassport.com:9443;https://verify.cmpassport.com;https://www.cmpassport.com;

4.3 初始化 SDK

初始化SDK，为后续取号功能做准备。 ● 初始化会采集信息，建议放到同意隐私协议后调用。 ● 调用SDK其他流程方法前，请确保已调用过初始化。 ● 初始化首次调用有网络请求，后续会使用缓存，如果不使用缓存可以调用clearScripCache方法清理缓存。

复制成功⧉
SDK.init({ appId: 'YOUR_APP_ID' }, (res) => {
  if (res.code === '200000') {
    console.log('初始化成功, msgId:', res.msgId);
  } else {
    console.log('初始化失败:', res.message);
  }
});

回调参数：

4.4 预检查网络环境（可选，建议调用）

判断当前网络环境是否支持一键登录取号。此方法为可选方法，但建议在拉起授权页之前调用，可提前识别不支持取号的场景（如纯 WiFi 环境、疑似热点等），并做相应降级处理，避免直接调用 openLoginAuth 后因网络环境不支持而失败。

● 需在 init 成功后调用。 ● 插件会判断用户当前网络状态：数据网络或 WiFi+数据网络状态下支持取号，纯 WiFi 热点（无数据网络）状态下不支持取号。

复制成功⧉
SDK.preCheckMobile((res) => {
  if (res.code === '0') {
    // 网络环境支持取号，可以拉起授权页
    SDK.openLoginAuth((authRes) => { /* ... */ });
  } else if (res.code === '504') {
    // 网络环境不支持取号，建议降级为短信验证码登录
    console.log('网络不支持取号:', res.message);
  } else if (res.code === '505') {
    // 疑似热点环境
    console.log('疑似热点环境:', res.message);
  } else {
    console.log('预检查失败:', res.message);
  }
});

回调参数：

4.5 打开授权页

调用此方法会启动一键登录授权页，用户授权后将返回认证token。

● 拉起授权页方法会启一键登录授权页面，已登录状态请勿调用 。 ● 一键登录成功率会受网络环境、SIM卡状态等影响，不能作为唯一登录方式，建议在拉起授权页失败回调处做降级逻辑处理，避免造成自身APP功能异常。 ●不要连续调用或者在授权页已经展示时调用，否则可能会有异常。 ● 如果需要修改授权页界面配置，请传入可选界面配置入参option，详见授权页自定义配置。

复制成功⧉
SDK.openLoginAuth((res) => {
  if (res.code === '200000') {
    console.log('取号成功, token:', res.token);
    console.log('msgId:', res.msgId);
    // 将 token 发送到业务服务端校验换取手机号
  } else if (res.code === '501') {
    console.log('用户取消授权');
  } else {
    console.log('取号失败:', res.message);
  }
});

回调参数：

cfg 可选入参：

4.5.1 授权页事件回调（v1.1.3 新增）

SDK v1.1.3 起支持授权页加载成功、勾选协议和用户点击登录按钮的回调，通过 openLoginAuth 的 cfg 传入：

复制成功⧉
SDK.openLoginAuth({
  // UI 配置（可选）
  option: { ... },
  // 授权弹窗加载成功
  authLoadSuccess: (res) => {
    console.log('授权页加载成功, msgId:', res.msgId);
    // 适合在这里关闭拉起授权页前的 loading
  },
  // 点击登录按钮和协议勾选框的监听
  clickListenerCallback: (res) => {
    if (res.code === '1') {
      console.log('用户点击登录按钮');
    } else if (res.code === '2') {
      console.log('用户点击协议勾选框, 勾选状态:', res.checked);
    }
  }
}, (res) => {
  // 授权结果回调（同上文）
});

authLoadSuccess 回调参数：

clickListenerCallback 回调参数：

4.6 置换手机号

当一键登录外层 code 为 200000 时，会获取到置换手机号所需的 token。请参考「服务端」文档来实现获取手机号码的步骤

4.7 完整调用流程示例

复制成功⧉
// 1. 初始化
SDK.init({ appId: 'your_app_id' }, (initRes) => {
  if (initRes.code !== '200000') {
    wx.showToast({ title: '初始化失败', icon: 'none' });
    return;
  }

  // 2. 打开授权页
  SDK.openLoginAuth((authRes) => {
    if (authRes.code === '200000') {
      // 3. 将 token 发送到你的业务服务端
      wx.request({
        url: 'https://your-server.com/api/verify-token',
        method: 'POST',
        data: { token: authRes.token },
        success: (res) => {
          // 4. 登录成功，进入你的业务逻辑
          wx.navigateTo({ url: '/pages/home/home' });
        }
      });
    } else if (authRes.code === '501') {
      wx.showToast({ title: '已取消授权', icon: 'none' });
    } else {
      wx.showToast({ title: authRes.message, icon: 'none' });
    }
  });
});

5 SDK 其他API 说明

5.1 设置日志开关

通过SDK.setLog(flag)可以设置 SDK 内部 console 日志输出开关。

5.2 设置初始化超时时间

通过SDK.setInitTimeout(ms)可以设置 init 接口超时时间，单位毫秒。

超时后返回 code: '001023', message: '超时'。

5.3 清理初始化缓存

通过SDK.clearScripCache()可以清理本地初始化缓存。调用后下次 init 将重新请求服务端获取参数。

6 授权页自定义配置

授权页通过 SDK.openLoginAuth({ option: { ... } }, callback) 传入配置。

6.1 配置项示例

复制成功⧉
SDK.openLoginAuth({
  option: {
    logoStyle: {
      src: 'https://example.com/logo.png',
      width: '200rpx',
      height: '200rpx',
    },
    sureBtnStyle: {
      text: '一键登录',
      bgColor: '#2b7de0',
    },
  }
}, (res) => { ... });

未勾选协议二次确认弹窗示例（v1.1.3 新增）：

默认（msgType='0'）未勾选协议点击按钮时出现箭头提示框；配置 msgType='1' 切换为底部提示框，并可通过 msg*Style 系列配置自定义样式：

复制成功⧉
SDK.openLoginAuth({
  option: {
    msgType: '1',
    msgMaskStyle: {            // 提示框蒙层
      ifShow: true,
      bgColor: 'rgba(0, 0, 0, 0.5)',
    },
    msgPanelStyle: {           // 提示框面板
      width: '100%',
      height: '364rpx',
      bottom: 'center',
      left: 'center',
      bgColor: '#FFFFFF',
      radius: '40rpx',
    },
    // 其余可选：msgTextStyle（协议栏文案）、msgLinkStyle（协议链接样式）、
    //           msgSureBtnStyle（确认按钮）、msgCancelBtnStyle（取消按钮），详见 6.2
  }
}, (res) => { ... });

6.2 配置项详细说明

6.3 自定义控件说明

customControlStyle 为数组格式，支持在授权页添加自定义按钮控件。

openType 取值说明（对应微信小程序标准页面跳转 API）：

移动官方文档未标注 openType 默认值，建议显式传入。跳转目标页面需在小程序 app.json 的 pages 中注册（tabBar 页需在 tabBar.list 中）。

7 返回码说明

7.1 SDK 返回码

7.2 运营商返回码

移动取号：

电信取号：

联通取号：

获取 token：