文档

H5客户端接入

更新时间:

本文详细介绍H5页面接入网页端SDK的方式及一键登录相关方法的说明。

说明

在使用过程中如有疑问,可以提交工单联系阿里云技术工程师处理。

接入步骤

创建认证方案

您导入项目或调用API接口时,会用到方案Code等参数信息,请先在号码认证产品控制台创建认证方案,获取方案Code等参数信息。

资源引入

npm包引入

下载npm资源,并将aliyun_numberauthsdk_web包添加依赖到package.json

npm i aliyun_numberauthsdk_web -S

在脚本中引入:

import { PhoneNumberServer } from 'aliyun_numberauthsdk_web'; 

静态资源引入

登录号码认证产品控制台,在概览页面右侧API&SDK区域,单击立即下载,进入API&SDK页面,根据页面提示下载并解压对应SDK。

网页端SDK上传到您的静态资源服务器上,获取能够访问到网页端SDK的URL,通过script标签的方式引入。

<script type="text/javascript" charset="utf-8" src="${your-sdk-asset-path}/numberAuth-web-sdk.js"></script>
重要
  • 不可在业务代码中覆盖window.PhoneNumberServer变量。

  • 未开启移动数据网络的用户无法通过一键登录完成认证:认证之前确保您的终端设备已关闭Wi-Fi连接且开启了SIM卡的4G移动数据网络(支持中国联通、中国移动的3G网络,但接口耗时会增加)。

交互流程

image..png

  1. 初始化并鉴权

    1. 用户访问H5页面

    2. 服务端:调用GetAuthToken接口获取业务鉴权accessToken、API鉴权jwtToken

    3. 网页端:调用checkLoginAvailable方法发起身份鉴权。

    4. 鉴权成功后展示登录界面。

  2. 唤起授权页面

    1. 用户点击H5页面的“登录”按钮。

    2. 网页端:调用getLoginToken方法进行预取号。

    3. 获取到带有掩码的手机号后,唤起二次弹窗授权页,授权页会展示待补充完整的号码及运营商协议。

      重要
      • 网页端SDK或注册需用户确认授权方可使用,且登录按钮文字描述必须包含“登录”、注册按钮文字描述必须包含“注册”等文字,不可诱导用户授权以及通过任何技术手段跳过或模拟此步骤,否则我方有权停止服务并追究相关法律责任。

      • 阿里云将对接入移动认证SDK并上线的应用授权页面进行审查,若出现未按要求弹出或设计授权页面的,将停止应用的网页端SDK或注册服务。

  3. 用户同意授权并登录

    1. 用户输入手机号中间四位数字并同意相关协议。

    2. 单击授权页面的登录或注册按钮,SDK会根据用户输入的掩码返回一键登录spToken。

  4. 服务端取号

    1. 服务端:调用GetPhoneWithToken接口,换取用户完整手机号。

    2. 获取到用户完整手机号后,您可自行实现登录或注册业务逻辑,并将结果返回给H5页面

    3. H5页面获取到登录状态,关闭授权弹窗。

伪代码示例

var loginBtn = document.getElementById("loginBtn");
var phoneNumberServer = new PhoneNumberServer();

function getAuth() {
  // 向后端发起请求,获取accessToken, jwtToken, 后端调用 getAuthToken 接口
  return accessToken, jwtToken;
}

function checkLogin(accessToken, jwtToken) {
  phoneNumberServer.checkLoginAvailable({
    accessToken: accessToken,
    jwtToken: jwtToken,
    success: function (res) {
      // 身份鉴权成功,调用 getLoginToken 接口
      getToken();
    },

    // 身份鉴权失败,提示用户关闭Wi-Fi或者尝试其他登录方案
    error: function (res) {},
  });
}

function getToken() {
  phoneNumberServer.getLoginToken({
    success: function (res) {
      // 成功回调,获取spToken
      getPhone(res.spToken);
    },

    // 失败回调
    error: function (res) {},
    
    // 授权页状态监听函数
    watch: function (status, data) {},
    
    // 页面配置选项
    authPageOption: {},
  });
}

function getPhone(spToken) {
  // 向后端发起请求,后端调用 GetPhoneWithToken接口,获取用户手机号, 完成登录
}


loginBtn.onclick = function () {
  const {accessToken, jwtToken} = getAuth();
  checkLogin(accessToken, jwtToken);
};

H5接入Demo,请参见H5页面Demo体验

SDK方法说明

初始化实例

var phoneNumberServer = new PhoneNumberServer();

checkLoginAvailable(一键登录鉴权接口)

