H5和小程序怎么实现一键登录？前端接入实战

devyidun

3人浏览 · 2026-06-30 18:17:31

devyidun · 2026-06-30 18:17:31 发布

在移动端App中，一键登录依赖原生SDK实现。但在H5页面和微信小程序这类Web技术栈场景中，需要走一条不同的技术路径。易盾号码认证提供了H5 JS SDK（NEOneLogin），并通过微信web-view组件实现对小程序场景的覆盖。

本文聚焦H5和小程序两个场景的一键登录接入方案，涵盖从依赖引入到上线的全流程。

H5一键登录接入

H5端的一键登录通过 NEOneLogin JS SDK 实现，本质是在页面中内嵌一个由运营商提供的iframe授权页。用户在该iframe中补全手机号中间四位并确认授权，SDK将token回调给业务方。

两种引入方式

方式一：npm模块引入（推荐，有TypeScript类型提示）

npm install @yidun/quickpass-sdk-one-login-h5

import NEOneLogin from '@yidun/quickpass-sdk-one-login-h5';

const neOneLogin = new NEOneLogin({
  businessId: '从易盾申请的 businessId',
  logo: 'https://your-domain.com/logo.png',
  phoneInputStyle: 'square',
});

方式二：script标签引入

<script src="https://yidunfe.nosdn.127.net/sdk/NEOneLogin.v3.1.2.umd.js"></script>
<script>
const neOneLogin = new window.NEOneLogin({
  businessId: '从易盾申请的 businessId',
});
</script>

script方式引入后，构造函数挂载在 window.NEOneLogin 上。

全屏模式 vs 弹框模式

H5 SDK支持两种展示模式：

全屏模式（float，默认）：授权页占满整个屏幕，由iframe全屏覆盖。适合独立的一键登录页面场景。

const neOneLogin = new NEOneLogin({
  businessId: 'xxx',
  mode: 'float',
  elements: ['back', 'logo', 'slogan', 'phone', 'loginButton', 'switchButton', 'policy'],
});

// 点击按钮调起授权页
document.querySelector('#login-btn').onclick = () => {
  neOneLogin.getToken();
};

弹框模式（popup）：授权页嵌入页面中的指定容器，适合在已有页面中以弹框形式展示。

const neOneLogin = new NEOneLogin({
  businessId: 'xxx',
  mode: 'popup',
  popupContainer: document.querySelector('#popup-container'),
  elements: ['phone', 'switchButton', 'loginButton', 'policy'],
  iframeStyles: {
    position: 'absolute',
    left: '0',
    bottom: '0',
    height: '274px',
  },
});

弹框模式的核心配置：

popupContainer：承载授权页的DOM元素，需预先设置好容器的位置、宽高和样式
iframeStyles：控制授权页iframe在容器内的定位，通常设为绝对定位并固定在容器底部
elements：可以只渲染必要的模块（如不展示Logo和slogan），由业务方自己的UI承担视觉引导

弹框模式的典型场景：在注册表单页中嵌入一键登录，页面顶部由业务方自己展示标题和引导文案，授权页只提供手机号输入和登录按钮。

事件回调处理

SDK通过事件监听机制回调各种状态，业务方按需处理：

// 成功——拿到token和accessToken，传给后端校验
neOneLogin.on('success', (data) => {
  fetch('/api/login', {
    method: 'POST',
    body: JSON.stringify({
      token: data.token,
      accessToken: data.accessToken,
    }),
  });
});

// 失败——走降级方案（短信验证码等）
neOneLogin.on('error', (err) => {
  console.log('一键登录失败', err.data);
  neOneLogin.dispose();  // 销毁实例
  // 切换到短信验证码登录
});

// 授权页就绪——预取号成功，授权页已挂载
neOneLogin.on('ready', () => {
  console.log('授权页已就绪');
});

// 返回按钮关闭
neOneLogin.on('close', () => {
  // 用户点击返回，可以做数据上报
});

