简介

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. 引入脚本

在 body 标签中引入 SDK：

<script src="https://yidunfe.nosdn.127.net/sdk/NEOneLogin.v3.1.1.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/jquery@3.6.0.js"></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 来缩减距离。