创蓝闪验SDK鸿蒙版HarmonyOS一键登录号码认证

一.准备工作

升级指南

手动集成闪验所有版本通用方式：
替换SDK包： 删除旧版本SDK所有相关的.har文件，清除缓存，再导入新版SDK中的所有.har文件。

前置条件

• SDK支持中国移动、联通、电信的取号能力。
• SDK支持网络环境为：
  • 纯数据网络
  • 数据网络与wifi网络双开
• 对于双卡手机，SDK取当前流量卡号码
• SDK使用DevEco Studio 5.0.0 Release开发，支持API12及以上版本。

一键登录使用场景：
用户无需输入手机号码，只需集成并调用SDK拉起授权页方法，用户确认授权后，SDK会获取并返回token，服务端携带token到运营商网关获取用户当前上网使用的流量卡号码，并返回给APP服务端。

本机号码校验(本机认证)使用场景：
用户通过SDK获取token，服务端携带手机号码和token去运营商网关进行校验比对，返回的校验结果为：用户当前流量卡号码与服务端携带的手机号码是否一致。

创建应用

应用的创建流程及APPID的获取，请查看「账号创建」文档

注意：应用 AppId 与包名、包签名一一绑定，如果应用有多个包名或签名不同的应用，须创建多个对应包名和签名的应用，否则初始化会报包名或签名校验不通过。

快速体验Demo

将创建应用时获得的bundleName和appid，appkey分别填入Demo工程中即可体验（appid和appkey在文件AppConfig中配置）
demo示例代码：CLShanYan_Harmony/ShanYanDemo at main · 253CL/CLShanYan_Harmony · GitHubContribute to 253CL/CLShanYan_Harmony development by creating an account on GitHub.https://github.com/253CL/CLShanYan_Harmony/tree/main/ShanYanDemo

开发环境搭建

1. 导入har： 将SDK压缩包中har添加到工程中。
2. 在oh-package.json5中配置如下内容：

   "dependencies": {
       "shanyansdk": "file:../ShanYanSDK"
     }

3. 在model.json5中配置如下权限：
   • ohos.permission.INTERNET
   • ohos.permission.GET_NETWORK_INFO
   • ohos.permission.SET_NETWORK_INFO

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

权限说明

二.SDK使用说明

1.初始化

使用场景

• 在app启动时进行调用
• 保证在预取号或一键登录前至少调用一次
• 只需调用一次，多次调用不会多次初始化，与一次调用效果一致

请求示例代码

1. 导入SDK头文件

import { CLResult, CLSDKManager } from 'shanyansdk'

1. 初始化方法

static async init(context: Context, appId: string): Promise<CLResult> 

let result: CLResult = await CLSDKManager.init(getContext(this), "APP_ID")

参数说明:

返回值说明:

2.预取号

使用场景

• 建议在执行一键登录的方法前，提前一段时间调用此方法，此调用将有助于提高拉起授权页的速度和成功率
• 不建议调用后立即调用拉起授权页方法（此方法是异步）
• 此方法需要1~2s的时间取得临时凭证，因此也不建议和拉起授权页方法一起串行调用
• 不建议频繁的多次调用和在拉起授权页后调用
• 建议在判断当前用户属于未登录状态时使用，已登录状态用户请不要调用该方法

接口作用

电信、联通、移动预取号 :初始化成功后，如果当前为电信/联通/移动，将调用预取号，可以提前获知当前用户的手机网络环境是否符合一键登录的使用条件，成功后将得到用于一键登录使用的临时凭证，默认的凭证有效期60min(三大运营商一致)。

请求示例代码

static async preGetPhoneNumber(): Promise<CLResult> 

let result: CLResult = await CLSDKManager.preGetPhoneNumber()

返回值说明:

3.拉起授权页

使用场景

• 用户进行一键登录操作时，调用一键登录方法，如果初始化成功，SDK将会拉起授权页面，用户授权后，SDK将返回取号 token给到应用客户端。
• 可以在多处调用
• 需在调用预初始化方法之后调用

一键登录逻辑说明

• 存在调用预初始化时获取的临时凭证，调用一键登录方法将立即拉起授权页面
• openLoginAuthListener： 拉起授权页面成功或失败的回调，拉起成功或失败均触发。当拉起失败时，oneKeyLoginListener不会触发。此回调的内部触发时机是viewDidAppear
• oneKeyLoginListener：一键登录监听， 拉起授权页成功后的后续操作回调，包括点击SDK内置的(非外部自定义)取消登录按钮，以及点击本机号码一键登录的回调。点击授权页自定义按钮不触发此回调
• 不存在临时凭证或临时凭证过期时(临时凭证有效期电信60min、联通60min、移动60min)，调用一键登录方法，将有一个很短的时延，待取号成功后拉起授权页面
• 取号失败时，返回失败

在预取号成功后调用，预取号失败不建议调用。调用拉起授权页方法后将会调起运营商授权页面。该方法会拉起登录界面，已登录状态请勿调用 。

