如何集成Harmony鸿蒙客户端一键登录以及有哪些相关接口

本文为您介绍鸿蒙客户端一键登录的集成方法及接口的功能示例。

说明

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

重要

一键登录服务必须打开蜂窝数据流量并且手机系统给与应用蜂窝数据权限才能使用。
取号请求过程需要消耗用户少量数据流量。
移动运营商支持2G、3G、4G、5G数据流量，2G、3G因为网络环境问题时延和成功率会比4G低。
电信运营商支持4G、5G数据网络，不支持2G、3G数据流量。
联通运营商支持3G、4G、5G数据网络，不支持2G。

接入步骤

获取SDK

登录号码认证产品控制台，在概览页面右侧API&SDK区域，单击立即下载，进入API&SDK页面，选择号码认证鸿蒙平台，完成SDK下载。

导入项目

在DevEco Studio中建立你的工程。
将下载的SDK压缩包解压后的har文件拷贝至项目的扩展库目录下（可参考压缩包提供的demo项目）。

申请认证方案密钥

调用API的过程会使用对应的方案Code和密钥等参数信息。请先在号码认证产品控制台，创建认证方案获取方案Code和密钥等参数信息。创建认证方案时需要提供您的App名称、包名、包签名以及AppId。

获取签名

您可通过以下鸿蒙官方代码，获取应用相关属性（包名、包签名和AppId）。

bundleManager.getBundleInfoForSelf(bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_SIGNATURE_INFO).then((bundleInfo) => {
  const packageName = bundleInfo.name
  console.log("numberauth:pagname:" + packageName)
  const sign = bundleInfo.signatureInfo.fingerprint
  console.log("numberauth:sign:" + sign)
  const appIdentifier = bundleInfo.signatureInfo.appIdentifier
  console.log("numberauth:appid:" + appIdentifier)
})

对应用签名

如果您还未对新创建的项目进行签名，建议您通过DevEco Studio自动化签名方式对应用签名：

使用自动签名功能实现签名，点击IDE右上角Project Structure图标：
在弹出界面依次选择Project > SigningConfigs，并勾选Automatically generate signature，等待自动签名完成即可，单击OK。

如您需要了解更多HarmonyOS应用配置签名信息，请参见HarmonyOS官方文档。

添加权限配置

编辑module.json5文件配置SDK相应权限：

    "requestPermissions": [
      {
        "name": 'ohos.permission.INTERNET',
        "name": 'ohos.permission.GET_NETWORK_INFO',
        "name":"ohos.permission.SET_NETWORK_INFO"
      }
    ]

权限说明

权限	说明
INTERNET	允许应用程序联网，用于访问网关和认证服务器。
GET_NETWORK_INFO	获取网络状态，判断是否数据、Wi-Fi等。
SET_NETWORK_INFO	允许应用配置数据网络，取号时需要切换到蜂窝网络。

交互流程详解

完整的功能交互流程请参见一键登录交互流程。

SDK方法说明

必调方法：创建功能入口实例

PhoneNumberAuthHelper是SDK的功能入口，所有的接口调用都需要通过PhoneNumberAuthHelper进行。

方法原型

public static getInstance(context: Context, listener: TokenResultListener): PhoneNumberAuthHelper;

参数说明：

参数	参数类型	参数说明
context	Context	调用的上下文环境。
listener	TokenResultListener	流程监控回调。

调用示例

class TokenListener implements TokenResultListener {
    private page: Index

    constructor(page: Index) {
        this.page = page;
    }

    onSuccess(msg: string): void {
        console.log("auth:onSuccess:" + msg)
        const result: object = JSON.parse(msg)
        const code = result['_code'] + ''
        const token = result['_token'] + ''
        if (code === "600000") {
            this.page.quitLoginPage()
        }
    }

    onFailure(ret: string): void {
        console.log("auth:onFailure:" + ret)
        this.page.updateAuth()
    }
}

let listener = new TokenListener(this)
this.helper = PhoneNumberAuthHelper.getInstance(getContext(this), listener)

必调方法：配置授权页界面参数

public  setAuthConfig(config: AuthUiConfig): void;

参数说明：

