本文为您介绍Android客户端融合认证的集成方法及接口的功能示例。
接入步骤
下载SDK
登录号码认证产品控制台,在概览页面的右侧API&SDK区域,单击立即下载,进入API&SDK页面,选择融合认证安卓平台,完成SDK下载。
导入项目
项目根目录build.gradle文件添加依赖:
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.0"
。控制minSdkVersion。
说明融合认证SDK最低依赖版本为21,因此创建新项目minSdkVersion不能低于21。
导入AAR文件,并添加依赖。
在使用融合认证功能的module中引入相关SDK,即将相关AAR导入module的
libs
文件夹。如您的项目需要使用手机号风险分、端风险设置功能,请将友盟相关组件一起引入。相关设置,请参见友盟组件依赖设置。
如您的项目不需要使用手机号风险分、端风险设置功能,请引入融合认证AAR即可。
在module下
build.gradle
文件中找到dependencies,添加如下引用:implementation fileTree(dir: "libs", include: ["*.aar"]) implementation 'androidx.appcompat:appcompat:1.3.1' implementation "org.jetbrains.kotlin:kotlin-stdlib:1.4.0"
创建签名文件。
参考为应用签名,创建签名文件,此签名文件在创建认证方案时使用,签名文件放置在module下,文件名及文件路径无设置要求。
以Demo为例,将签名文件放置在
app/sig-adaptation/debug/
文件夹下,在module的build.gradle
文件中指向该签名。查看包签名。
使用Studio右侧面板,选择Gradle > 项目名称 > 签名文件module > Tasks > android > signingReport,查看包签名。
说明包签名获取方式如下:
方式一:上图的下方输出的MD5值移除冒号,将大写字母转换为小写字母即可生成包签名。如果右侧面板没有signingReport,请参见生成签名报告。
方式二:请通过手机终端下载并安装Android App签名获取工具,获取Android App的包签名信息。
创建认证方案
您使用SDK时,会用到方案Code。在获取到包签名后,请在号码认证产品控制台,创建认证方案,获取方案Code。
添加配置
添加权限。
在
AndroidManifest.xml
清单文件中添加必要权限。<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
添加Activity声明。
在
AndroidManifest.xml
清单文件中添加Activity声明。//号码认证界面 <activity android:name=".numberauth.FusionNumberAuthActivity" android:exported="false" android:configChanges="orientation|keyboardHidden|screenSize" android:screenOrientation="behind" android:theme="@style/NumberAuthTheme" /> //短信界面 <activity android:name=".smsauth.FusionSmsActivity" android:exported="false" android:configChanges="orientation|keyboardHidden|screenSize" android:screenOrientation="behind" /> //图形验证界面 <activity android:name=".graphauth.FusionGraphAuthActivity" android:exported="false" android:configChanges="orientation|keyboardHidden|screenSize" android:screenOrientation="behind"/> //上行短信界面 <activity android:name=".upsms.AlicomFusionUpSmsActivity" android:exported="false" android:configChanges="orientation|keyboardHidden|screenSize" android:screenOrientation="behind" /> //号码认证授权页界面 <activity android:name="com.mobile.auth.gatewayauth.LoginAuthActivity" android:configChanges="orientation|keyboardHidden|screenSize" android:exported="false" android:launchMode="singleTop" android:screenOrientation="behind" android:theme="@style/authsdk_activity_dialog" /> //号码认证二次弹窗授权界面 <activity android:name="com.mobile.auth.gatewayauth.PrivacyDialogActivity" android:configChanges="orientation|keyboardHidden|screenSize" android:exported="false" android:launchMode="singleTop" android:screenOrientation="behind" android:theme="@style/authsdk_activity_dialog" /> //号码认证协议及登录注册场景协议界面,需要您自定义实现 <activity android:name="com.alicom.fusion.demo.CustomWebViewActivity" android:configChanges="orientation|keyboardHidden|screenSize|uiMode|fontScale" android:screenOrientation="sensorPortrait"> <intent-filter> //action为固定值不能修改 <action android:name="com.fusion.auth"/> <category android:name="android.intent.category.DEFAULT"/> </intent-filter> </activity>
说明图形认证界面无法添加自定义view,如果您不需要该功能,可以在认证策略设置中关闭图形验证节点。
混淆配置。
如您有混淆需求,请在混淆文件中加入如下混淆规则:
-keep class com.alicom.fusion.auth.**{*;}
使用场景
融合认证SDK涵盖以下5个场景,您可以通过相应场景ID实现场景的调用。
使用场景 | 场景 ID |
100001 | |
100002 | |
100003 | |
100004 | |
100005 |
场景的具体策略设置,请参见全局策略。
交互流程
客户端集成阿里云融合认证SDK,完成初始化。
服务端对接GetFusionAuthToken接口获取鉴权Token,下发至客户端后传入SDK进行鉴权。
客户端唤起场景授权页面,部分场景需要用户授权(同意隐私协议、获取短信验证码等)。
用户授权后,客户端通过SDK的回调接口获取到统一认证Token后,将统一认证Token上传到服务端。
服务端对接VerifyWithFusionAuthToken接口,将Token转换为用户的手机号。
SDK方法说明
创建实例
// 创建无参数构造方法,主要进行⼀些SDK初始化⼯作
AlicomFusionBusiness mAlicomFusionBusiness = new AlicomFusionBusiness();
初始化鉴权Token
SDK在启动时需要传入鉴权Token,用于合法性校验。
鉴权Token需要从服务端获取,请参见GetFusionAuthToken接口。
方案Code需要在控制台创建认证方案后获取,具体操作请参见创建认证方案。
/**
* @param mContext 上下文
* @param sceneCode 方案Code
* @param token 鉴权Token
*/
public void initWithToken(Context mContext, String sceneCode, AlicomFusionAuthToken token)
鉴权成功、失败、过期都将触发主流程回调(AlicomFusionAuthCallBack),您需要实现相应回调:
鉴权成功:通过
onSDKTokenAuthSuccess()
回调,场景操作必须在回调成功后进行。鉴权失败:通过
onSDKTokenAuthFailure()
回调。Token更新:Token过期前五分钟,通过
onSDKTokenUpdate()
回调获取新的Token。您需要实现此回调,以获取新的Token。
设置回调
SDK流程各个节点运行状态都通过回调来通知用户,您需要实现主流程回调AlicomFusionAuthCallBack
。
主流程回调 AlicomFusionAuthCallBack
/**
* Token需要更新
*
* @return token,APP更新最新token后,组装Token返回给到SDK,SDK会通过此Token进行鉴权更新
* 用户可在此处进行token获取,两次请求,每次30s,60s后无法获取会报token获取超时
* @note 必选回调,只在超时调用获取。handler初始化&历史Token过期前5分钟,会触发此回调,由SDK维护token的生命周期
*/
AlicomFusionAuthToken onSDKTokenUpdate();
/**
* Token鉴权成功
*
* @note 必选回调,token鉴权成功后,才可以使用startScene接口拉起场景
* @note 不建议在本回调中直接调用startScene接口,本回调跟随token鉴权事件触发,可能存在多次回调
* startSceneWithTemplateId开始场景必须在该回调后进行,具体逻辑参考demo
*/
void onSDKTokenAuthSuccess();
/**
* Token鉴权失败
*
* @param failToken 错误token
* @param error 错误定义
* @note 必选回调,token初次鉴权失败&token更新后鉴权失败均会触发此回调
* @note token鉴权失败后,无法继续使用SDK的功能,请销毁SDK后重新初始化
*/
void onSDKTokenAuthFailure(AlicomFusionAuthToken failToken, AlicomFusionEvent error);
/**
* 认证成功
*
* @param token 统一认证Token
* @param nodeName 获取Token的节点名称
* @param event verify成功事件
* 认证成功即各节点成功获取相应Token,用户可使用相应Token进行换号或登录操作,根据操作反馈选择继续或中断流程
* 具体逻辑参考demo
* @note 必选回调
* @note 可以使用maskToken去服务端做最终验证换取真实手机号码,如果换取手机号失败,可以通过SDK的continue接口继续后续场景流程
*/
void onVerifySuccess(String token, String nodeName, AlicomFusionEvent event);
/**
* 中途认证节点,需要知道中途认证结果,否则影响流程继续执行
*
* @param nodeName 获取Token的节点名称
* @param maskToken 统一认证Token
* @param event 事件
* @param verifyResult 回调
* 该回调出现在换号场景对当前登录账号获取token进行验证,根据验证结果调用HalfWayVerifyResult回调的verifyResult方法
* 决定流程走向,具体逻辑参考demo
* @note 必选回调
* @note 可以使用maskToken去服务端做最终验证换取真实手机号码,通过resultBlock告知SDK验证结果,如果失败则SDK不进行任何操作,成功则进入下一个节点
*/
void onHalfWayVerifySuccess(String nodeName, String maskToken, AlicomFusionEvent event, HalfWayVerifyResult verifyResult);
/**
* 认证失败
*
* @param error 获取Token失败事件
* @param nodeName 获取Token的节点名称
* 认证失败回调,如号码认证中无法拉起授权页,Token获取失败,短信界面无法获取短信或者开启手机号校验
* 时输入手机号与传入手机号不符及开启自动填充后传入手机号小于11位,上行界面获取上行信息失败等情况
* 认证失败后可选择继续或者中断流程,具体逻辑参考demo
* @note 必选回调
* @note 当接收到这个回调的时候说明在当前场景中出现获取Token失败的情况,您可控制是否继续
*/
void onVerifyFailed(AlicomFusionEvent error, String nodeName);
/**
* 场景流程结束 正常加异常结束
*
* @param event 错误定义
* 融合认证SDK内部流程已结束,需要您调用stopSceneWithTemplateId中断流程
* @note 必选回调,认证流程结束,认证失败,不可逆
*/
void onTemplateFinish(AlicomFusionEvent event);
/**
* 场景事件回调
*
* @param event 点击事件 用户操作记录
* 对SDK内部关键节点运行回调,辅助开发,快速定位问题
* @note 可选回调,SDK场景流程中各个界面点击事件&界面跳转事件等UI相关回调
* @note 本回调接口仅做事件通知,不可再此回调内处理业务逻辑
*/
void onAuthEvent(AlicomFusionEvent event);
/**
* 填充手机号,用于校验手机号是否和输入的一致,或者重新绑定手机号场景自动填充手机号
*
* @param nodeId 节点id
* @param event 事件
* @return 返回当前用户正在使用的手机号用于下一步操作
* 如果开启自动填充或者自动校验,用户需传入相应号码继续流程,具体逻辑参考demo
* @note 必选回调,SDK内置UI部分手机号
*/
String onGetPhoneNumberForVerification(String nodeId, AlicomFusionEvent event);
/**
* 认证中断
*
* @param event 中断原因
* 流程无法进行停留在当前界面,此回调处于节点进行状态,开始继续或中断方法无效
* @note 必选回调
* @note 认证流程临时中断,APP可根据不同事件显示对应的提示信息
* @note 触发条件:1. 未勾选隐私协议框,进行认证;2. 验证手机号码输入格式错误,3sdk开始加载某个节点和结束加载某个节点,4、相关的接口可用校验
*/
void onVerifyInterrupt(AlicomFusionEvent event);
实现主流程回调(AlicomFusionAuthCallBack)后,您需要使用下面的方法进行回调设置。
/**
* @param callback 主流程回调
*/
public void setAlicomFusionAuthCallBack(AlicomFusionAuthCallBack callback)
开始场景
调用该接口的前提是没有其他正在执行的场景,否则将报100003错误。
需要Token鉴权成功后才可使用。
场景ID(
templateId
)请参见使用场景。
/**
* @param mContext 上下文
* @param templateId 场景ID
* @param callback (可选)自定义UI时使用:如果使用默认UI,该参数可不传;自定义UI需通过该回调实现
*/
public void startSceneWithTemplateId(Context mContext, String templateId, AlicomFusionAuthUICallBack callback)
使用默认UI
使用默认UI,您将无法修改UI。示例代码如下:
mAlicomFusionBusiness.startSceneWithTemplateId(<YOUR_CONTEXT>, "100001");
使用自定义UI
根据实际场景可以通过界面UI流程回调(AlicomFusionAuthUICallBack
)修改相关UI,具体请参见界面UI流程回调。示例代码如下:
mAlicomFusionBusiness.startSceneWithTemplateId(<YOUR_CONTEXT>, "100001", new AlicomFusionAuthUICallBack() {
@Override
public void onPhoneNumberVerifyUICustomView(String templateId, String nodeId, FusionNumberAuthModel authConfig) {
// 自定义一键登录UI参数
}
/**
* 短信登录页面的整个view对象是完全开放的,用户可以自行修改,具体实现效果及代码由用户自定义实现。
*/
@Override
public void onSMSCodeVerifyUICustomView(String templateId, String nodeId, boolean isAutoInput, AlicomFusionVerifyCodeView view) {
//移除SDK短信登录页面默认的所有内置组件
view.getRootRl().removeAllViews();
//SDK获取验证码的内置接口
view.verifyCodeBtnClick("");
//SDK提交验证码的内置接口
view.submitVerifyCodeBtnClick("","");
//获取协议文本对象
TextView privacyTV = view.getInputView().getPrivacyTV();
//自定义短信认证UI参数
}
@Override
public void onSMSSendVerifyUICustomView(String templateId, String nodeId, AlicomFusionUpSMSView view, String receivePhoneNumber, String verifyCode) {
// 自定义上行短信认证UI参数
}
});
场景流程
场景执行将触发主流程回调(AlicomFusionAuthCallBack),您需要实现相应回调:
获取Token成功:通过
onVerifySuccess()
回调,返回当前节点统一认证Token。您获取到该Token后可通过VerifyWithFusionAuthToken接口换取号码。获取Token失败:通过
onVerifyFailed()
回调。在收到该回调后,您可以选择继续场景,进行下一节点的验证;或结束场景。中途获取Token成功:在场景ID为100002、验证当前手机号节点时触发,通过
onHalfWayVerifySuccess()
回调。在您验证完成当前手机号后,通过verifyResult
告知SDK验证结果,SDK将根据该结果执行之后的流程。场景流程结束:通过
onTemplateFinish()
回调,需要您调用结束场景。
继续场景
用于场景中断后恢复流程。如获取到统一认证Token后,假设服务端验证失败,可以通过该接口继续进行场景流程。
需要在start后才能使用。
/**
* @param templateId 场景ID
* @param isSuccess 当前场景验证是否成功,将决定后续流程走向(如取号操作失败,需下一步鉴权,可通过该参数控制走向)
*/
public void continueSceneWithTemplateId(String templateId, boolean isSuccess)
结束场景
当需要结束场景时调用该接口,对应的场景将不再执行。
需要在start后才能使用,结束后才可以start下一个场景,不可同时start多个场景。
/**
* @param templateId 场景ID
*/
public void stopSceneWithTemplateId(String templateId)
销毁服务
销毁服务后,SDK内部各个模块同步销毁。若想继续使用SDK,请重新初始化。
public void destory()
其他接口说明
友盟组件依赖设置
如果您需要使用友盟组件的端风险检测及手机号评分功能,需要配置AAR后,调用下面的方法决定友盟组件的初始化位置。
本功能属于插件式依赖,不属于强制性依赖。您需要引入AAR配置,否则设置无效。
/**
* 设置是否由SDK初始化友盟统计组件
* @note SDK默认使用融合认证关联友盟组件,如果您当前App未集成友盟组件,根据SDK集成文档接入各个SDK后,无需再关心此接口设置
* @note 如果您当前已经集成过友盟组件,则⽆需重复集成,使用此接口关闭内置链接,并确保使用本SDK前已经完成友盟组件初始化
* @param isUseSupply true:使用SDK默认关联友盟组件;false:不使用SDK关联友盟组件,即使用App原有友盟组件,默认true
* @param channel 渠道名称
*/
public static void useSDKSupplyUMSDK(boolean isUseSupply,String channel)
主动更新鉴权Token
本接口为非必要接口:SDK内部存在Token的过期监控,过期前会通过AlicomFusionAuthCallBack
回调通知客户端,客户端可不感知此项逻辑。
鉴权Token具有时效性,客户端可在鉴权Token即将过期时,主动更新鉴权Token。鉴权Token相关更新逻辑请参见initWithToken。
/**
* @param token 鉴权Token
*/
public void updateToken(AlicomFusionAuthToken token)
获取SDK版本号
/**
* @return SDK版本号
*/
public static String getSDKVersion()
获取场景ID
/**
* @return templateId 当前正在运行中的场景ID
*/
public String getCurrentTemplateId()
日志功能
/**
* @param logEnable 是否打印log(默认开启)
*/
public static void setLogEnable(boolean logEnable)
SDK界面适配异形屏
/**
* @param adapterPageShape 是否适配:true适配,false不适配。默认false
*/
public void adapterPageShape(boolean adapterPageShape)
设置界面方向
设置界面方向必须在initWithToken之后调用,否则无效。
//1竖屏;2横屏。默认为:1竖屏。
private volatile int screenOretation = 2;
UI页面接口说明
界面UI流程回调 AlicomFusionAuthUICallBack
/**
* ⼀键登录自定义UI
* @note ⼀键登录界面不可100%完全自定义,请通过AlicomFusionNumberAuthModel参数进行修改
* 请不要调整view id属性,否则可能造成部分功能无法使用
* @param templateId 场景ID
* @param nodeId 节点ID
* @param authConfig 自定义UI属性
*/
void onPhoneNumberVerifyUICustomView(String templateId, String nodeId, FusionNumberAuthModel authConfig);
/**
* 短信验证码认证自定义UI
* @note 短信登录页面的整个view对象是完全开放的,您可以自行修改AlicomFusionVerifyCodeView
* 请不要调整view id属性,否则可能造成部分功能无法使用
* @param templateId 场景ID
* @param nodeId 节点ID
* @param isAutoInput 是否自动填充手机用户配置autoNumberShow值进行判断
* 是否填充通过AlicomFusionAuthCallBack回调的onGetPhoneNumberForVerification方法传入的手机号
* @param view 短信验证码界面view,具体实现效果及代码由用户自定义实现。
*/
void onSMSCodeVerifyUICustomView(String templateId, String nodeId, boolean isAutoInput, AlicomFusionVerifyCodeView view);
/**
* 上⾏短信认证自定义UI
* @note 请不要调整view id属性,否则可能造成部分功能无法使用
* @param templateId 场景ID
* @param nodeId 节点ID
* @param view 上行短信认证界面view
* @param receivePhoneNumber 短信接收号码
* @param verifyCode 短信内容
*/
void onSMSSendVerifyUICustomView(String templateId, String nodeId, AlicomFusionUpSMSView view, String receivePhoneNumber, String verifyCode);
⼀键登录自定义UI参数 FusionNumberAuthModel
public class FusionNumberAuthModel {
// 实现其他号码登录功能
public void otherPhoneLogin()
// 添加自定义XML布局
@AuthNumber
public void addAuthRegisterXmlConfig(AuthRegisterXmlConfig xmlConfig)
// 添加自定义View
public void addAuthRegistViewConfig(String viewID, AuthRegisterViewConfig viewConfig)
// 移除自定义XML布局
public void removeAuthRegisterXmlConfig()
// 移除自定义View
public void removeAuthRegisterViewConfig()
/**
* 设置UI控件点击事件回调
*
* @param uiClickListener 回调实现
*/
public void setUiClickListener(AuthUIControlClickListener uiClickListener)
/**
* 设置切换组件swtich点击事件
*
* @param callBack 回调实现
*/
public void setSwitchLoginBack(AlicomFusionSwitchLogin callBack)
// 获取参数实体对象,参数方法请参见后续表格
public Builder getBuilder()
}
配置授权页导航栏
配置授权页Logo
配置授权页Slogan
配置授权页号码栏
配置授权页登录按钮
配置授权页隐私栏
配置切换控件方式
配置页面相关函数
配置二次隐私协议弹窗页面
一键登录界面添加自定义XML布局
/**
* @param xmlConfig
*/
@AuthNumber
public void addAuthRegisterXmlConfig(AuthRegisterXmlConfig xmlConfig)
一键登录界面添加自定义View
/**
* @param viewID view的ID
* @param viewConfig view的动态配置
*/
public void addAuthRegistViewConfig(String viewID, AuthRegisterViewConfig viewConfig)
二次弹窗界面添加XML布局
/**
* @param xmlConfig
*/
public void addPrivacyRegisterXmlConfig(AuthRegisterXmlConfig xmlConfig)
二次弹窗界面添加自定义View
/**
* @param viewID view的ID
* @param viewConfig view的动态配置
*/
public void addPrivacyAuthRegistViewConfig(String viewID, AuthRegisterViewConfig viewConfig)
短信认证自定义UI参数 AlicomFusionVerifyCodeView
public class AlicomFusionVerifyCodeView {
//顶部title区域
private RelativeLayout titleRl;
//返回按钮
private ImageView returnImg;
//标题文本框
private TextView titleContentTV;
//自动填充手机号区域
private AlicomFusionAutoInputView autoInputView;
//手动输入手机号区域
private AlicomFusionInputView inputView;
//输入及发送验证码区域
private AlicomFusionSendVerifyCodeView sendVerifyCodeView;
//获取验证码
public void verifyCodeBtnClick(String phoneNumber)
//校验验证码
public void submitVerifyCodeBtnClick(String phoneNumber, String code)
}
自动填充手机号区域
public class AlicomFusionAutoInputView {
/**自动填充布局上方显示手机号及提示信息*/
private RelativeLayout autoInputMsgRL;
/**自动填充布局手机号展示*/
private TextView autoInputPhoneNumTV;
/**自动填充布局提示信息*/
private TextView autoInputPhoneHintTV;
/**自动填充布局获取验证码*/
private TextView autoInputRequestCodeTV;
}
手动输入手机号区域
public class AlicomFusionInputView {
/**国家号及手机号输入框区域*/
private RelativeLayout inputNumberContentRL;
/**国家号*/
private TextView mCountryTV;
/**手机号输入框*/
private EditText inputNumberET;
/**手动输入手机号布局获取验证码*/
private TextView inputNumberRequestCodeTV;
/**协议区域*/
private RelativeLayout privacyRL;
/**协议复选框*/
private CheckBox agreePrivacy;
/**协议文本*/
private TextView privacyTV;
}
输入及发送验证码区域
public class AlicomFusionSendVerifyCodeView {
/**提示信息*/
private TextView sendSmsHint;
/**验证码输入区域*/
private RelativeLayout sendSmsCodeRL;
/**第⼀位验证码*/
private EditText firstCode;
/**第⼆位验证码*/
private EditText secondCode;
/**第三位验证码*/
private EditText thirdCode;
/**第四位验证码*/
private EditText fourCode;
/**第五位验证码*/
private EditText fivthCode;
/**第六位验证码*/
private EditText sixthCode;
/**发送验证码按钮*/
private TextView sendSmsCode;
}
上行短信认证自定义UI参数 AlicomFusionUpSMSView
public class AlicomFusionUpSMSView {
//上行短信界面顶部导航区域
private RelativeLayout titleRl;
//返回按钮
private ImageView returnImg;
//title文本
private TextView titleContentTV;
//提示信息区域
private RelativeLayout remindRl;
//提示信息文本框
private TextView smsRemindTV;
//短信内容区域
private RelativeLayout smsContentRl;
//短信内容文本框
private TextView smsContentTV;
//接收号码区域
private RelativeLayout receiveSmsNumberRl;
//接收号码文本框
private TextView receiveSmsNumberTV;
//⽴即发送短信按钮
private TextView sendSmsTV;
//我已发送短信按钮
private TextView HadSenTSmsTV;
//发送短信
public void gotoSendUpSms(String receivePhoneNumber, String verifyCode)
//发送短信校验
public void upSmsAlreadySend()
}