请求示例代码

static async quickAuthLoginWithConfigure(clUIConfigure: CLUIConfigure,
    oneKeyLoginListener: (result: CLResult) => void): Promise<CLResult>

let config = new CLUIConfigure()
let pgResult: CLResult =
  await CLSDKManager.quickAuthLoginWithConfigure(config, async (result: CLResult) => {

  })

参数说明:

返回值说明:

• 用户取消登录(授权页点击返回) 【处理建议：若无特殊需求可不做处理】
• 用户选择其他方式登录(点击授权页自带的其他方式登录): 【处理建议：可根据实际情况跳转其他登录方式 】
• 其他错误 【处理建议：使用通道失败，可根据实际情况跳转其他登录方式 】

4.关闭授权页

建议在置换手机号成功后销毁授权页。

关闭授权页时机

a.SDK拉起授权页方法 直接回调失败时

b.置换手机号有返回结果时

授权页销毁

销毁授权页界面

static closeAuthLoginPage()

CLSDKManager.closeAuthLoginPage()

三.授权界面修改

1.设计规范

注意:

1、开发者不得通过任何技术手段，破解授权页，或将授权页面的号码栏、隐私栏、品牌露出内容隐 藏、覆盖。

2、登录按钮文字描述必须包含“登录”或“注册”等文字，不得诱导用户授权。

3、对于接入SDK并上线的应用，我方会对上线的应用授权页面做审查，如果有出现未按要 求弹出或设计授权页面的，将关闭应用的认证取号服务。

2.页面可调整属性、布局

**注：授权页基本控件布局通过布局对象设置，布局定位更加方便快捷

export class CLUIConfigure {
  // 设置导航栏、状态栏属性
  systemBarProperties?: window.SystemBarProperties
  // 设置服务条款标题字体大小
  navTextSize?: number
  // 设置服务条款标题字体颜色
  navTextColor?: ResourceColor
  // 设置服务条款标题颜色
  navColor?: ResourceColor
  // 设置服务条款标题栏自定义view
  clauseComponent?: () => void
  // 设置授权页布局自定义View
  loginPageComponent?: () => void
  // 设置号码栏字体大小、字体粗细
  numberSize?: number
  // 设置手机号码字体颜色
  numberColor?: ResourceColor
  // 设置号码栏偏移
  numberMargin?: Margin
  // 设置号码栏相对布局偏移规则
  numberAlignRuleOption?: AlignRuleOption
  // 设置登录按钮宽度
  loginBtnWidth?: Length
  // 设置登录按钮高度
  loginBtnHeight?: Length
  // 设置登录按钮文本内容
  loginBtnText?: string
  // 设置授权登录文本字体大小
  loginBtnTextSize?: number
  // 设置授权登录按钮字体颜色
  loginBtnTextColor?: ResourceColor
  // 设置登录按钮边缘边距
  loginBtnMargin?: Margin
  // 设置登录按钮相对布局偏移规则
  loginBtnAlignRuleOption?: AlignRuleOption
  // 设置登录按钮背景图片
  loginBtnImgPath?: ResourceStr
  // 设置登录按钮背景颜色
  loginBtnColor?: ResourceColor
  // 设置登录按钮点击监听事件
  loginClickListener?: CLLoginClickListener
  // 设置隐私条款的协议文本，自定义条款，自定义条款链接、字体颜色
  clauses?: Array<PrivacyEntity>
  // 设置隐私条款偏移边距
  clauseMargin?: Margin
  // 设置隐私条款相对布局偏移规则
  clauseAlignRuleOption?: AlignRuleOption
  // 设置隐私条款勾选框宽度
  checkBoxWidth?: Length
  // 设置隐私条款勾选框高度
  checkBoxHeight?: Length
  // 设置隐私条款勾选框勾选状态
  clauseState?: boolean
  // 设置隐私条款勾选框偏移边距
  checkBoxMargin?: Margin
  // 设置勾选框类型(圆角矩形/圆形)
  checkBoxShape?: CheckBoxShape
  // 设置隐私条款勾选框相对布局偏移规则
  checkBoxAlignRuleOption?: AlignRuleOption
  // 设置授权页勾选框和登录按钮的监听事件
  checkBoxListener?: CLCheckBoxListener
  // 设置授权页勾选框是否勾选的监听事件
  checkedChangeListener?: CLCheckedChangeListener
  // 设置未勾选提示的自定义提示文案。不设置则无提示。
  checkTipText?: string
  // 设置勾选颜色
  checkedColor?: ResourceColor
  // 设置默认元素语言，0.中文简体 1.中文繁体 2.英文
  appLanguageType?: number
  // 设置授权页返回键监听事件
  backPressedListener?: CLBackPressedListener
  // 设置授权按钮监听事件，入参回调CLAuthLoginListener，用户点击 登录按钮时如果未勾选协议，
  // 触发CLAuthLoginListener的 (context: UIContext,callBack:CLAuthLoginCallBack) 方法。可以实现 二次弹窗确认的功能
  authLoginListener?: CLAuthLoginListener
}

