如何集成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文件拷贝至您项目的libs扩展库目录下。
在module下的oh_package.json5文件中添加SDK依赖：
注意：非项目根目录下的oh_package.json5文件，建议您参考压缩包内的Demo项目。
```
"dependencies": {
    "numberauth_standard": "file:libs/auth_number_product-2.0.1-log-online-standard-release.har"
  }
```

添加权限配置

编辑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	允许应用配置数据网络，取号时需要切换到蜂窝网络。

申请认证方案密钥

调用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 > Signing Configs，并勾选Automatically generate signature，等待自动签名完成即可，单击OK。

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

交互流程详解

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

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，是本机号码校验。

选调方法：获取运营商类型

返回默认上网SIM卡的运营商类型：

public getCurrentCarrierName(): String

返回值说明：CMCC：中国移动；CUCC：中国联通；CTCC：中国电信。

选调方法：一键登录加速接口（预取号接口）

建议调用此接口：提前调用此接口可快速唤起授权页。唤起授权页的前提条件是预取号必须要成功，如果没有提前调用本接口，直接调用getlogintoken接口时，SDK内部仍会自动先行调用预取号接口，所以唤起授权页会有一个明显的等待过程。

何时调用此接口：

建议在调用拉取授权页getlogintoken接口前，提前2-3秒调用本接口（因为本接口调用后需要1~3s的时间取得临时凭证）。
建议在判断当前用户属于未登录状态时调用，已登录状态用户请不要调用该方法。
请勿频繁地多次调用、请勿在拉起授权登录页时或之后调用。
进入App后立即登录的场景不需要调用此接口。

调用示例：

class PreListener implements PreLoginResultListener {
    onTokenSuccess(vendor: string): void {
        throw new Error('Method not implemented.');
    }

    onTokenFailed(vendor: string, ret: string): void {
        throw new Error('Method not implemented.');
    }
}

let preListener = new PreListener();
this.helper.accelerateLoginPage(5000, preListener);

参数说明：

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

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

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

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

public setUIClickListener(listener: AuthUIControlClickListener): void

参数说明：

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

选调方法：获取授权页协议复选框选中状态

可通过此方法判断授权页协议复选框是否勾选，并展示提示信息或二次隐私协议弹窗。

public queryCheckBoxIsChecked(): boolean

UI页面接口说明

创建授权页

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

如果您使用自定义协议，请确认您协议栏配置的所有自定义协议详情页HTML的<title>是否有配置内容。如未配置<title>，用户点击查看协议详情内容时会显示网页URL，影响界面美观。

导航栏

方法名	类型	说明
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	登录按钮相对布局偏移规则。

协议栏

协议栏相关：

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

复选框相关：

privacyCbUnSelectImg	Resource	通过指定图片设置复选框在未选中状态下的显示效果，默认为空。
privacyCbSelectImg	Resource	通过指定图片设置复选框在选中状态下的显示效果，默认为空。
privacyCbWidth	Length	协议栏复选框宽度。
privacyCbHeight	Length	协议栏复选框高度。
privacyCbMargin	Margin	协议栏复选框相对布局偏移规则。
privacyCbIsOn	boolean	复选框默认是否选中。
privacyCbSelectColor	ResourceColor	复选框选中色。
privacyCbAlignRuleOption	AlignRuleOption	复选框相对布局偏移规则。
privacyCbShape	CheckBoxShape	复选框样式。
pricacyCbClipText	string	复选框未选中时登录提示信息。

其他：

自定义协议配置注意事项：

建议您在协议详情页HTML内配置<title>属性，如<title>用户服务隐私协议</title>。如有多个自定义协议时均需配置<title>属性。

如果协议详情页未配置<title>或<title>属性无法正常获取，协议详情页顶部会显示协议URL，影响界面美观。

