微信小程序集成文档
更新时间:2026-07-30 17:18:31
1 产品概述
闪验 SDK 是基于运营商网关认证能力的一键登录解决方案。用户只需点击"一键登录"按钮,即可自动获取本机手机号码,完成登录/注册,无需手动输入手机号和短信验证码。

2 核心能力
-
一键登录:用户在授权页点击确认,SDK自动获取当前流量卡对应的token,通过服务端可置换完整手机号码。
-
三网支持:自动适配移动、联通、电信三大运营商,一套配置三网共用。
-
网络支持:支持WiFi+数据网络和纯数据流量网络。
3 接入准备
3.1 平台申请
-
在微信公众平台申请微信小程序能力,获取 wxappid
-
在创蓝平台注册账号,创建应用并获取 appId 和 appkey
-
在腾讯公众平台小程序后台添加取号插件:
"设置" → "第三方服务" → "插件管理"→ 搜索 "智能链接" 申请添加
3.2 重要参数说明
| 参数 | 说明 |
|---|---|
| wxappid | 微信平台分配的微信小程序ID |
| appId | 创蓝平台分配的应用AppId,用于 SDK 初始化 |
| appkey | 创蓝平台分配的密钥,用于服务端 token 校验及手机号解密 |
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.2.2",
"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('初始化成功, traceId:', res.traceId);
} else {
console.log('初始化失败:', res.message);
}
});回调参数:
| 参数 | 类型 | 说明 |
|---|---|---|
| code | string | '200000'=成功,其他=失败 |
| message | string | 结果描述 |
| traceId | string | 请求追踪 ID(成功时返回) |
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);
}
});回调参数:
| 参数 | 类型 | 说明 |
|---|---|---|
| code | string | '0'=支持取号,'504'=不支持,'505'=疑似热点,其他=失败 |
| message | string | 结果描述 |
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);
}
});回调参数:
| 参数 | 类型 | 说明 |
|---|---|---|
| code | string | '200000'=成功,'501'=用户取消,其他=失败 |
| message | string | 结果描述 |
| token | string | 取号凭证(成功时返回,用于服务端校验) |
| msgId | string | 消息 ID(成功时返回) |
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 日志输出开关。
| 参数 | 类型 | 说明 |
|---|---|---|
| flag | boolean | true=开启日志,false=关闭(默认) |
5.2 设置初始化超时时间
通过SDK.setInitTimeout(ms)可以设置 init 接口超时时间,单位毫秒。
| 参数 | 类型 | 说明 |
|---|---|---|
| ms | number | 超时时间(毫秒),默认 6000 |
超时后返回 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) => { ... });6.2 配置项详细说明