// 先在服务端调用getAuthToken接口, 获取accessToken, jwtToken
phoneNumberServer.checkLoginAvailable();

checkLoginAvailable 方法参数

phoneNumberServer.checkLoginAvailable({
  accessToken: "******",
  jwtToken: "******",
  success: function (res) {
    console.log(res);
    if (res.code === 600000) {
      console.log("鉴权成功", res);
      // 在此调用getLoginToken方法
    }
  },

  error: function (res) {
    console.log("鉴权失败", res);
    // 可提示用户关闭Wi-Fi或者尝试其他登录方案
  }
});

参数名称

参数类型

是否必填

参数说明

accessToken

string

业务鉴权Token,由服务端调用GetAuthToken接口获取。过期时间是10分钟,有效期内可以重复使用。

jwtToken

string

API鉴权Token,由服务端调用GetAuthToken接口获取。过期时间是1小时,有效期内可以重复使用。

timeout

number

接口请求超时时间,默认值为10s。

success

function

成功回调。入参请参见success/error 回调函数入参

error

function

失败回调。入参请参见success/error 回调函数入参

success/error 回调函数入参

参数示例

参数名称

参数说明

{
  code: "6000xx",
  content: [
    { 
      vender: "CU", 
      result: "100001", 
      resultCode: "101", 
      msgId: "xxxxx"
    }
  ],
  msg: "",
  requestId: ""
}

code

返回的状态码。

  • 返回600000代表请求成功。

  • 其他错误码,请参见错误码

content

运营商SDK的返回结果,方便客户定位问题。

说明

不同运营商返回的内容消息体存在一些差异,可根据vender字段进行区分处理。

msg

返回结果的描述。

requestId

请求ID,根据此ID可查询相关日志。

getLoginToken(获取一键登录Token接口)

// 在checkLoginAvailable方法的success回调中调用本方法
phoneNumberServer.getLoginToken();

getLoginToken 方法参数

phoneNumberServer.getLoginToken({
  authPageOption: {
    navText: "测试",
    subtitle: "", // 副标题
    isHideLogo: false, // logo显示隐藏
    logoImg: "XXX",
    btnText: "立即登录",
    agreeSymbol: "、",
    privacyOne: ["《中国移动认证服务条款》", ""],
    privacyTwo: ["《中国移动认证服务条款》", ""],
    showCustomView: true,
    customView: {
      element:
        '<div class="btn_box other" onclick="clickEvent()">切换其他登录方式</div>',
      style: ".btn_box.other{background: #fff; color: #f00}",
      js: "function clickEvent(){alert(666666)}",
    },
    privacyBefore: "我已阅读并同意",
    privacyEnd: "",
    vendorPrivacyPrefix: "《",
    vendorPrivacySuffix: "》",
    privacyVenderIndex: 2,
    isDialog: true, // 是否是弹窗样式
    manualClose: true, // 是否手动关闭弹窗/授权页
    isPrePageType: false,
    isShowProtocolDesc: false,
    // prePageTypeOption: {
    //     // mount: '',
    //     privacyOne: ['条款1', 'https://wap.cmpassport.com/resources/html/contract.html'],
    //     privacyTwo: ['条款2', 'https://wap.cmpassport.com/resources/html/contract.html'],
    //     // showCustomView: true,
    //     agreeSymbol: '及',
    //     tips: <div style={{ position: 'absolute', top: '10px', right: '10px', borderRadius: '30%', fontSize: '12px', color: '#fff'}}>tips</div>,
    //     btnText: '',
    // }
  },
  success: (res) => {
    console.log(res);
    if (res.code === 600000) {
      // 拿到spToken去服务端发起Token验证
      phoneNumberServer.closeLoginPage(); // 手动关闭授权页时调用关闭页面
      res.clearInput(); // 清空输入框并将光标置于第一个输入框
      res.focusOn(2); // 将光标置于第1-4个输入框

      res.setMessage({
        // 设置弹出Toast提示框(有默认样式)
        showMessage: true, // 是否弹出Toast提示框
        messageContent: "test content", // 弹出内容
        messageStyle: {
          // 自定义弹窗样式,写入css样式即可
          color: "#fff",
          borderRadius: "8px",
        },
        time: 3000, // 弹出时间/ms,默认3000毫秒
      });
    }
  },

  error: (res) => {
    // 提示用户关闭Wi-Fi或者尝试其他登录方案
  },

  watch: function (status, data) {
    // console.log('-----------------status', status, data);
    // 当status为2时整个流程结束,比如如果按钮有loading状态此处置为false
  },
});

参数名称

参数类型

是否必填

参数说明

authPageOption

object

配置选项。配置详情请参见authPageOption 字段说明

