一键登录(NEOneLogin)

2023.01.30 16:16:29

    简介

    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://www.jsdelivr.com/package/npm/@yidun/quickpass-sdk-one-login-h5/dist/NEOneLogin.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 传入一个容器 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[] -
    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
    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

    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

    实例方法

    以下是初始化实例上可调用的方法:

    • 调起授权页

    核心方法,调用该方法后即调起授权页,用户进行手机号补全,示例:

    neOneLogin.getToken();
    
    • 关闭授权页

    调用该方法后可关闭授权页,会删除授权页 iframe,若重新调用 getToken 方法,会重新生成授权页 iframe,示例:

    neOneLogin.disposeAuthFrame();
    
    • 销毁流程

    销毁流程,建议在组件卸载时使用,示例:

    neOneLogin.dispose();
    

    事件回调

    在验证过程中会抛出⼀些回调事件,业务上可以监听这些事件,⾃⾏做⼀些处理。

    • 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()
    });
    
    • 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,即可正常访问。其次保证使用电脑连接插卡的手机热点,进行开发,走手机流量。如果你通过宽带流量进行开发,一定只会收到错误码。

    Online Chat Tel:95163223