privacySpanBeforeText	string	协议栏前置文本。
privacySpanBeforeFontSize	number	协议栏前置文本字体大小。
privacySpanBeforeFontColor	ResourceColor	协议栏前置文本字体颜色。
privacySpanBeforeFontWeight	FontWeight	协议栏前置文本字体样式，默认取值`FontWeight.Normal`。
privacySpanEndText	string	协议栏后置文本。
privacySpanEndFontSize	number	协议栏后置文本字体大小。
privacySpanEndFontColor	ResourceColor	协议栏后置文本字体颜色。
privacySpanEndFontWeight	FontWeight	协议栏后置文本字体样式，默认取值`FontWeight.Normal`。
privacyOperatorIndex	OperatorIndex	设置运营商协议位置：前置：OperatorIndex.BEGIN 后置：OperatorIndex.END
vendorPrivacyPrefix	string	设置运营商协议前缀符号，只能设置一个字符且只能设置`<>`、`()`、`《》`、`【】`、`『』`、`[]`、`（）`中的一个。
vendorPrivacySuffix	string	设置运营商协议后缀符号，只能设置一个字符且只能设置`<>`、`()`、`《》`、`【】`、`『』`、`[]`、`（）`中的一个。
privacySpanOneText	string	第一个自定义协议文本。在授权页单击协议文本`privacySpanOneText` 将跳转至配置好的`privacySpanOneUrl 第一个自定义协议网址`。
privacySpanOneUrl	string	第一个自定义协议网址。
privacySpanOneFontSize	number	第一个自定义协议字体大小。
privacySpanOneFontColor	ResourceColor	第一个自定义协议字体颜色。
privacySpanTwoText	string	第二个自定义协议文本。
privacySpanTwoUrl	string	第二个自定义协议网址。
privacySpanTwoFontSize	number	第二个自定义协议字体大小。
privacySpanTwoFontColor	ResourceColor	第二个自定义协议字体颜色。
privacySpanThreeText	string	第三个自定义协议文本。
privacySpanThreeUrl	string	第三个自定义协议网址。
privacySpanThreeFontSize	number	第三个自定义协议字体大小。
privacySpanThreeFontColor	ResourceColor	第三个自定义协议字体颜色。

协议详情页

方法名	类型	说明
navFontColor	ResourceColor	设置服务条款标题栏字体颜色。默认值为`Color.Black`。
navFontSize	number	设置服务条款标题栏字体大小。默认值大小为`16`。

自定义组件

方法名	类型	说明
loginPageComponent	WrappedBuilder<[]>	授权页自定义组件（实现方式请参见Demo）。
clauseComponent	WrappedBuilder<[]>	协议详情页自定义组件（实现方式请参见Demo）。

如需在授权页底部添加“其他登录方式”，可通过自定义组件和quitLoginPage退出授权页界面实现。详细示例请参见选调方法：退出授权页界面。

创建二次弹窗

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

方法名	类型	说明
needShowPrivacyAlert	boolean	在未勾选协议复选框时点击登录按钮，二次隐私协议弹窗是否需要显示。取值： true（默认值）：显示。 false：不显示。
privacyAlertTitleText	string	弹窗提示文本。
privacyAlertConfirmBtnText	string	弹窗确认按钮文本。
privacyAlertConfirmBtnTextColor	ResourceColor	弹窗确认按钮文本颜色。
privacyAlertCancelBtnText	string	弹窗取消按钮文本。
privacyAlertCancelBtnTextColor	ResourceColor	弹窗取消按钮文本颜色。

SDK返回码

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

导入常见问题解决

[build init]failed:npm ERR! Error: EPERM: operation not permitted
Windows系统权限问题解决方法：请先确认您的本地开发环境如SDK、Node.js等配置无误后，尝试以管理员方式启动DevEco Studio。

[Ohpm Install]failed:ohpm ERROR: missing: numberauth_standard

此问题表明numberauth_standard依赖包未找到或未正确引用，建议根据项目导入检查您的SDK依赖项位置及名称是否添加正确。完整错误信息：

ohpm ERROR: missing: numberauth_standard@C:\workspace\NumberAuthDemo\demo\libs, required by demo@1.0.0
ohpm ERROR: Found exception: Error: Fetch local folder package error, C:\workspace\NumberAuthDemo\demo\libs\oh-package.json5 does not exist., reached retry limit or non retryable error encountered.
ohpm ERROR: Install failed, detail: Error: Fetch local folder package error, C:\workspace\NumberAuthDemo\demo\libs\oh-package.json5 does not exist.

SDK无法导入问题解决：
需要将引入的oh_modules及项目根目录下oh_modules删除。删除后在DevEco Studio底部Terminal中输入ohpm install重新导入即可。