timeout

number

超时时间,单位:秒。建议不低于2秒,默认为3秒。

success

function

成功回调。入参请参见success/error 回调函数入参

error

function

失败回调。入参请参见success/error 回调函数入参

watch

function

授权页状态监听函数。入参请参见watch/protocolPageWatch 回调函数入参

protocolPageWatch

function

预授权页状态监听函数,isPrePageType参数为true时需填入。入参请参见watch/protocolPageWatch 回调函数入参

privacyAlertWatch

function

二次弹窗页面状态监听函数。

success/error 回调函数入参

参数名称

参数类型

参数说明

code

string

返回的状态码。

  • 返回600000代表请求成功。

  • 其他错误码,请参见错误码

spToken

string

运营商一键登录Token,可在服务端调用GetPhoneWithToken接口进行取号。

clearInput

function

调用清空当前所有输入框,将光标置于第一个输入框。

focusOn

function

入参为:1-4,将光标置于入参对应下标的输入框内。

setMessage

function

设置弹出Toast提示框(有默认样式)。入参格式:

{ 
  showMessage: boolean, // 是否弹出Toast提示框 
  messageContent: string, // 弹出内容 
  messageStyle: object, // 自定义弹窗样式 
  time: number // 弹出时间ms
}

vender

string

运营商信息:

  • CM 中国移动 

  • CU 中国联通

  • CT 中国电信

watch/protocolPageWatch 回调函数入参

参数名称

参数说明

status

授权页状态。

  • 1:渲染成功(watch,protocolPageWatch)

  • 2:主动点击返回/关闭按钮(watch)

  • 3:点击协议(watch,protocolPageWatch)

  • 5:点击登录按钮(watch,protocolPageWatch)

  • 6:获取掩码成功(仅protocolPageWatch回调返回此状态,获取此状态时,需确认当前使用的运营商网络,在预授权模式中,协议和登录按钮此时展示。)

  • 8:点击协议按钮(返回的data中会包含当前的协议勾选状态isChecked, 为true时为已勾选, false为未勾选)(watch, protocolPageWatch)

  • 9:输入手机号四位掩码的监听(watch)(返回的data中会返回当前的四位掩码maskPhone,maskPhone为数组,按顺序掩码数字。 )

data

监听返回的额外数据,包含以下:

  • requestId: string类型,本地调用的唯一ID,根据此ID可查询相关日志。

  • netType:string类型,运营商类型,CT(电信)、CU(联通)、CM(移动)。

  • maskPhone:array类型,手机号四位掩码(status为9和5时出现)。

  • isChecked:boolean类型,当前的协议勾选状态 (status为8和5时出现)。

authPageOption 字段说明

参数名称

参数类型

是否必填

参数说明

mount

string

指定挂载节点的ID,默认挂载到body标签。

navText

string

导航栏标题文案,默认值:本机号码登录。

navBackImg

string

导航栏返回按钮图片的src链接。

说明

仅在全屏模式下有返回按钮。

subtitle

string

副标题导航栏下面的说明文案,不传则不显示。

isHideLogo

boolean

是否隐藏Logo。取值:

  • false(默认值):表示显示。

  • true:表示隐藏。

logoImg

string

Logo图片设置,默认值:阿里云Logo。

numberLabel

string

手机号码前面的文案或图片,不传则不展示。

btnText

string

按钮文案,默认值:登录。

isFocus

boolean

进入授权页面,是否聚焦光标。取值:

  • true:聚焦光标。

  • false(默认值):不聚焦光标。

    说明

    由于系统限制,iOS系统浏览器不支持该功能。

agreeSymbol

string

协议和协议之间的连接符号,默认用“和”连接。

privacyVenderIndex

number

运营商协议的位置,默认为2。

  • 0:最前面。

  • 1:中间位置。

  • 2:最后面。

vendorPrivacyPrefix

string

设置运营商协议前缀符号,仅支持设置如下字符中的任意一个,如<>、()、《》、【】、『』、[]、()

vendorPrivacySuffix

string

设置运营商协议后缀符号,仅支持设置如下字符中的任意一个,如<>、()、《》、【】、『』、[]、()

privacyBefore

string

设置开发者隐私条款前置自定义文案。默认:我已阅读并同意。

privacyEnd

string

设置开发者隐私条款后置自定义文案。

privacyCheckedImg

string

默认为圆形勾选,如需自定义可传入需要的图片。

privacyOne

string

自定义协议1,格式:['name',url]。

privacyTwo

string

自定义协议2,格式:['name',url]。

showCustomView

boolean