参数	参数类型	参数说明
config	AuthUiConfig	授权页及二次弹窗界面参数信息实体类，请参见UI页面接口说明。

必调方法：设置密钥

public setAuthSDKInfo(secretInfo: string): void

参数说明：

参数	参数类型	参数说明
secretInfo	string	SDK密钥，在号码认证控制台申请认证方案获得。

必调方法：Token获取流程

授权请求

应用调用本方法时，SDK将拉取用户授权页面，用户确认授权后SDK将返回token给应用端：

//totalTime 超时时间单位ms
public getLoginToken(totalTime: number): Promise<void>;

参数说明：

参数	参数类型	参数说明
totalTime	number	超时时间设置。

调用示例

this.helper.getLoginToken(5000)

方法返回在入口监控回调TokenListener中，示例代码如下：

class TokenListener implements TokenResultListener {
    private page: Index

    constructor(page: Index) {
        this.page = page
    }

    onSuccess(msg: string): void {
        console.log("auth:onSuccess:" + msg)
        const result: object = JSON.parse(msg)
        const code = result['_code'] + ''
        const token = result['_token'] + ''
        if (code === "600000") {
            this.page.quitLoginPage()
        }
    }

    onFailure(ret: string): void {
        console.log("auth:onFailure:" + ret)
        this.page.updateAuth()
    }
}

必调方法：清除流程回调监听

在流程完成后需调用该方法清除监听避免后台监听：

public clearAuthListener():void

选调方法：退出授权页界面

进入授权页后可调用该方法退出授权页界面：

public quitLoginPage(): Promise<void>;

可通过调用此方法关闭授权页跳出阿里云号码认证SDK，切换用户自定义的登录控件。

例如：Demo示例中（具体路径如下图所示）使用自定义Logo组件设置Logo图片及位置，点击Logo图片关闭授权页，然后调用用户自定义的登录逻辑，实现切换其他方式登录的效果。Demo下载请参见鸿蒙客户端Demo体验。

146192785d5eebab39d64f5f8dc6ac4c

选调方法：设置回调监听

添加或更新流程监听接口：

public setAuthListener(listener: TokenResultListener): void

参数说明：

参数	参数类型	参数说明
listener	TokenResultListener	添加或更新流程监听接口。

选调方法：检测运行环境

检测运行环境，判断设备环境是否适合SDK运行,结果会在接口回调监控中返回：

public checkEnvAvailable(type: number): void

参数说明：

参数	参数类型	参数说明
type	number	SDK功能类型。取值：1，一键登录；2，是本机号码校验。

选调方法：一键登录加速接口

加速接口可以加快拉起授权页速度，可提前调用，如hap初始化时：

public accelerateLoginPage(overdueTimeMills: number, listener: PreLoginResultListener): void

参数说明：

参数	参数类型	参数说明
overdueTimeMills	number	超时时间，单位：ms。
listener	PreLoginResultListener	回调监听接口。

选调方法：SDK界面点击事件监听接口

授权页拉起后监听授权页及二次弹窗页点击事件：

public setUIClickListener(listener: AuthUIControlClickListener): void

参数说明：

参数	参数类型	参数说明
listener	AuthUIControlClickListener	点击事件回调监听接口。

UI页面接口说明

创建授权页

号码认证Harmony标准版授权页说明：

导航栏

方法名	类型	说明
windowBarProperties	window.SystemBarProperties	设置授权页及协议详情页顶部状态栏。

手机掩码

方法名	类型	说明
numberMagin	Margin	设置手机掩码偏移。
numberFontSize	number	设置手机掩码字体大小。
numberFontColor	ResourceColor	设置手机掩码字体颜色。
numberHeight	Length	设置手机掩码栏高度。
numberAlignRuleOption	AlignRuleOption	设置手机掩码栏相对布局偏移规则。

登录按钮

