logo
logo
请输入关键词搜索产品或者文档
中国

中国站

创蓝云智

国际站

Innopaas

微信小程序集成文档

更新时间:2026-07-30 17:18:31

1 产品概述

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

扫码体验:
扫码体验

2 核心能力

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

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

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

3 接入准备

3.1 平台申请

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

  2. 在创蓝平台注册账号,创建应用并获取 appIdappkey

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

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);
  }
});

回调参数:

参数类型说明
codestring'200000'=成功,其他=失败
messagestring结果描述
traceIdstring请求追踪 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);
  }
});

回调参数:

参数类型说明
codestring'0'=支持取号,'504'=不支持,'505'=疑似热点,其他=失败
messagestring结果描述

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);
  }
});

回调参数:

参数类型说明
codestring'200000'=成功,'501'=用户取消,其他=失败
messagestring结果描述
tokenstring取号凭证(成功时返回,用于服务端校验)
msgIdstring消息 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 日志输出开关。

参数类型说明
flagbooleantrue=开启日志,false=关闭(默认)

5.2 设置初始化超时时间

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

参数类型说明
msnumber超时时间(毫秒),默认 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 配置项详细说明

配置模块字段含义说明
①logologoStyle.widthLogo宽度百分比或数值,如200rpx可选
logoStyle.heightLogo高度百分比或数值可选
logoStyle.srcLogo图片路径URL路径可选,默认创蓝logo
logoStyle.toplogo距页面上边框距离百分比或数值,如20rpx可选
logoStyle.leftlogo距页面左边框距离数值或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未选中图标URLstring可选
checkBtnStyle.checked选中图标URLstring可选
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控件 IDstring可选
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跳转 URLURL 链接必选

7 返回码说明

7.1 SDK 返回码

返回码描述说明
200000成功初始化/取号成功
001023超时init 接口超时
000400服务端响应为空服务端未返回有效数据
000401请求服务端失败网络请求异常
000500请先调用 init 初始化openLoginAuth 前未调用 init
000501移动 appId 未初始化cmccAppId 未获取到
000520appId 必传init 未传入 appId
000600SDK 初始化异常初始化过程发生异常
000601SDK 响应处理异常处理服务端响应时发生异常
000602Token 签名计算异常签名计算过程发生异常
000603Token UUID 生成异常UUID 生成失败
000604Token 处理异常Token 处理过程发生异常
000605Token 插件调用异常调用取号插件时发生异常
000606网络类型处理异常网络类型处理时发生异常
000607网络类型调用异常网络类型调用时发生异常
000001获取网络类型失败获取网络类型失败

7.2 运营商返回码

移动取号:

返回码描述
103000成功
500网络异常,请检查网络设置
503参数缺失
130010参数为空
105002移动网关取号失败
105112时间戳非法
105113APPID 非法或为空
103101错误的请求签名
110023应用没有权益
110025权益已失效
110029微信 appid 校验失败

电信取号:

返回码描述
103000成功
301参数错误
500网络异常
502电信/联通取号能力关闭
105003电信网关取号失败
110023应用没有权益
110025权益已失效

联通取号:

返回码描述
103000成功
500网络异常
502电信/联通取号能力关闭
105001联通网关取号失败
110023应用没有权益
110025权益已失效

获取 token:

返回码描述
501用户取消授权
502用户选择其他登录方式
103002没有填写必传参数
104000app 不存在
104001businessType 校验失败
104003应用没有权益
104004权益已失效
104007accessToken 不存在(token 有效期 2 分钟)
104008accessToken 校验失败
104011手机号不能为空
104012本机号码校验失败
24小时热线 400-9669-253