是否展示自定义控件。取值:

  • true:表示展示自定义控件。

  • false(默认值):表示不展示自定义控件。

customView

object

添加此属性必须设置showCustomViewtrue,对象形式

{
  "element": "自定义节点",
  "style": "自定义样式",
  "js": "自定义交互"
}

isDialog

boolean

是否弹窗样式。取值:

  • true:表示登录页为弹窗。

  • false(默认值):表示登录页为全屏页面。

manualClose

boolean

是否手动关闭弹窗/授权页。取值:

  • true:表示登录时需要手动关闭授权页。

  • false(默认值):表示登录时自动关闭授权页。

isPrePageType

boolean

协议是否前置。取值:

  • true:协议展示在预授权页面,用户同意协议,点击确认按钮后,跳转至授权页。

  • false(默认值):协议不前置。

isShowProtocolDesc

boolean

预授权模式下,授权页弹窗是否展示协议。取值:

  • true:表示展示协议。

  • false(默认值):表示不展示协议。

prePageTypeOption

object

isPrePageType参数为true时,需传入mount。配置详情请参见配置对象详情请参见prePageTypeOption 预授权页面配置

privacyAlertIsNeedShow

boolean

设置二次隐私协议弹窗是否显示,点击协议链接跳转至新tab。取值:

  • true:表示展示。

  • false(默认值):表示不展示。

privacyAlertConfig

object

二次弹窗相关配置。配置对象详情请参见privacyAlertConfig 二次弹窗相关配置

privacyCheckedUrl

string

协议勾选时的图片地址。

privacyUnCheckedUrl

string

协议未勾选时的图片地址。

prePageTypeOption 预授权页面配置

参数名称

参数类型

是否必填

参数说明

mount

string

指定挂载节点的ID,此参数不传或者找不到会直接报错。

btnText

string

按钮文案,默认值:点击登录。

privacyOne

string

自定义协议1,格式['name',url]。

privacyTwo

string

自定义协议2,格式['name',url]。

tips

string

在预授权页面的登录按钮模块,可以加自己的小设计,提高可扩展性。

privacyVenderIndex

number

运营商协议的位置,默认为2。

  • 0:最前面。

  • 1:中间位置。

  • 2:最后面。

vendorPrivacyPrefix

string

设置运营商协议前缀符号,仅支持设置如下字符中的任意一个,如<>、()、《》、【】、『』、[]、()

vendorPrivacySuffix

string

设置运营商协议后缀符号,仅支持设置如下字符中的任意一个,如<>、()、《》、【】、『』、[]、()

privacyBefore

string

设置开发者隐私条款前置自定义文案。默认:我已阅读并同意。

privacyEnd

string

设置开发者隐私条款前置自定义文案。

privacyCheckedImg

HTMLImageElement

默认为圆形勾选,如需自定义可传入需要的图片。

privacyAlertConfig 二次弹窗相关配置

参数名称

参数类型

是否必填

参数说明

title

string

二次弹窗标题文案。默认值:请阅读并同意用户注册协议。

btnText

string

二次弹窗按钮文案。默认值:我已阅读并同意以上协议。

说明

privacyAlertIsNeedAutoLogin为true时,btnText不可配置,默认:同意协议并登录

privacyAlertIsNeedAutoLogin

boolean

点击二次弹窗同意按钮是否自动登录。取值:

  • true:表示自动登录。

  • false:表示不自动登录。

    说明
    • 当掩码未输入时,自动聚焦第一个输入框,并弹出软键盘。

    • 当四位掩码已输入时,自动触发授权页点击按钮,获取到spToken。

privacyAlertIsDialog

boolean

是否弹窗模式。取值:

  • true(默认值):表示是弹窗模式。

  • false:表示不是弹窗模式。

privacyAlertMaskIsNeedShow

boolean

是否展示蒙层。取值:

  • true:表示展示。

  • false(默认值):表示不展示。

    说明

    privacyAlertIsDialog为true时该参数生效。

isLoginShowPrivacyAlert

boolean

点击授权页(预授权)登录按钮时是否自动弹出二次弹窗。取值:

  • true:表示自动弹出。

  • false(默认值):表示不自动弹出。

privacyAlertLoginText

string

privacyAlertIsNeedAutoLogintrue时二次弹窗协议页面按钮文案,取值:

  • login(默认值):表示二次弹窗协议页面按钮文案为“同意协议并登录”。

  • continue:表示二次弹窗协议页面按钮文案为“同意协议并继续”。

其他方法说明

