H5 集成文档V3.X

1 产品概述

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

• 本文是创蓝闪验H5的接入文档，用于指导WEB应用开发人员接入，并详细描述接入流程和使用方法，默认读者已经具有一定的编程知识基础。

前置条件：

• H5版本仅支持单蜂窝数据网络取号，WiFi连接的情况下会失败。
• 目前安卓和鸿蒙端微信浏览器、谷歌浏览器、Edge浏览器有反馈取号失败的情况，建议使用系统自带浏览器，苹果端没有影响。

注意：三网运营商内部执行逻辑不同，必须分别使用三网运营商的卡进行测试，防止功能异常

2 接入准备

2.1 平台申请

• 开发者使用账号登录创蓝智能云平台 (www.chuanglan.com )，参考【账号创建】中H5相关信息说明，填写信息创建应用。（注意：登录页地址和域名必须按照说明填写，否则会报referer校验不通过的错误）
• 审核通过后，开发者可以在应用详情中获取到应用的appId和appKey。H5 SDK 初始化仅需 appId；appKey 用于业务服务端置换手机号。
• 在页面 <head> 中添加 <meta content="always" name="referrer">（避免 HTTPS 跨域时 referer 为空）

2.2 引入 SDK

创蓝闪验 H5 SDK 提供两种集成方式，请根据项目技术栈任选其一。

方式一：npm 安装（支持 ESM / CJS，推荐工程化项目使用）

复制成功⧉
npm install shanyan-h5-sdk

复制成功⧉
import clshanyansdk from 'shanyan-h5-sdk';

说明：

• npm 包内置全部依赖与样式（含 React 运行时），业务方无需额外安装任何依赖，Vue / 原生 / React 项目均可使用
• 打包器（Vite / Webpack / Rollup）自动选择最优格式（ESM 或 CJS）
• TypeScript 项目自带类型声明，无需额外安装 @types/*
• npm 方式与 script 标签方式的 API 完全一致
• <meta name="referrer" content="always"> 仍需保留在页面中

后续文档中的 window.clshanyansdk.xxx(...) 调用，在 npm 方式下替换为 clshanyansdk.xxx(...) 即可。

方式二：script 标签（传统接入）

复制成功⧉
<!-- 闪验 H5 SDK（内部已自动加载移动/联通/电信运营商 SDK，客户无需额外引入） -->
<script src="js/umd/living.min.js"></script>
<!-- 依赖库（业务方自行引入） -->
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.1.1/crypto-js.min.js"></script>

引入后全局对象为 window.clshanyansdk，API 与 npm 方式完全一致。

两种方式对比

---

3 SDK 快速接入

3.1 初始化

建议在 H5 页面加载完成时调用，或在拉起授权页前提前调用（建议提前 1秒以上）。

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

回调参数：

调用说明：

• 初始化成功后 5 分钟内重复调用 init 会直接回调成功（内存参数复用）；超过时效会自动重新向服务端获取参数
• 初始化进行中重复调用返回 000500「初始化进行中，请勿重复调用」
• 初始化失败后 SDK 内部会自动重试一次，仍失败才对外返回失败

3.2 打开授权页

在需要启动一键登录的页面调用此方法，会展示授权页，用户授权后将返回认证 token。

• 拉起授权页前请确保已调用 init 初始化（未初始化时调用返回 000501）
• 一次调用保证只回调一次；不要连续调用或在授权页已展示时调用
• 一键登录成功率受网络环境、SIM卡状态等影响，不能作为唯一登录方式，建议在失败回调处做降级逻辑

复制成功⧉
window.clshanyansdk.openLoginAuth({
  // 可选：授权页 UI 配置
  option: { ... },
  // 可选：授权页加载成功回调（适合关闭 loading）
  authLoadSuccess: (res) => {
    console.log('授权页加载成功, msgId:', res.msgId);
  },
  // 可选：点击登录按钮/协议勾选框监听
  clickListenerCallback: (res) => {
    if (res.code === '1') console.log('用户点击登录按钮');
    else if (res.code === '2') console.log('用户点击协议勾选框, checked:', res.checked);
  }
}, (res) => {
  if (res.code === '200000') {
    console.log('取号成功, token:', res.token);
    console.log('msgId:', res.msgId);
    // 将 token 发送到业务服务端校验换取手机号
  } else if (res.code === '1011') {
    console.log('用户取消授权');
  } else {
    console.log('取号失败:', res.message);
  }
});

回调参数：

cfg 可选入参：

3.3 置换手机号

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

3.4 完整调用流程示例

复制成功⧉
// 1. 初始化
window.clshanyansdk.init({ appId: 'your_app_id' }, (initRes) => {
  if (initRes.code !== '200000') {
    alert('初始化失败: ' + initRes.message);
    return;
  }

  // 2. 打开授权页
  window.clshanyansdk.openLoginAuth({
    option: {
      setPageType: false,
      contracts: [
        { name: '《用户服务协议》', url: 'https://example.com/service.html' },
        { name: '《隐私政策》', url: 'https://example.com/privacy.html' },
      ],
    },
    authLoadSuccess: () => { hideLoading(); },
  }, (authRes) => {
    if (authRes.code === '200000') {
      // 3. 将 token 发送到业务服务端
      fetch('https://your-server.com/api/verify-token', {
        method: 'POST',
        body: JSON.stringify({ token: authRes.token }),
      }).then(res => res.json()).then(data => {
        console.log('手机号:', data.mobile);
      });
    } else if (authRes.code === '1011') {
      alert('已取消授权');
    } else {
      alert('取号失败: ' + authRes.message);
    }
  });
});

---

4 SDK 其他 API 说明

4.1 获取网络类型

复制成功⧉
window.clshanyansdk.getNetworkType((res) => {
  console.log('网络类型:', res.netType); // 'cellular' / 'wifi' / 'unknown'
});

此方法为可选，iOS 系统下 netType 基本返回 unknown，结果仅供参考。也可通过浏览器原生 navigator.connection 自行判断。

4.2 设置运行环境

复制成功⧉
window.clshanyansdk.setEnvironment('stable'); // 'stable' 测试环境 / 'release' 生产环境（默认）

• 须在 init 之前调用；默认使用生产环境 release
• 环境切换后内存中已获取的初始化参数自动失效，下次 init 会重新请求

4.3 设置日志开关

复制成功⧉
window.clshanyansdk.setLog(true);  // 开启 SDK 内部日志（默认关闭）

开启后 vConsole/控制台可看到 【ShanYan-SDK:模块】 开头的完整链路日志。

4.4 设置日志上报开关

复制成功⧉
window.clshanyansdk.setReport(false); // 关闭运行日志上报（默认开启）

SDK 运行结果日志默认上报至创蓝服务端（仅含结果码与描述信息）用于问题排查，如业务方不需要可调用此方法关闭。

4.5 设置 UI 配置（全局默认）

复制成功⧉
window.clshanyansdk.setUIConfig({
  setPageType: true,
  contracts: [...],
  // 其他样式配置...
}, (res) => {
  // res.code === '000700' 配置成功
  // res.code === '000500' 协议名称超长（仅校验旧格式 setPrivacyOne/setPrivacyTwo，>20字）
});

openLoginAuth 传入 cfg.option 时将整体替换当前生效的 UI 配置（包括 setUIConfig 设置的全局默认配置）；未传入 option 时沿用 setUIConfig 设置的全局默认配置。

4.6 销毁授权页

复制成功⧉
window.clshanyansdk.destroy(); // 主动销毁授权页

---

5 授权页自定义配置

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

授权页采用流式自动布局（内容自动居中排版，模块间距自动计算），不支持绝对定位类字段（top/left 等）。下表仅列出当前实际生效的字段。

5.1 配置项示例

复制成功⧉
window.clshanyansdk.openLoginAuth({
  option: {
    setPageType: true,

    logoStyle: {
      src: 'https://example.com/logo.png',
      height: '200rpx',
    },

    loginBtnStyle: {
      text: '一键登录',
      bgColor: '#2b7de0',
      fontColor: '#FFFFFF',
    },

    contracts: [
      { name: '《用户服务协议》', url: 'https://example.com/service.html' },
      { name: '《隐私政策》', url: 'https://example.com/privacy.html' },
      { name: '《数据安全说明》', url: 'https://example.com/data.html' },
    ],

    msgType: '1',
    msgPanelStyle: {
      width: '100%',
      height: '364rpx',
      bgColor: '#FFFFFF',
      radius: '40rpx',
    },
  }
}, (res) => { /* 授权结果回调 */ });

