@yidun/quickpass-sdk-one-login-h5
v3.1.1
Published
一键登录 H5
Downloads
45
Readme
一键登录（NEOneLogin）
简介
NEOneLogin 为支持 H5 一键登录的 JS SDK，整合三大运营商（移动、联调、电信），一步校验手机号与当前 SIM 卡号是否一致，优化注册、登录、支付等场景验证流程。
快速上手
按照以下步骤快速调用示例。
资源引入
目前支持两种接入 SDK 方式。强烈推荐使用第一种 模块引入 的方式接入，以获取良好的类型提示。
1. 模块引入
下载 npm 包：
# npm
npm install @yidun/quickpass-sdk-one-login-h5
# yarn
yarn add @yidun/quickpass-sdk-one-login-h5
# pnpm
pnpm add @yidun/quickpass-sdk-one-login-h5在代码中引用：
import NEOneLogin from '@yidun/quickpass-sdk-one-login-h5';2. script 引入
body 标签下引入 SDK：
<script src="https://yidunfe.nosdn.127.net/sdk/NEOneLogin.v3.1.0.umd.js"></script>引入该脚本之后，不需要像模块引入方式一样通过 import 引入 NEOneLogin 变量，初始化时直接按下列方式即可：
const neOneLogin = new window.NEOneLogin({
// ...
});3. 添加 head referrer
生产上有 https 访问的，https 请求跨域，会导致上报的 referer 为空，运营商会去校验请求 referer 是否进行备案，请在 html 文件下的 head 标签添加如下代码解决此问题：
<meta content="always" name="referrer" />调用 SDK
1. 初始化 SDK
import NEOneLogin from '@yidun/quickpass-sdk-one-login-h5';
const neOneLogin = new NEOneLogin({
businessId: '从易盾申请的 businessId',
logo: 'https://xxxxxx.com/logo.png',
phoneInputStyle: 'square',
});2. 调起授权页
neOneLogin.getToken();调用该方法后，会调起授权页，需用户输入中间四位手机号。
3. 开始验证
neOneLogin.on('success', (data) => {
console.log('success', data);
ajax({
url: 'https://xxxxx.com/login',
data: {
token: data.token,
accessToken: data.accessToken,
},
});
});用户在授权页输入完手机号码，点击登录后，会向运营商发送校验请求，获得 accessToken，通过 success 事件，SDK 会将用于验证的 token 和 accessToken 都回调给业务方。
配置说明
在初始化 SDK 时，可以传入以下配置：
| 参数 | 描述 | 类型 | 默认值 | 是否必填 |
| --- | --- | --- | --- | --- |
| businessId | 从易盾申请的 businessId | string | - | 是 |
| mode | 授权页面弹出模式，float 模式下占满全屏，popup 模式下需要通过 popupContainer 传入一个容器。弹框 popup 模式如何使用及其效果，可见弹框模式 | float | popup | float | 否 |
| popupContainer | 只在 popup 模式下生效，用于承接授权页的容器，若不设置此项，默认为 float 模式 | string | HTMLElement | - | 否 |
| elements | 需要渲染在授权页的模块，可选项有 back ， logo ， slogan ， phone ， switchButton ， policy ， loginButton，根据数组中模块的位置进行顺序渲染，详细使用方法见自定义模块渲染方式 | string[] | ['back', 'logo', 'slogan', 'phone', 'policy', 'loginButton'] | 否 |
| backText | 授权页返回按钮文本 | string | 返回 | 否 |
| logo | logo 的 url 地址，可传 base64 | string | - | 否 |
| logoStyles | logo 的样式 | LogoStyles | - | 否 |
| sloganAppName | 标语要显示的 app 名称 | string | 网易易盾 | 否 |
| sloganStyles | 标语样式 | SloganStyles | - | 否 |
| phoneStyles | 手机号模块样式 | PhoneStyles | - | 否 |
| phoneInputStyle | 手机号输入框类型 | sub | square | sub | 否 |
| switchBtnText | 切换按钮文本 | string | 其它登录方式 | 否 |
| switchBtnStyles | 切换按钮样式 | SwitchButtonStyles | - | 否 |
| policy | 隐私条款 | PolicyDefine[] | - | 否 |
| policyTarget | 指定在何处显示隐私条款链接的 URL，当 mode 为 popup 模式时，推荐设置为非 self 的任意值。 | self | blank | parent | top | - | 否 |
| policyStyles | 隐私条款模块样式 | PolicyStyles | - | 否 |
| loginBtnText | 登录按钮文本 | string | 一键登录 | 否 |
| loginBtnStyles | 登录按钮样式 | LoginButtonStyles | - | 否 |
| iframeStyles | 授权页 iframe 的样式，你可以传入任何 css 样式，key 支持短横线连接或小驼峰形式 | CSSStyleDeclaration | 不同的 mode 有不同的默认样式，皆可以覆盖 | 否 |
| toastDelay | 提示弹框的存在时间，单位为 ms（毫秒） | number | 3000 | 否 |
| toastShow | 是否显示提示框，如果设置为 false，开发可监听 tip 事件使用自己的提示组件 | boolean | true | 否 |
| toastStyles | 提示弹框模块样式 | ToastStyles | － | 否 |
LogoStyles
| 参数 | 描述 | 类型 | 默认值 | 是否必填 |
| --- | --- | --- | --- | --- |
| width | 宽度大小，比如 220、50% 和 220px | number | string | 220 | 否 |
| height | 高度大小，比如 110 和 110px，如果你的图片高度是确定的，建议把这个配置加上，设置为你希望的图片高度大小，这样可以避免由于图片加载过程中出现的布局跳动问题 | number | string | - | 否 |
| top | 距离顶部位置，比如 220 和 220px | number | string | 150 | 否 |
| align | 垂直排列方式 | left | center | right | center | 否 |
SloganStyles
| 参数 | 描述 | 类型 | 默认值 | 是否必填 |
| ----- | -------------------------------------- | ----------------------------- | -------- | -------- |
| width | 宽度大小，比如 220、50% 和 220px | number | string | 100% | 否 |
| top | 距离顶部位置，比如 50 和 50px | number | string | 50 | 否 |
| align | 垂直排列方式 | left | center | right | center | 否 |
| color | 字体颜色 | string | #333 | 否 |
| size | 字体大小 | number | string | 14px | 否 |
PhoneStyles
| 参数 | 描述 | 类型 | 默认值 | 是否必填 |
| --- | --- | --- | --- | --- |
| top | 距离顶部位置，比如 220 和 220px | number | string | 150 | 否 |
| align | 垂直排列方式 | left | center | right | center | 否 |
| color | 字体颜色 | string | #333 | 否 |
| size | 字体大小 | number | string | 26px | 否 |
| cursorColor | 闪烁光标颜色 | number | string | #2a62ff | 否 |
| subBottomColor | phoneInputStyle 为 sub 模式时，底线的背景颜色 | string | #2a62ff | 否 |
| subWidth | phoneInputStyle 为 sub 模式时，输入框的宽度 | number | string | 28px | 否 |
| subHeight | phoneInputStyle 为 sub 模式时，输入框的高度 | number | string | 32px | 否 |
| squareBackground | phoneInputStyle 为 square 模式时，输入框的背景色 | string | rgba(192, 208, 238, 0.4) | 否 |
| squareWidth | phoneInputStyle 为 square 模式时，输入框的宽度 | number | string | 32px | 否 |
| squareHeight | phoneInputStyle 为 square 模式时，输入框的高度 | number | string | 32px | 否 |
| squareRadius | phoneInputStyle 为 square 模式时，输入框的圆角 | number | string | 8px | 否 |
SwitchButtonStyles
| 参数 | 描述 | 类型 | 默认值 | 是否必填 |
| ----- | -------------------------------------- | ----------------------------- | --------- | -------- |
| width | 宽度大小，比如 220、50% 和 220px | number | string | 100% | 否 |
| top | 距离顶部位置，比如 30 和 30px | number | string | 30 | 否 |
| align | 垂直排列方式 | left | center | right | center | 否 |
| color | 字体颜色 | string | #2a62ff | 否 |
| size | 字体大小 | number | string | 14px | 否 |
PolicyDefine
| 参数 | 描述 | 类型 | 默认值 | 是否必填 | | ------- | ------------------ | ------ | ------ | -------- | | url | 条款页链接 | string | - | 是 | | content | 条款展示的文本名称 | string | - | 是 |
PolicyStyles
| 参数 | 描述 | 类型 | 默认值 | 是否必填 |
| ----- | -------------------------------------- | ----------------------------- | -------- | -------- |
| width | 宽度大小，比如 220、50% 和 220px | number | string | 100% | 否 |
| top | 距离顶部位置，比如 50 和 50px | number | string | 50 | 否 |
| align | 垂直排列方式 | left | center | right | center | 否 |
| color | 字体颜色 | string | #333 | 否 |
| size | 字体大小 | number | string | 14px | 否 |
LoginButtonStyles
| 参数 | 描述 | 类型 | 默认值 | 是否必填 |
| --- | --- | --- | --- | --- |
| width | 宽度大小，比如 220、100% 和 220px | number | string | 100% | 否 |
| top | 距离顶部位置，比如 50 和 50px | number | string | 50 | 否 |
| align | 垂直排列方式 | left | center | right | center | 否 |
| color | 字体颜色 | string | #fff | 否 |
| size | 字体大小 | number | string | 18px | 否 |
| height | 按钮高度大小，比如 48、10% 和 48px | number | string | 48 | 否 |
| background | 按钮背景颜色 | string | linear-gradient(90deg,#5f83fe,#324dff) | 否 |
| radius | 按钮四周圆角大小 | number | string | 8px | 否 |
ToastStyles
| 参数 | 描述 | 类型 | 默认值 | 是否必填 |
| ----- | ------------------------------------------------------------------- | ----------------------------- | -------- | -------- |
| width | 宽度大小，比如 auto、80% 和 220px | number | string | auto | 否 |
| top | 提示弹框距离顶部第一个非静态定位父元素的距离，比如 284 和 284px | number | string | 284 | 否 |
| align | 垂直排列方式 | left | center | right | center | 否 |
自定义模块渲染方式
在一键登录授权页，你看到的所有 UI 都是由一个个模块组成的，每个模块由一个字符串表示，比如 back 代表的是顶部的返回按钮，logo 代表的是你看到的 logo。
elements 配置项可以让你自定义这些模块的渲染顺序，以及决定它们渲不渲染，下图将为你直观演示该配置项的作用：
手动配置代码演示：
const neOneLogin = new NEOneLogin({
businessId: '易盾申请的 businessId',
elements: ['back', 'logo', 'slogan', 'phone', 'loginButton', 'switchButton', 'policy'],
});弹框模式
关于配置项 mode 默认是 float 模式，即授权页是全屏占满的，如果你希望是在当前页以弹框的形式展示授权页面，需要同时设置 mode 和 popupContainer 配置项。
弹框模式示例代码：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, viewport-fit=cover" />
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<meta content="always" name="referrer" />
<title>一键登录H5 - demo</title>
<style>
#get-token-btn {
position: fixed;
left: 10px;
top: 10px;
}
#popup-container {
position: fixed;
left: 50%;
top: 50%;
width: 90%;
height: 400px;
transform: translate(-50%, -50%);
border-radius: 20px;
box-shadow: rgb(0 0 0 / 10%) 0px 4px 12px;
}
.title {
text-align: center;
margin-top: 30px;
}
.sub-title {
display: inline-block;
text-align: center;
width: 100%;
}
</style>
<script src="libs/[email protected]"></script>
</head>
<body>
<div id="root">
<button id="get-token-btn">调起授权页</button>
<div id="popup-container">
<h2 class="title">免费领试听课</h2>
<span class="sub-title">提交后会有老师联系您</span>
</div>
</div>
<script>
(function () {
const popupContainer = document.querySelector('#popup-container');
const neOneLogin = new NEOneLogin({
businessId: '从易盾申请的 businessId',
mode: 'popup',
popupContainer,
phoneInputStyle: 'square',
// 只渲染 4 个模块，其它的自定义
elements: ['phone', 'switchButton', 'loginButton', 'policy'],
logoStyles: {
top: 10,
},
sloganAppName: '网易易盾',
sloganStyles: {
top: 10,
},
phoneStyles: {
top: 20,
},
switchBtnText: '切换手机号',
loginBtnText: '授权登录',
loginBtnStyles: {
top: 20,
},
policy: [
{
content: '自定义条款1',
url: 'https://www.baidu.com',
},
{
content: '自定义条款',
url: 'https://www.baidu.com',
},
],
policyStyles: {
top: 20,
},
iframeStyles: {
position: 'absolute',
left: '0',
bottom: '0',
height: '274px',
},
});
document.querySelector('#get-token-btn').onclick = () => {
neOneLogin.getToken();
};
})();
</script>
</body>
</html>从上面可以看到，我们调整了各个模块的 top 以覆盖 SDK 的默认距离，并将授权页放到了我们自定义的容器中。下图是实际效果：
实例方法
以下是初始化实例上可调用的方法：
- 调起授权页
核心方法，调用该方法后即调起授权页，用户进行手机号补全，示例：
neOneLogin.getToken();- 关闭授权页
调用该方法后可关闭授权页，会删除授权页 iframe，若重新调用 getToken 方法，会重新生成授权页 iframe，示例：
neOneLogin.disposeAuthFrame();- 销毁流程
销毁流程，建议在组件卸载时使用，示例：
neOneLogin.dispose();- 启用登录按钮
将登录按钮状态设置为可用，示例：
neOneLogin.enableLoginButton();用户点击登录后，登录按钮就会一直保持禁用状态，可手动调用上面方法将其启用。不过大多数情况下，接入方无需使用该方法，建议失败时走降级或者销毁实例重新验证，因为运营商会对同一个 token 做次数校验。
- 禁用登录按钮
将登录按钮状态设置为禁用，示例：
neOneLogin.disableLoginButton();事件回调
在验证过程中会抛出⼀些回调事件，业务上可以监听这些事件，⾃⾏做⼀些处理。
- success 事件
neOneLogin.on('success', (data) => {
console.log('success', data);
// 成功拿到 token 和 accessToken 后像服务端发起校验
ajax({
url: 'https://xxxxx.com/login',
data: {
token: data.token,
accessToken: data.accessToken,
},
});
});- error 事件
neOneLogin.on('error', (err) => {
// err.data 中可以拿到错误信息
console.log('error', err.data);
neOneLogin.dispose();
neOneLogin = null;
// 失败后可以走业务方自己的降级流程
// handleOneLoginFailProcess()
});- ready 事件
neOneLogin.on('ready', () => {
// 当预取号->授权页面成功挂载时触发
});- close 事件
neOneLogin.on('close', () => {
// 当授权页通过返回按钮关闭时触发
});- switch 事件
neOneLogin.on('switch', () => {
// 当授权页点击切换按钮时触发
// 与 close 事件不同的是，close 事件触发时意味着授权页已经被关闭
// 但 switch 事件不会关闭授权页，如果需要关闭，需要开发调用 disposeAuthFrame 方法
});- tip 事件
neOneLogin.on('tip', ({ code, text }) => {
// 根据 code 或者 text 在⻚面中给出提示文案
});当前包含以下 code 和 text:
| code | text | 说明 | | -------------- | ---------------------------------- | ---------------------------- | | complete_phone | 请补全手机号后登录 | 授权页手机号未补全 | | agree_terms | 请勾选同意运营商认证服务条款后登录 | 未勾选同意运营商认证服务条款 |
错误对照表
| code | msg | 说明 | | ----- | ---------------------------------- | --------------------------------------------- | | -8001 | 网络请求错误 | 网络错误，请检查网络 | | 10000 | 预取号失败 | 预取号失败 | | 20001 | 移动取号失败 | 移动取号失败 | | 20002 | 移动获取 accessToken 失败 | 移动获取 accessToken 失败 | | 20010 | 移动报备 referer 校验失败 | 访问域名的 referer 与移动报备的地址不一致 | | 30001 | 联通获取省份 URL 失败 | 联通获取省份 URL 失败 | | 30002 | 联通获取省份失败 | 联通获取省份 URL 后，在获取省份时接口请求失败 | | 30003 | 联通获取 accessToken 失败 | 联通获取 accessToken 失败 | | 30010 | 联通报备 referer 校验失败 | 访问域名的 referer 与联通报备的地址不一致 | | 40001 | 电信预授权失败 | 电信预授权失败 | | 40002 | 电信获取 accessCode 失败 | 电信获取 accessCode 失败 | | 40010 | 电信报备 referer 校验失败 | 访问域名的 referer 与电信报备的地址不一致 | | 40000 | 未知运营商，仅支持电信、联通、移动 | 仅支持主流运营商 |
常见问题
1. 发生错误时该如何排查问题？
首先看返回的错误码，可从错误信息 err.data 中获取，然后与上述的【错误对照表】对比查看，需要强调的是，如果错误码为 40000，请检查设备网络是否关闭了 wifi。
2. 错误码在上述【错误对照表】中没有怎么办？
因为 SDK 内部在调用各个运营商服务时，他们有自己的错误提示信息，我们的策略是优先显示他们的错误信息，所以当出现这种情况时，开发者可根据错误信息中的 err.data.msg 大致排查下，如果还是不知道如何解决，请联系我们的技术支持。
3. 我用电脑如何进行开发？
首先要保证开发时本地服务的访问地址不能是 localhost 或者 ip，需要配置一个已报备过的完整的地址，例如 http://ye-dev.dun.163.com，这个时候推荐使用 SwitchHost 软件配置：127.0.0.1 ye-dev.dun.163.com，即可正常访问。其次保证使用电脑连接插卡的手机热点，进行开发，走手机流量。如果你通过宽带流量进行开发，一定只会收到错误码。
4. 小屏幕会自适应吗？
SDK 内部做了根据屏幕高度自适应，在屏幕高度 0 - 500px 以下和 500px - 600px 区间，各个 UI 模块的间距会减小，以保证在用户屏幕内能够显示所有模块。如果你自定义了模块的 top 属性，将会覆盖默认的间距，这个时候需要业务方自己做自适应工作。如果业务方使用的 mode 为 popup 模式，因为我们无法得知容器的大小，所以无法做自适应，需要业务方自己设置各 UI 模块的 top 来缩减距离。