// 切换登录方式
neOneLogin.on('switch', () => {
  // 用户点击"其它登录方式"
  neOneLogin.disposeAuthFrame(); // 关闭授权页
  // 切换到其他登录方式
});

// 提示事件
neOneLogin.on('tip', ({ code, text }) => {
  // code: complete_phone → 手机号未补全
  // code: agree_terms → 未勾选协议
});

关键配置：referer

这是H5端最容易踩的坑。生产环境HTTPS下，如果不在head标签中配置referer策略，运营商会对空的referer做校验失败。

<head>
  <meta content="always" name="referrer" />
</head>

不加这一行，运营商会返回referer校验失败错误（移动20010、联通30010、电信40010）。

生命周期管理

SDK实例需要正确的生命周期管理：

// 关闭授权页（不销毁实例，可重新getToken）
neOneLogin.disposeAuthFrame();

// 完全销毁实例（组件卸载时调用）
neOneLogin.dispose();

// 手动控制登录按钮状态
neOneLogin.enableLoginButton();   // 启用
neOneLogin.disableLoginButton();  // 禁用

通常情况下不需要手动 enableLoginButton——因为运营商会对同一token做次数校验，失败后建议直接销毁实例重建，而非重新启用按钮。

微信小程序接入

微信小程序中无法直接运行H5 JS SDK，但可以通过 web-view 组件加载一个部署好的H5一键登录页面，实现间接接入。

技术原理

整体架构是：小程序web-view → H5一键登录页面 → 运营商授权页 → token回调 → 微信JSSDK通信 → 小程序页面。

接入步骤

第一步：创建web-view承载页面

在小程序 pages/ 下创建 one-login 页面：

<!-- one-login.wxml -->
<view class="container">
  <web-view src="https://your-domain.com/one-login-h5.html"></web-view>
</view>

第二步：部署H5一键登录页面

将接入NEOneLogin SDK的页面部署到HTTPS服务器。该页面需要额外处理与小程序的通信：

// 成功时跳转小程序验证页
neOneLogin.on('success', (data) => {
  window.wx.miniProgram.redirectTo({
    url: `/pages/verify/verify?from=h5&event=verify&token=${data.token}&accessToken=${data.accessToken}`
  });
});

// 失败时跳转小程序失败页
neOneLogin.on('error', (err) => {
  window.wx.miniProgram.redirectTo({
    url: `/pages/unpass/unpass?from=h5&event=${err.data.code}`
  });
});

第三步：创建验证页面接收token

在小程序创建 pages/verify/verify 页面，在 onLoad 生命周期中接收参数：

// verify.js
Page({
  onLoad(options) {
    const { from, event, token, accessToken } = options;
    if (from === 'h5' && event === 'verify') {
      // 拿到 token 和 accessToken，调用后端校验接口
      wx.request({
        url: 'https://your-api.com/api/verify',
        method: 'POST',
        data: { token, accessToken },
        success(res) {
          // 校验成功，完成登录
        }
      });
    }
  }
});

第四步：配置业务域名（上线必须）

在微信小程序管理后台 — 开发管理 — 开发设置 — 业务域名中，添加两个域名：

你的H5页面域名：如 https://your-domain.com（部署一键登录H5页面的域名）
易盾授权页域名：https://ye.dun.163yun.com（运营商授权页iframe的域名，必须添加）

配置后需下载校验文件，放置到你的H5页面域名根目录下，同时将该文件发给易盾技术支持——因为易盾的授权页域名根目录下也需要放置该文件。

第五步：本地开发时跳过校验

开发阶段可以勾选"不校验合法域名、web-view（业务域名）"快速调试，但上线前务必完成域名配置。

小程序接入的注意事项

手机预览时需打开"开发模式"重新进入小程序，否则无法预览web-view内容
两个业务域名都必须配置：自己的域名和易盾的 ye.dun.163yun.com
H5页面的通信使用了微信JSSDK的 wx.miniProgram.redirectTo，需确保H5页面已引入微信JSSDK
web-view中的页面必须HTTPS

