Android对接指南
交互流程
l 业务方每次调用SDK预登录接口将收集一次个人信息
为了确保用户在登录过程中将手机号码信息授权给合作方使用的知情权,天翼账号登录认证需要合作方满足如下要求:
(1)合作方在调用登录认证方法前,必须显示出登录页面,登录页面需明确告知用户操作会将用户本机号码信息授权给应用;(天翼账号服务与隐私协议url地址:https://e.189.cn/sdk/agreement/detail.do?hidetop=true)
(2)合作方需展示“天翼账号”品牌露出,不得通过任何技术手段,将登录页面的隐私栏、品牌露出内容隐藏、覆盖;
若有出现未按要求设计登录页面的行为或有非正常调用行为,为了保护用户的隐私安全,我方有权将合作方应用的登录功能下线,由此产生的一切影响由合作方自己承担。
如下是天翼账号标准页面的设计规范,供合作方参考;
为满足以上要求,接入资料中未包含相应的导入包,需合作方将如下信息在开放平台上进行配置,我方即可提供导入包:
(1)一个APPID对应一个应用,故需要提供如下信息,用于校验该APPID对应的应用请求:
Android端:APPID、包名packagename、包签名(签名证书的MD5值)
iOS端:APPID、bundleID(可配置测试和正式的bundleID)
已对接过的合作方请留意错误码的改动,以防影响正常使用逻辑。
所需权限调用说明:
业务场景 | 对应权限 | 调用权限目的 | 调用频率 |
免密预取号 | INTERNET | 允许sdk进行联网 | 由合作方调用接口触发 |
CHANGE_NETWORK_STATE | 运行sdk改变网络连接状态 | ||
ACCESS_WIFI_STATE | 允许sdk访问wifi网络状态信息 | ||
ACCESS_NETWORK_STATE | 允许sdk访问联网状态,区分用户设备时蜂窝网络或者是wifi网络 | ||
WRITE_EXTERNAL_STORAGE | 把打印的日志信息保存在外部存储目录(代码已经废弃,后续版本会删除) | ||
GET_TASKS | 在打开免密页面时,sdk获取堆栈信息判断当前最顶层页面activity是否被覆盖 |
(1)接入前请先确认
A. 已申请appId、appSecret。
B. 正确配置包名与签名(签名指纹MD5值)。
若无,请按1.2的指引申请
(2)选择SDK包
SDK 含有so库,请根据您项目的so目录(若有),选择包含对应ABI目录的aar包。
A.CTAccountSdk_HY_v3.8.x_armeabi.aar ,只包含了armeabi的so库(若您项目无so库或只有armeabi目录,建议使用该aar包);
B.CTAccountSdk_HY_v3.8.x_all.aar,包含多个so库目录(分别armeabi,armeabi-v7a,arm64-v8a,x86,x86_64,请根据您项目so库目录,过滤多余的so库)
(1) 将AAR包导入到libs目录下
(2) 在build.gradle配置aar依赖
dependencies {
//name为libs目录下.aar文件名称,ext为.aar的扩展名
compile(name: 'CTAccountSdk_v3.6.0_armeabi', ext: 'aar')
}
(1) 在AndroidManifest.xml配置权限
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.GET_TASKS" />
(2)配置权限说明
权限 | 用途 |
INTERNET | 允许应用程序联网 |
CHANGE_NETWORK_STATE | 允许程序改变网络连接状态 |
ACCESS_WIFI_STATE | 允许程序访问WiFi网络状态信息 |
ACCESS_NETWORK_STATE | 允许程序访问联网状态,区分用户设备是移动网络或WiFi |
GET_TASKS | 允许访问task |
(3)Activity组件配置
<activity
android:name="cn.com.chinatelecom.account.sdk.ui.AuthActivity"
android:exported="false"
android:theme="@style/authActivityTheme"
android:screenOrientation="portrait" />
<activity
android:name="cn.com.chinatelecom.account.sdk.ui.MiniAuthActivity"
android:exported="false"
android:theme="@style/authMiniActivityTheme"/>
<activity
android:name="cn.com.chinatelecom.account.sdk.ui.PrivacyWebviewActivity"
android:exported="false"
android:theme="@style/authActivityTheme"
android:screenOrientation="portrait" />
在混淆配置文件末尾添加如下:
-keep class cn.com.chinatelecom.account.**{*;}
【接口说明】
在使用天翼账号SDK接口之前,必须先调用初始化方法(提前1s以上最佳),建议在Application或Activity的onCreate()调用。不建议初始化与预登录接口同时调用。
【调用示例】
CtAuth.getInstance().init(context, APPID , APPSECRET, false);
【请求参数】
参数名 | 类型 | 必填 | 说明 |
context | Context | 是 | 上下文环境 |
appId | String | 是 | 向天翼账号平台申请的应用ID |
appSecret | String | 是 | 向天翼账号平台申请的应用密钥 |
isDebugMode | boolean | 是 | 调试模式(上线前需置为false) false:不输出SDK日志 true:输出SDK日志 |
【响应参数】
无
【接口说明】
在调用该接口前,建议先做本地预判断处理,符合条件再调用预登录接口。预登录接口可获取脱敏手机号、accessCode、gwAuth等信息,其中脱敏手机号可用于登录界面的展示,accessCode默认有效期为60分钟。(备注:旧方法名requestPreCode已废弃,请使用新方法名requestPreLogin)
SDK提供两个预判断方法:
1、 判断移动数据网络是否开启
CtAuth.getInstance().isMobileDataEnabled();
返回:
true:表示已开启移动数据网(支持预登录)
false:表示未开启移动数据网(不支持预登录)
2、 判断当前运营商类型
CtAuth.getInstance().getOperatorType();
返回:
"CT":电信 , "CM":移动 , "CU":联通 ,"UN":未知
【调用示例】
CtAuth.getInstance().requestPreLogin (null ,new ResultListener() {
@Override
public void onResult(String result) {
Log.i(TAG, "requestPreLogin ---> result : " + result);
}
});
【请求参数】
参数名 | 类型 | 必填 | 说明 |
ctSetting | CtSetting | 否 | 超时时间设置,可传null。 也可传入自定义的ctSetting。传null默认为 CtSetting ctSetting =CtSetting(5000,5000 ,10000); 三个参数分别为连接超时时间、读取超时时间、总超时时间。 |
resultListener | ResultListener | 是 | 预登录回调接口,接口方法onResult(String result)用于接收请求结果。其中result为返回结果json格式字符串。 |
【响应参数】
返回结果result的json格式说明:
参数名 | 类型 | 字段含义 | 说明 |
result | int | 结果码 | 返回参数结果码,0表示成功, 详细参考错误码定义(6.1) |
msg | String | 结果说明 | 结果码对应详细说明 |
data | String | 响应数据 | json格式的响应数据 |
reqId | String | 请求Id | 用于在账号平台排查问题 |
data格式说明:
参数名 | 类型 | 字段含义 | 说明 |
operatorType | String | 运营商标识 | CT电信,CU联通,CM移动,UN其他 |
expiredTime | int | 预登录结果失效时间 | 预登录结果失效时间 |
accessCode | String | 授权码 | 天翼账号授权码(可用于登录/校验,一次性有效,有效期60min) |
【接口说明】
使用该接口前,必须先完成调用初始化和预登录接口。在预登录成功后,才调用该接口打开登录界面,用户点击一键登录按钮,将立即返回登录结果(无网络请求)。
(注意:打开登录界面后,需确保该Activity在屏幕的最顶部,由用户点击授权一键登录)
【调用示例】
CtAuth.getInstance().openAuthActivity(context ,authPageConfig,new ResultListener() {
@Override
public void onResult(String result) {
Log.i(TAG, "login ---> result : " + result);
}
});
【请求参数】
参数名 | 类型 | 必填 | 说明 |
context | Context | 是 | 上下文环境 |
authPageConfig | AuthPageConfig | 是 | AuthPageConfig为登录界面配置类,用于设置登录界面的布局文件及控件ID,并传入SDK。 详细说明见Demo |
resultListener | ResultListener | 是 | 登录回调接口,接口方法onResult(String result)用于接收请求结果。其中result为返回结果json格式字符串。 |
【响应参数】
返回结果result的json格式说明:
参数名 | 类型 | 必填 | 说明 |
result | int | 结果码 | 返回参数结果码,0表示成功, 详细参考错误码定义(6.1) |
msg | String | 结果说明 | 结果码对应详细说明 |
data | String | 响应数据 | json格式的响应数据 |
reqId | String | 请求Id | 用于在账号平台排查问题 |
data格式说明:
参数名 | 类型 | 字段含义 | 说明 |
accessCode | String | 授权码 | 天翼账号授权码,用于获取信息接口传参,默认时效性60分钟 |
authCode | String | 校验码 | 天翼账号校验码,用于获取信息接口传参 |
operatorType | String | 运营商标识 | CT电信,CU联通,CM移动,UN其他 |
expiredTime | int | 失效时间 | 预登录结果失效时间戳 |
【接口说明】
1.普通APP接入不需要动态配置,可忽略该接口。
2.该接口在“3.打开登录界面”基础上,增加动态配置功能,支持代码动态设置登录界面(包括LOGO图片、界面字体颜色、大小、文本、控件偏移值、自定义协议等)、对话框和隐私协议界面。
3.使用该接口前,必须先完成调用初始化和预登录接口。在预登录成功后,才调用该接口打开登录界面,用户点击一键登录按钮,将立即返回登录结果(无网络请求)。
(注意:打开登录界面后,需确保该Activity在屏幕的最顶部,由用户点击授权一键登录)
【调用示例】
CtAuth.getInstance().openAuthActivity(context ,authPageConfig,authViewConfig,new ResultListener() {
@Override
public void onResult(String result) {
Log.i(TAG, "login ---> result : " + result);
}
});
【请求参数】
参数名 | 类型 | 必填 | 说明 |
context | Context | 是 | 上下文环境 |
authPageConfig | AuthPageConfig | 是 | AuthPageConfig为登录界面配置类,用于设置登录界面的布局文件及控件ID,并传入SDK。 详细说明见Demo |
authViewConfig | AuthViewConfig | 否 | AuthViewConfig为控件属性动态配置类,对AuthPageConfig类配置的布局文件里的控件进行代码动态修改,详细说明见Demo; 若该值传入null,则与“3.5.3打开登录界面”的使用一致。 |
resultListener | ResultListener | 是 | 登录回调接口,接口方法onResult(String result)用于接收请求结果。其中result为返回结果json格式字符串。 |
【响应参数】
返回结果result的json格式说明:
参数名 | 类型 | 必填 | 说明 |
result | int | 结果码 | 返回参数结果码,0表示成功, 详细参考错误码定义(6.1) |
msg | String | 结果说明 | 结果码对应详细说明 |
data | String | 响应数据 | json格式的响应数据 |
reqId | String | 请求Id | 用于在账号平台排查问题 |
data格式说明:
参数名 | 类型 | 字段含义 | 说明 |
accessCode | String | 授权码 | 天翼账号授权码,用于获取信息接口传参,默认时效性60分钟 |
authCode | String | 校验码 | 天翼账号校验码,用于获取信息接口传参 |
operatorType | String | 运营商标识 | CT电信,CU联通,CM移动,UN其他 |
expiredTime | int | 失效时间 | 预登录结果失效时间戳 |
【接口说明】
当返回登录结果后,合作方APP可以调用该接口关闭登录界面。
【调用示例】
CtAuth.getInstance().finishAuthActivity();
【请求参数】
无
【响应参数】
无
【接口说明】
使用该接口前,必须先完成调用初始化和预登录接口。在预登录成功后,才调用该接口打开登录界面,用户点击一键登录按钮,将立即返回登录结果(无网络请求)。
(注意:打开登录界面后,需确保该Activity在屏幕的最顶部,由用户点击授权一键登录)
【调用示例】
CtAuth.getInstance().openMiniAuthActivity(context ,miniAuthPageConfig,new ResultListener() {
@Override
public void onResult(String result) {
Log.i(TAG, "login ---> result : " + result);
}
});
【请求参数】
参数名 | 类型 | 必填 | 说明 |
context | Context | 是 | 上下文环境 |
miniAuthPageConfig | AuthPageConfig | 是 | AuthPageConfig为登录界面配置类,用于设置登录界面的布局文件及控件ID,并传入SDK。 详细说明见Demo |
resultListener | ResultListener | 是 | 登录回调接口,接口方法onResult(String result)用于接收请求结果。其中result为返回结果json格式字符串。 |
【响应参数】
返回结果result的json格式说明:
参数名 | 类型 | 必填 | 说明 |
result | int | 结果码 | 返回参数结果码,0表示成功, 详细参考错误码定义(6.1) |
msg | String | 结果说明 | 结果码对应详细说明 |
data | String | 响应数据 | json格式的响应数据 |
reqId | String | 请求Id | 用于在账号平台排查问题 |
data格式说明:
参数名 | 类型 | 字段含义 | 说明 |
accessCode | String | 授权码 | 天翼账号授权码,用于获取信息接口传参,默认时效性60分钟 |
authCode | String | 校验码 | 天翼账号校验码,用于获取信息接口传参 |
operatorType | String | 运营商标识 | CT电信,CU联通,CM移动,UN其他 |
expiredTime | int | 失效时间 | 预登录结果失效时间戳 |
【接口说明】
1.普通APP接入不需要动态配置,可忽略该接口。
2.该接口在“3.5.6打开Mini登录界面”基础上,增加动态配置功能,支持代码动态设置登录界面(包括LOGO图片、界面字体颜色、大小、文本、控件偏移值、自定义协议等)、对话框和隐私协议界面。
3.使用该接口前,必须先完成调用初始化和预登录接口。在预登录成功后,才调用该接口打开登录界面,用户点击一键登录按钮,将立即返回登录结果(无网络请求)。
(注意:打开登录界面后,需确保该Activity在屏幕的最顶部,由用户点击授权一键登录)
【调用示例】
CtAuth.getInstance().openMiniAuthActivity(context ,miniAuthPageConfig,miniAuthViewConfig,new ResultListener() {
@Override
public void onResult(String result) {
Log.i(TAG, "login ---> result : " + result);
}
});
【请求参数】
参数名 | 类型 | 必填 | 说明 |
context | Context | 是 | 上下文环境 |
miniAuthPageConfig | AuthPageConfig | 是 | AuthPageConfig为登录界面配置类,用于设置登录界面的布局文件及控件ID,并传入SDK。 详细说明见Demo |
miniAuthViewConfig | AuthViewConfig | 否 | AuthViewConfig为控件属性动态配置类,对AuthPageConfig类配置的布局文件里的控件进行代码动态修改,详细说明见Demo; 若该值传入null,则与“3.5.3打开登录界面”的使用一致。 |
resultListener | ResultListener | 是 | 登录回调接口,接口方法onResult(String result)用于接收请求结果。其中result为返回结果json格式字符串。 |
【响应参数】
返回结果result的json格式说明:
参数名 | 类型 | 必填 | 说明 |
result | int | 结果码 | 返回参数结果码,0表示成功, 详细参考错误码定义(6.1) |
msg | String | 结果说明 | 结果码对应详细说明 |
data | String | 响应数据 | json格式的响应数据 |
reqId | String | 请求Id | 用于在账号平台排查问题 |
data格式说明:
参数名 | 类型 | 字段含义 | 说明 |
accessCode | String | 授权码 | 天翼账号授权码,用于获取信息接口传参,默认时效性60分钟 |
authCode | String | 校验码 | 天翼账号校验码,用于获取信息接口传参 |
operatorType | String | 运营商标识 | CT电信,CU联通,CM移动,UN其他 |
expiredTime | int | 失效时间 | 预登录结果失效时间戳 |
【接口说明】
当返回登录结果后,合作方APP可以调用该接口关闭登录界面。
【调用示例】
CtAuth.getInstance().finishMiniAuthActivity();
【请求参数】
无
【响应参数】
无
通过设置JS桥接对象,实现APP内嵌浏览器支持H5页面进行预登录。具体设置说明如下:
APP内嵌浏览器通过addJavascriptInterface(ctAccountJsBridge , "EAccountJsBridge")方法增加JS桥接对象(其中ctAccountJsBridge为桥接对象, "EAccountJsBridge"为桥接名)
【参数说明】
参数名 | 类型 | 必填 | 说明 |
ctAccountJsBridge | CtAccountJsBridge | 是 | 桥接类的构造方法: cn.com.chinatelecom.account.api.CtAccountJsBridge(WebView wieview) |
name | String | 是 | 桥接名:"EAccountJsBridge" |
【调用示例】
mWebView.addJavascriptInterface(new CtAccountJsBridge(mWebView), "EAccountJsBridge");
【接口说明】
接入方可以通过此接口实现WIFI网络切换数据网络的能力,推荐在获取到预取号结果后尽快调用此接口切换网络后进行取号请求,降低两次IP不一致的可能性。此接口仅作为辅助接口,接入方也可以自行实现网络切换能力后进行取号请求
【调用示例】
/**
* 切换网络至数据网络示例代码
*
* @param context
*/
public void switchNet(Context context) {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
switchNetManager = new SwitchNetManagerExternal(context, DELAY_CHECK);
switchNetManager.switchToMobileNetV5(new SwitchCalllBackExternal() {
@Override
public void onSwitchSuccess(Network t, long consumingTime) {
//TODO 处理取号网络请求
URL realUrl = null;
// 打开和URL之间的连接
try {
if(t != null && isOsV5()){//SDK版本大于21并且返回Network不为空则通过返回network建立网络连接
HttpsURLConnection conn = (HttpsURLConnection) t.openConnection(realUrl);
}else {
HttpsURLConnection conn = (HttpsURLConnection) realUrl.openConnection();
}
} catch (IOException e) {
e.printStackTrace();
}
}
@Override
public void onSwitchError(long consumingTime) {
//处理切换网络失败,必须释放
unregisterNetwork();
//TODO 接入方实现部分
}
@Override
public void onSwitchTimeout() {
//处理切换网络失败,必须释放
unregisterNetwork();
//TODO 接入方实现部分
}
});
} else {
//url与切换成功后所需要进行请求的地址保持一致
String url = "业务请求URL";
switchNetManager = new SwitchNetManagerExternal(context, DELAY_CHECK);
switchNetManager.switchToMobileNetV4(new SwitchCalllBackExternal() {
@Override
public void onSwitchSuccess(Network t, long consumingTime) {
//TODO 处理取号网络请求
URL realUrl = null;
// 打开和URL之间的连接
try {
//SDK版本低于21则直接使用URL建立连接
HttpsURLConnection conn = (HttpsURLConnection) realUrl.openConnection();
} catch (IOException e) {
e.printStackTrace();
}
}
@Override
public void onSwitchError(long consumingTime) {
//处理切换网络失败,必须释放
unregisterNetwork();
//TODO 接入方实现部分
}
@Override
public void onSwitchTimeout() {
//处理切换网络失败,必须释放
unregisterNetwork();
//TODO 接入方实现部分
}
}, url);
}
}【请求参数】
参数名 | 类型 | 必填 | 说明 |
Context | Context | 是 | 上下文 |
DELAY_CHECK
| int
| 是 | 1.用于设置超时时间,单位ms,当达到总的超时时间DELAY_CHECK,将强制停止任务,直接返回超时结果。 |
【响应参数】
返回结果说明:
参数名 | 类型 | 字段含义 | 说明 |
Network | Network
| 网络标识 | 如果SDK版本号大于21,则通过其建立网络连接 |
consumingTime | Long | 切换耗时 | 切换网络过程耗时统计 |