getConnection(网络类型检查接口

本接口会判断当前用户的网络类型并返回netType

  • wifi:Wi-Fi网络,建议对该类用户提醒关闭Wi-Fi或提供其他认证方式。

  • cellular:移动数据网络。

  • unknown:未知网络类型。

本接口与认证流程不相关联,您可自行选择是否调用。建议认证前调用此接口,拦截使用Wi-Fi网络的用户,节约资源并提升用户的认证体验。

const netType = phoneNumberServer.getConnection(); // 返回netType: wifi, cellular, unknown

getVersion(获取SDK版本号

const sdkVersion = phoneNumberServer.getVersion();  // 返回SDK版本号,如'1.0.0' 

sendLoggerEnable(设置开启日志)

phoneNumberServer.setLoggerEnable(true); // true为开启,false为不开启。

样式说明

以下为原始样式的层级,需增加样式权重才能对原有的样式进行覆盖。

重要

一键登录授权页上的返回按钮、关闭按钮、导航栏、运营商协议、标题栏和登录按钮,请不要配置为隐藏。

授权页全屏样式

// 此处可修改导航栏整体样式:字体大小,字体颜色,背景颜色等
.page-type-container .nav {
   
}

// 此处可修改导航栏返回按钮的样式: 高度、宽度等
.page-type-container .nav .nav-back-icon-img {
   
}

// 此处可修改导航栏标题样式: 字体大小,颜色等
.page-type-container .nav .nav-title {
   
}

// 此处可修改logo容器的样式: 宽度 高度,圆角等
.page-type-container .logo {
    
}

// 此处修改电话号码的样式: 颜色、字体大小等
.page-type-container .number-con {
}

// 此处修改电话号码掩码的样式:宽度、高度、字体颜、色间距等
.page-type-container .number-con input {
}

// 此处修改协议勾选、选中时的颜色
.page-type-container .agreement .checke-1 svg g {
    fill: blue;
}

// 此处修改协议区域的样式: 字体颜色,大小等
.page-type-container .agreement .agree-content {
   
}

// 此处修改协议名称的样式:颜色大小等
.page-type-container .agreement a {
    
}

// 此处修改登录按钮的样式:颜色大小背景色等
.page-type-container .submit-btn{

}

授权弹窗样式

// 此处可修改标题栏整体样式:字体大小,字体颜色,背景颜色等
.dialog-type-container .nav {
   
}


// 此处可修改标题样式: 字体大小,颜色等
.dialog-type-container .nav .nav-title {
   
}

// 关闭按钮
div.dialog-type-container .close-btn::before, .dialog-type-container .close-btn::after{

}

// 此处可修改logo容器的样式: 宽度、高度、圆角等
.dialog-type-container .logo {
    
}

// 此处修改电话号码的样式: 颜色、字体大小等
.dialog-type-container .number-con {
}

// 此处修改电话号码掩码的样式:宽度、高度、字体颜、色间距等
.dialog-type-container .number-con input {
}

// 此处修改协议勾选、选中时的颜色
.dialog-type-container .agreement .checke-1 svg g {
    fill: blue;
}

// 此处修改协议区域的样式: 字体颜色,大小等
.dialog-type-container .agreement .agree-content {
   
}

// 此处修改协议名称的样式:颜色大小等
.dialog-type-container .agreement a {
    
}


// 此处修改登录按钮的样式:颜色大小背景色等
.dialog-type-container .submit-btn{

}

预授权模式

// 按钮样式
div.number-auth-demo .protocol-front-page-container .number-auth-btn-wrap {

  // border-radius: 30px;
  // width: 300px;
  // height: 80px;
  // color: #666;
}

二次弹窗样式

/**蒙层样式**/
.privacy-alert-container .privacy-alert-mask {
  background: rgba(0, 0, 0, 0.75);
}

/**标题样式**/
.privacy-alert-container .page-type-tabs .page-type-list-nav span {
 
}

/**协议头标题样式**/
.privacy-alert-container .page-type-tabs .page-type-list-nav span {
  
}

/**协议内容 (弹窗模式) 如果按钮遮盖了协议内容建议减小协议内容的高度进行调整 **/
.privacy-alert-container .privacy-alert-modal.dialog .page-type-tabs iframe {
  width: 100%;
  height: 75vh; // 默认高度
}

/**二次弹窗按钮默认样式**/
.privacy-alert-container .privacy-alert-modal .privacy-alert-btn {
  position: fixed;
  bottom: 10px;
  left: 0;
  padding: 10px 0;
  width: 92vw;
  background: linear-gradient(90deg, #FF8101 3%, #FF6B01 100%);
  border: none;
  border-radius: 2px;
  color: #fff;
  font-size: 4.8vmin;
  font-weight: 200;
  margin: 4vw;
}