H5端常见错误码

错误码	说明	排查方向
-8001	网络请求错误	检查网络连接
-8002	预取号超时	网络环境差，重试
10000	预取号失败	检查businessId和网络
20001	移动取号失败	移动网络相关
20010	移动referer校验失败	检查referer meta标签和报备
30001	联通获取省份URL失败	联通网络相关
30010	联通报备referer校验失败	同上
40001	电信预授权失败	电信网络相关
40010	电信报备referer校验失败	同上
40000	未知运营商	非三大运营商网络或WiFi关闭

常见问题（FAQ）

Q1：H5端为什么一直返回referer校验失败？

三个原因依次排查：①是否在 <head> 中添加了 <meta content="always" name="referrer"/>；②生产域名是否在运营商后台完成了referer报备；③请求是否确实走了HTTPS（HTTP下referer可能为空）。

Q2：小程序中web-view提示无法打开页面？

检查：①web-view的src是否HTTPS；②业务域名是否已完成配置（包括易盾的 ye.dun.163yun.com）；③校验文件是否已放置到域名根目录。开发阶段可临时勾选"不校验合法域名"。

Q3：弹框模式下授权页不显示？

确认popupContainer元素是否存在并可见，建议给容器设置明确的宽高。同时检查iframeStyles是否正确（弹框模式默认iframe定位为absolute，需配合父容器使用）。

Q4：点击登录按钮后按钮一直禁用状态？

这是正常行为——登录按钮在点击后自动禁用，防止重复提交。如果取号失败，可以调用 dispose() 销毁实例后重新初始化，或调用 enableLoginButton() 手动启用。

Q5：小程序和H5能不能共用一个businessId？

可以。businessId在易盾后台对应一个应用，只要签名/包名/referer配置正确即可。

Q6：H5需要配置包名和签名吗？

不需要。H5端不做包名和签名校验，取而代之的是域名referer校验——需要在运营商后台报备生产域名。

了解易盾号码认证一键登录的完整产品能力与接入方案，可访问易盾号码认证产品页。

网易智企-易盾开发者社区

网易易盾是国内领先的数字内容风控服务商，依托网易二十余年的先进技术和一线实践经验沉淀，为客户提供专业可靠的安全服务，涵盖内容安全、业务安全、应用安全、安全专家服务四大领域，全方位保障客户业务合规、稳健和安全运营。

更多推荐

本机校验怎么实现？静默手机号验证方案详解

一键登录解决了"获取本机号码"的问题，但并非所有场景都需要获取号码本身。很多业务场景只关心一件事：用户输入的手机号，是不是当前设备SIM卡的号码？这就是本机校验的定位。它不获取明文号码，只做一致性校验——用户输入手机号，SDK通过运营商网关比对当前流量卡号码是否与输入一致，返回"是"或"否"。本文详细拆解本机校验的技术方案、适用场景和

网易智企-易盾开发者社区

uniapp多端一键登录怎么统一实现？App/H5/小程序条件编译适配方案

uniapp最大的优势是一套代码编译到多个平台。但号码认证一键登录在不同端的实现方式截然不同：App端走原生插件、H5端走JS SDK、小程序端走web-view。如何在保持代码统一性的同时处理这些差异？答案就在uniapp的条件编译机制。本文通过封装一个统一的 quickLogin 工具模块，基于易盾号码认证SDK实现三端的一键登录能力——业务层只调用一个方法，底层自动适配不同平台。三端技术

网易智企-易盾开发者社区

uniapp App端怎么接入号码认证？原生插件封装方案

uniapp作为跨端开发框架，在App端使用原生渲染（基于Weex或纯原生），无法直接运行H5的JS SDK。要实现号码认证一键登录，需要将易盾的原生SDK封装为uniapp原生插件，通过 uni.requireNativePlugin 在JS层调用。本文聚焦uniapp App端（Android + iOS）的插件封装和接入流程。整体架构 uniapp JS层 (Vue页面) │ uni.r