let config = new CLUIConfigure()
let systemBarProperties: window.SystemBarProperties = {
  statusBarColor: '#ff00ff',
  navigationBarColor: '#00ff00',
  statusBarContentColor: '#ffffff',
  navigationBarContentColor: '#00ffff'
}
config.systemBarProperties = systemBarProperties
config.navTextColor = Color.White
config.navColor = Color.Pink
config.appLanguageType = 1

// 登录按钮点击监听事件  （勾选后进入正常的授权登录）
config.loginClickListener = ({
  onLoginClickStart(context: UIContext) {
    HiLogUtils.info("loginClickListener：开始登录授权")
  }
, onLoginClickComplete(context: UIContext) {
    HiLogUtils.info("loginClickListener：登录授权结束")
  }
})
config.loginPageComponent = authPageComponent

// 设置授权页返回键监听事件
config.backPressedListener = ({
  async onBackPressed() {
    HiLogUtils.info("backPressedListener：返回")
    let systemBarProperties: window.SystemBarProperties = {
      statusBarColor: '#ffffff'
    }
    let windowClass: window.Window = await window.getLastWindow(getContext(this))
    await windowClass.setWindowSystemBarProperties(systemBarProperties)
  }
})

// 授权按钮监听 1
config.authLoginListener = ({
  onAuthLoginListener(context: UIContext, callBack: CLAuthLoginCallBack) {
    promptAction.showDialog({
      message: '是否登录授权',
      buttons: [
        {
          text: '确定',
          color: '#000000'
        },
        {
          text: '取消',
          color: '#000000'
        }
      ],
    })
      .then(data => {
        // 授权回调，通过onAuthLoginCallBack(b:boolean)决定是否继续登录 流程。可以实现二次弹窗确认的功能
        if (data.index == 0) {
          CLSDKManager.clearScripCache()
          callBack.onAuthLoginCallBack(true)
        } else {
          callBack.onAuthLoginCallBack(false)
        }
      })
  }
})

// 设置授权页勾选框和登录按钮的监听事件
config.checkBoxListener = ({
  onLoginClick() {
    HiLogUtils.info("checkBoxListener：未勾选时点击一键登录回调")
  }
})
// 设置授权页勾选框是否勾选的监听事件
config.checkedChangeListener = ({
  onCheckedChanged(b) {
    HiLogUtils.info("checkedChangeListener：勾选状态改变:" + b)
  }
})
config.checkBoxShape = CheckBoxShape.ROUNDED_SQUARE
config.checkTipText = "没选中- -- ~"

config.clauses = [{
  text: "同意",
  isProtocol: false,
  fontColor: Color.Black,
  fontSize: 16,
  fontWeight: FontWeight.Bold,
},
  {
    text: "《**CLAUSE**》",
    isProtocol: true,
    fontColor: Color.Red,
    fontSize: 16,
    fontWeight: FontWeight.Bold,
  },
  {
    text: "、",
    isProtocol: false,
    fontColor: Color.Black,
    fontSize: 16,
    fontWeight: FontWeight.Bold
  },
  {
    text: "自定义协议1",
    isProtocol: true,
    fontColor: Color.Red,
    fontSize: 16,
    fontWeight: FontWeight.Bold,
    url: "https://www.baidu.com/"
  },
  {
    text: "、",
    isProtocol: false,
    fontColor: Color.Black,
    fontSize: 16,
    fontWeight: FontWeight.Bold
  },
  {
    text: "自定义协议2",
    isProtocol: true,
    fontColor: Color.Red,
    fontSize: 16,
    fontWeight: FontWeight.Bold,
    url: "https://www.sina.com/"
  },
  {
    text: "并使用本机号码校验",
    isProtocol: false,
    fontColor: Color.Black,
    fontSize: 16,
    fontWeight: FontWeight.Bold
  }]

状态栏配置:

服务条款配置:

授权页布局:

授权页号码配置:

授权页登录按钮配置:

授权页隐私条款配置:

授权页语言配置:

授权页拉返回监听:

授权按钮布局:

四.本机认证

1.初始化

同“二、SDK使用说明-->初始化”

2.本机认证

接口作用
本机号码校验 : 验证指定手机号与本机SIM卡是否一致。(此接口仅返回token，手机号验证需调用服务端)

使用场景

• 在初始化接口后调用
• 输入手机号后进行校验

请求示例代码

 static async mobileCheckWithLocalPhoneNumberComplete(): Promise<CLResult>

let result: CLResult = await CLSDKManager.mobileCheckWithLocalPhoneNumberComplete()

返回值说明:

3.手机号后台服务端校验

当一键登录外层 code 为 2000 时，会获取到检验手机号所需的 token。请参考「服务端」文档来实现检验手机号码的步骤。

五.返回码对照

外层错误码

同一外层码可能对应不同的内层码

内层错误码

联通返回码

电信返回码

移动返回码