| 配置模块 | 字段 | 含义 | 值 | 说明 |
|---|---|---|---|---|
| ①logo | logoStyle.width | Logo宽度 | 百分比或数值,如200rpx | 可选 |
| logoStyle.height | Logo高度 | 百分比或数值 | 可选 | |
| logoStyle.src | Logo图片路径 | URL路径 | 可选,默认创蓝logo | |
| logoStyle.top | logo距页面上边框距离 | 百分比或数值,如20rpx | 可选 | |
| logoStyle.left | logo距页面左边框距离 | 数值或center | 可选 | |
| ②小程序名称 | bussinessNameStyle.text | 小程序名称文案 | string | 可选 |
| bussinessNameStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 | |
| bussinessNameStyle.fontColor | 字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| bussinessNameStyle.fontSize | 字体大小 | 数值,如32rpx | 可选 | |
| bussinessNameStyle.top | 距上边框距离 | 百分比或数值 | 可选 | |
| bussinessNameStyle.left | 距左边框距离 | 数值或center | 可选 | |
| ③授权栏 | authTextStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 |
| authTextStyle.fontColor | 字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| authTextStyle.fontSize | 字体大小 | 数值 | 可选 | |
| authTextStyle.top | 距上边框距离 | 百分比或数值 | 可选 | |
| authTextStyle.left | 距左边框距离 | 数值或center | 可选 | |
| ④授权提示栏 | authTipStyle.ifShow | 是否展示提示栏 | boolean | 可选 |
| authTipStyle.text | 提示栏文案 | string | 可选 | |
| authTipStyle.width | 提示栏宽度 | 百分比或数值,如200rpx | 可选 | |
| authTipStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 | |
| authTipStyle.fontColor | 文案的字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| authTipStyle.fontSize | 文案的字体大小 | 数值 | 可选 | |
| authTipStyle.top | 距上边框距离 | 百分比或数值 | 可选 | |
| authTipStyle.left | 距左边框距离 | 数值或center | 可选 | |
| ⑤号码栏 | phoneStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 |
| phoneStyle.fontColor | 字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| phoneStyle.fontSize | 文案的字体大小 | 数值 | 可选 | |
| phoneStyle.top | 距上边框距离 | 百分比或数值 | 可选 | |
| phoneStyle.left | 距左边框距离 | 数值或center | 可选 | |
| ⑥提示栏(WiFi+数据网络环境时显示) | tipStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 |
| tipStyle.fontColor | 文案的字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| tipStyle.fontSize | 文案的字体大小 | 数值 | 可选 | |
| tipStyle.top | 距上边框距离 | 百分比或数值 | 可选 | |
| tipStyle.left | 距左边框距离 | 数值或center | 可选 | |
| ⑦取消按钮 | cancleBtnStyle.text | 按钮文案(默认"拒绝") | string,≤6字 | 可选 |
| cancleBtnStyle.textAlign | 文案对齐选项 | “center/left/right” | 可选 | |
| cancleBtnStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 | |
| cancleBtnStyle.fontColor | 字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| cancleBtnStyle.fontSize | 文案的字体大小 | 数值 | 可选 | |
| cancleBtnStyle.top | 距上边框距离 | 百分比或数值 | 可选 | |
| cancleBtnStyle.left | 距左边框距离 | 数值或center | 可选 | |
| cancleBtnStyle.width | 按钮宽度 | 百分比或数值 | 可选 | |
| cancleBtnStyle.height | 按钮高度 | 百分比或数值 | 可选 | |
| cancleBtnStyle.bgColor | 按钮颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| cancleBtnStyle.radius | 按钮圆角 | 百分比或数值 | 可选 | |
| cancleBtnStyle.borderColor | 按钮边框颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| cancleBtnStyle.borderWidth | 按钮边框线宽 | 数值,如“1px” | 可选 | |
| ⑧登录按钮 | sureBtnStyle.text | 按钮文案(默认"授权登录") | string,≤6字 | 可选 |
| sureBtnStyle.textAlign | 文案对齐选项 | “center/left/right” | 可选 | |
| sureBtnStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 | |
| sureBtnStyle.fontColor | 字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| sureBtnStyle.fontSize | 文案的字体大小 | 数值 | 可选 | |
| sureBtnStyle.top | 距上边框距离 | 百分比或数值 | 可选 | |
| sureBtnStyle.left | 距左边框距离 | 数值或center | 可选 | |
| sureBtnStyle.width | 按钮宽度 | 百分比或数值 | 可选 | |
| sureBtnStyle.height | 按钮高度 | 百分比或数值 | 可选 | |
| sureBtnStyle.bgColor | 按钮颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| sureBtnStyle.radius | 按钮圆角 | 百分比或数值 | 可选 | |
| sureBtnStyle.borderColor | 按钮边框颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| sureBtnStyle.borderWidth | 按钮边框线宽 | 数值,如“1px” | 可选 | |
| ⑨协议栏 | agreeLineStyle.textAlign | 文案对齐选项 | “center/left/right” | 可选 |
| agreeLineStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 | |
| agreeLineStyle.fontColor | 字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| agreeLineStyle.fontSize | 文案的字体大小 | 数值 | 可选 | |
| agreeLineStyle.top | 距上边框距离 | 百分比或数值 | 可选 | |
| agreeLineStyle.left | 距左边框距离 | 数值或center | 可选 | |
| agreeLineStyle.width | 文案宽度 | 百分比或数值 | 可选 | |
| ⑩协议勾选框 | checkBtnStyle.uncheck | 未选中图标URL | string | 可选 |
| checkBtnStyle.checked | 选中图标URL | string | 可选 | |
| checkBtnStyle.width | 图标宽度 | 百分比或数值 | 可选 | |
| checkBtnStyle.height | 图标高度 | 百分比或数值 | 可选 | |
| ⑪协议名称 | agreeStyle.contracts | 协议数组 | [{name:"协议名", url:"链接"}] | 可选,仅支持小程序原生协议页面、不支持协议链接 |
| agreeStyle.fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 | |
| agreeStyle.fontColor | 字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 | |
| ⑫自定义控件 | customControlStyle | 数组格式 | 详见下方说明 | 可选 |
| ⑬弹窗 | layerStyle.height | 弹窗高度 | 百分比或数值 | 可选 |
| layerStyle.radius | 弹窗圆角 | 数值 | 可选 | |
| layerStyle.bgColor | 弹窗背景色 | 十六进制颜色码 | 可选 | |
| ⑭蒙层 | maskStyle.ifShowMask | 是否显示蒙层 | boolean,默认true | 可选 |
| maskStyle.bgColor | 蒙层背景色 | 十六进制颜色码 | 可选 | |
| maskStyle.opacity | 蒙层透明度 | 数值 | 可选 |
6.3 自定义控件说明
customControlStyle 为数组格式,支持在授权页添加自定义按钮控件。
| 字段 | 含义 | 值 | 说明 |
|---|---|---|---|
| ifShow | 是否展示 | boolean,默认 false | 必选 |
| id | 控件 ID | string | 可选 |
| openType | 跳转方式 | navigate/redirect/switchTab/reLaunch/navigateBack | 可选 |
| name | 显示文案 | string | 可选 |
| width | 宽度 | 百分比或数值 | 可选 |
| height | 高度 | 百分比或数值 | 可选 |
| top | 距弹窗上边框距离 | 百分比或数值 | 可选 |
| left | 距弹窗左边框距离 | 百分比或数值 | 可选 |
| fontFamily | 文案的字体 | string,如serif/monospace等 | 可选 |
| fontColor | 字体颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 |
| fontSize | 字体大小 | 数值 | 可选 |
| bgColor | 背景颜色 | 十六进制颜色码,如“#FFFFFF” | 可选 |
| textAlign | 文本对齐 | center/left/right | 可选 |
| radius | 圆角 | 数值 | 可选 |
| url | 跳转 URL | URL 链接 | 必选 |
7 返回码说明
7.1 SDK 返回码
| 返回码 | 描述 | 说明 |
|---|---|---|
| 200000 | 成功 | 初始化/取号成功 |
| 001023 | 超时 | init 接口超时 |
| 000400 | 服务端响应为空 | 服务端未返回有效数据 |
| 000401 | 请求服务端失败 | 网络请求异常 |
| 000500 | 请先调用 init 初始化 | openLoginAuth 前未调用 init |
| 000501 | 移动 appId 未初始化 | cmccAppId 未获取到 |
| 000520 | appId 必传 | init 未传入 appId |
| 000600 | SDK 初始化异常 | 初始化过程发生异常 |
| 000601 | SDK 响应处理异常 | 处理服务端响应时发生异常 |
| 000602 | Token 签名计算异常 | 签名计算过程发生异常 |
| 000603 | Token UUID 生成异常 | UUID 生成失败 |
| 000604 | Token 处理异常 | Token 处理过程发生异常 |
| 000605 | Token 插件调用异常 | 调用取号插件时发生异常 |
| 000606 | 网络类型处理异常 | 网络类型处理时发生异常 |
| 000607 | 网络类型调用异常 | 网络类型调用时发生异常 |
| 000001 | 获取网络类型失败 | 获取网络类型失败 |
7.2 运营商返回码
移动取号:
| 返回码 | 描述 |
|---|---|
| 103000 | 成功 |
| 500 | 网络异常,请检查网络设置 |
| 503 | 参数缺失 |
| 130010 | 参数为空 |
| 105002 | 移动网关取号失败 |
| 105112 | 时间戳非法 |
| 105113 | APPID 非法或为空 |
| 103101 | 错误的请求签名 |
| 110023 | 应用没有权益 |
| 110025 | 权益已失效 |
| 110029 | 微信 appid 校验失败 |
电信取号:
| 返回码 | 描述 |
|---|---|
| 103000 | 成功 |
| 301 | 参数错误 |
| 500 | 网络异常 |
| 502 | 电信/联通取号能力关闭 |
| 105003 | 电信网关取号失败 |
| 110023 | 应用没有权益 |
| 110025 | 权益已失效 |
联通取号:
| 返回码 | 描述 |
|---|---|
| 103000 | 成功 |
| 500 | 网络异常 |
| 502 | 电信/联通取号能力关闭 |
| 105001 | 联通网关取号失败 |
| 110023 | 应用没有权益 |
| 110025 | 权益已失效 |
获取 token:
| 返回码 | 描述 |
|---|---|
| 501 | 用户取消授权 |
| 502 | 用户选择其他登录方式 |
| 103002 | 没有填写必传参数 |
| 104000 | app 不存在 |
| 104001 | businessType 校验失败 |
| 104003 | 应用没有权益 |
| 104004 | 权益已失效 |
| 104007 | accessToken 不存在(token 有效期 2 分钟) |
| 104008 | accessToken 校验失败 |
| 104011 | 手机号不能为空 |
| 104012 | 本机号码校验失败 |
这篇文档对您有帮助吗?