5.2 配置项详细说明

说明：

• 返回/关闭按钮（cancelBtnStyle）与协议勾选框（checkBtnStyle）当前为内置固定样式：全屏模式左上角 ‹ 返回按钮，弹窗模式右上角 ✕ 关闭按钮，相关配置暂不生效
• 字号、宽高类数值支持 rpx（按 750 设计稿自动换算为 vw）、vw、px、百分比

5.3 自定义控件说明

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

定位方式：

• 配置了 top / left / right 任一项 → 绝对定位于授权页内
• 均未配置 → 随文档流排列在登录按钮（或协议区）下方，marginTop 控制与上方元素的间距

点击行为：

• 点击控件统一回调 code='502'（配置了 id 时随回调携带），SDK 随即销毁授权页，业务方在回调中自行处理后续逻辑
• 配置了 url 的跳转类控件：SDK 先以新窗口打开链接，再派发 502 回调
• 控件的业务含义（如「其他登录方式」）由业务方根据 id 自行解释

---

6 默认样式与交互说明

SDK 内置两套默认样式，业务方不传配置时自动使用：

默认交互行为：

• 默认不显示登录按钮（loginBtnStyle.text 为空）：补齐 4 位号码且勾选协议后自动提交；配置 loginBtnStyle.text 后显示按钮，改为点击按钮提交
• 未勾选协议时提交（默认 msgType: '1'）：底部弹出二次协议确认弹窗，点「同意并继续」自动勾选并提交
• 授权页展示期间自动锁定宿主页面滚动，销毁后自动恢复，防止触摸滚动穿透

数字键盘（补号）交互：

• 全屏模式键盘贴屏幕底部常驻，弹窗模式悬浮于屏幕底部，均不随内容滚动
• 补齐 4 位号码后键盘自动收起；点击号码栏可重新弹出键盘（支持退格修改），再次补齐后自动收起
• 二次协议弹窗 / 协议全文查看期间键盘自动隐藏

小屏适配与滚动：

• 内容超出键盘上方可视区域时，授权页内容区自动支持上下滑动（触摸控件或空白处均可）
• 横屏矮屏（高度 ≤500px）自动切换紧凑布局，保证主要控件可见

---

7 返回码说明

7.1 SDK 返回码

7.2 运营商返回码

三网取号全部失败时，SDK 统一回调 000002，message 中包含三网原始返回 JSON：YDData（移动）/ CUData（联通）/ CTData（电信），可据此定位具体运营商的失败原因。

移动取号：

联通取号：

电信取号：

---