方法名	类型	说明
loginBtnText	string	登录按钮文本。
loginBtnMagin	Magin	登录按钮偏移。
loginBtnPadding	Padding	登录按钮内边距。
loginBtnFontSize	number	登录按钮文本字体大小。
loginBtnFontColor	ResourceColor	登录按钮文本字体颜色。
loginBtnWidth	Length	登录按钮宽度。
loginBtnrHeight	Length	登录按钮高度。
loginBtnBackGroundColor	ResourceColor	登录按钮背景色。
loginBtnBackGroundImage	Resource	设置登录按钮背景图。说明 media资源的目录，不需要加后缀，如图片在media中的存放目录是resources/media/test.png,则传入参数为"test"，loginBtnBackGroundImage=$r('app.media.test')。
loginBtnAlignRuleOption	AlignRuleOption	登录按钮相对布局偏移规则。

协议栏

协议栏相关：

方法名	类型	说明
privacyBackgrounColor	ResourceColor	协议栏背景色。
privacyFontColor	ResourceColor	协议栏字体颜色。
privacyFontSize	number	协议栏字体大小。
privacyMargin	Margin	协议栏偏移。
privacyAlignRuleOption	AlignRuleOption	协议栏相对布局偏移规则。

复选框相关：

privacyCbWidth	Length	协议栏复选框宽度。
privacyCbHeight	Length	协议栏复选框高度。
privacyCbMargin	Margin	协议栏复选框相对布局偏移规则。
privacyCbIsOn	boolean	复选框默认是否选中。
privacyCbSelectColor	ResourceColor	复选框选中色。
privacyCbAlignRuleOption	AlignRuleOption	复选框相对布局偏移规则。
privacyCbShape	CheckBoxShape	复选框样式。
pricacyCbClipText	string	复选框未选中时登录提示信息。

其他：

privacySpanBeforeText	string	协议栏前置文本。
privacySpanBeforeFontSize	number	协议栏前置文本字体大小。
privacySpanBeforeFontColor	ResourceColor	协议栏前置文本字体颜色。
privacyOperatorIndex	OperatorIndex	设置运营商协议位置：前置：OperatorIndex.BEGIN 后置：OperatorIndex.END
vendorPrivacyPrefix	string	设置运营商协议前缀符号，只能设置一个字符且只能设置`<>`、`()`、`《》`、`【】`、`『』`、`[]`、`（）`中的一个。
vendorPrivacySuffix	string	设置运营商协议后缀符号，只能设置一个字符且只能设置`<>`、`()`、`《》`、`【】`、`『』`、`[]`、`（）`中的一个。
privacySpanOneText	string	第一个自定义协议文本。
privacySpanOneUrl	string	第一个自定义协议网址。
privacySpanOneFontSize	number	第一个自定义协议字体大小。
privacySpanOneFontColor	ResourceColor	第一个自定义协议字体颜色。
privacySpanTwoText	string	第二个自定义协议文本。
privacySpanTwoUrl	string	第二个自定义协议网址。
privacySpanTwoFontSize	number	第二个自定义协议字体大小。
privacySpanTwoFontColor	ResourceColor	第二个自定义协议字体颜色。
privacySpanThreeText	string	第三个自定义协议文本。
privacySpanThreeUrl	string	第三个自定义协议网址。
privacySpanThreeFontSize	number	第三个自定义协议字体大小。
privacySpanThreeFontColor	ResourceColor	第三个自定义协议字体颜色。

自定义组件

方法名	类型	说明
loginPageComponent	WrappedBuilder<[]>	自定义组件（实现方式参见demo）。

创建二次弹窗

二次弹窗会在授权页复选框未勾选协议复选框的情况下弹出：

方法名	类型	说明
privacyAlertTitleText	string	弹窗提示文本。
privacyAlertConfirmBtnText	string	弹窗确认按钮文本。
privacyAlertConfirmBtnTextColor	ResourceColor	弹窗确认按钮文本颜色。
privacyAlertCancelBtnText	string	弹窗取消按钮文本。
privacyAlertCancelBtnTextColor	ResourceColor	弹窗取消按钮文本颜色。

SDK返回码

调用号码认证鸿蒙客户端SDK过程中返回的错误码请参见阿里云号码认证SDK返回码说明（鸿蒙客户端专属）。

SDK导入失败问题解决

SDK引入后，点击IDE右上角同步即可正常导入。

若出现无法导入情况：

需要将引入module的oh_modules及项目根目录下oh_modules删除。
然后在DevEco Studio底部Terminal中输入ohpm install重新导入即可。