一键登录(NEOneLogin)

2024.04.15 17:12:21

    简介

    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 会将用于验证的 tokenaccessToken 都回调给业务方。

    配置说明

    在初始化 SDK 时,可以传入以下配置:

    参数 描述 类型 默认值 是否必填
    businessId 从易盾申请的 businessId string -
    mode 授权页面弹出模式,float 模式下占满全屏,popup 模式下需要通过 popupContainer 传入一个容器。弹框 popup 模式如何使用及其效果,可见弹框模式 float | popup float
    popupContainer 只在 popup 模式下生效,用于承接授权页的容器,若不设置此项,默认为 float 模式 string | HTMLElement -
    elements 需要渲染在授权页的模块,可选项有 backlogosloganphoneswitchButtonpolicyloginButton,根据数组中模块的位置进行顺序渲染,详细使用方法见自定义模块渲染方式 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,当 modepopup 模式时,推荐设置为非 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 宽度大小,比如 22050%220px number | string 220
    height 高度大小,比如 110110px,如果你的图片高度是确定的,建议把这个配置加上,设置为你希望的图片高度大小,这样可以避免由于图片加载过程中出现的布局跳动问题 number | string -
    top 距离顶部位置,比如 220220px number | string 150
    align 垂直排列方式 left | center | right center

    SloganStyles

    参数 描述 类型 默认值 是否必填
    width 宽度大小,比如 22050%220px number | string 100%
    top 距离顶部位置,比如 5050px number | string 50
    align 垂直排列方式 left | center | right center
    color 字体颜色 string #333
    size 字体大小 number | string 14px

    PhoneStyles

    参数 描述 类型 默认值 是否必填
    top 距离顶部位置,比如 220220px number | string 150
    align 垂直排列方式 left | center | right center
    color 字体颜色 string #333
    size 字体大小 number | string 26px
    cursorColor 闪烁光标颜色 number | string #2a62ff
    subBottomColor phoneInputStylesub 模式时,底线的背景颜色 string #2a62ff
    subWidth phoneInputStylesub 模式时,输入框的宽度 number | string 28px
    subHeight phoneInputStylesub 模式时,输入框的高度 number | string 32px
    squareBackground phoneInputStylesquare 模式时,输入框的背景色 string rgba(192, 208, 238, 0.4)
    squareWidth phoneInputStylesquare 模式时,输入框的宽度 number | string 32px
    squareHeight phoneInputStylesquare 模式时,输入框的高度 number | string 32px
    squareRadius phoneInputStylesquare 模式时,输入框的圆角 number | string 8px

    SwitchButtonStyles

    参数 描述 类型 默认值 是否必填
    width 宽度大小,比如 22050%220px number | string 100%
    top 距离顶部位置,比如 3030px number | string 30
    align 垂直排列方式 left | center | right center
    color 字体颜色 string #2a62ff
    size 字体大小 number | string 14px

    PolicyDefine

    参数 描述 类型 默认值 是否必填
    url 条款页链接 string -
    content 条款展示的文本名称 string -

    PolicyStyles

    参数 描述 类型 默认值 是否必填
    width 宽度大小,比如 22050%220px number | string 100%
    top 距离顶部位置,比如 5050px number | string 50
    align 垂直排列方式 left | center | right center
    color 字体颜色 string #333
    size 字体大小 number | string 14px

    LoginButtonStyles

    参数 描述 类型 默认值 是否必填
    width 宽度大小,比如 220100%220px number | string 100%
    top 距离顶部位置,比如 5050px number | string 50
    align 垂直排列方式 left | center | right center
    color 字体颜色 string #fff
    size 字体大小 number | string 18px
    height 按钮高度大小,比如 4810%48px number | string 48
    background 按钮背景颜色 string linear-gradient(90deg,#5f83fe,#324dff)
    radius 按钮四周圆角大小 number | string 8px

    ToastStyles

    参数 描述 类型 默认值 是否必填
    width 宽度大小,比如 auto80%220px number | string auto
    top 提示弹框距离顶部第一个非静态定位父元素的距离,比如 284284px 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 模式,即授权页是全屏占满的,如果你希望是在当前页以弹框的形式展示授权页面,需要同时设置 modepopupContainer 配置项。

    弹框模式示例代码:

    <!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 属性,将会覆盖默认的间距,这个时候需要业务方自己做自适应工作。如果业务方使用的 modepopup 模式,因为我们无法得知容器的大小,所以无法做自适应,需要业务方自己设置各 UI 模块的 top 来缩减距离。

    Online Chat Tel:95163223 Free trial