Android对接指南

[隐藏]

交互流程

Group 25.png

业务方每次调用SDK预登录接口将收集一次个人信息

  合规使用说明(接入前必读)

为了确保用户在登录过程中将手机号码信息授权给合作方使用的知情权,天翼账号登录认证需要合作方满足如下要求:

1)合作方在调用登录认证方法前,必须显示出登录页面,登录页面需明确告知用户操作会将用户本机号码信息授权给应用;(天翼账号服务与隐私协议url地址:https://e.189.cn/sdk/agreement/detail.do?hidetop=true

2)合作方需展示“天翼账号”品牌露出,不得通过任何技术手段,将登录页面的隐私栏、品牌露出内容隐藏、覆盖;

若有出现未按要求设计登录页面的行为或有非正常调用行为,为了保护用户的隐私安全,我方有权将合作方应用的登录功能下线,由此产生的一切影响由合作方自己承担。

如下是天翼账号标准页面的设计规范,供合作方参考;

图片8.png 

 

为满足以上要求,接入资料中未包含相应的导入包,需合作方将如下信息在开放平台上进行配置,我方即可提供导入包:

(1)一个APPID对应一个应用,故需要提供如下信息,用于校验该APPID对应的应用请求:

Android端:APPID、包名packagename、包签名(签名证书的MD5值

iOSAPPIDbundleID(可配置测试和正式的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.1. 接入说明

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.2. 导入aar

(1) AAR包导入到libs目录下

图片1.png 

 

 

(2) build.gradle配置aar依赖

dependencies {

//namelibs目录下.aar文件名称,ext.aar的扩展名

   compile(name: 'CTAccountSdk_v3.6.0_armeabi', ext: 'aar')

}

 

1.3. 配置权限与组件清单

(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" />

 

 

 

1.4. 配置混淆规则

在混淆配置文件末尾添加如下:

-keep class cn.com.chinatelecom.account.**{*;}

1.5. SDK接口调用说明

1.5.1. 初始化SDK

【接口说明】

在使用天翼账号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日志

【响应参数】

1.5.2. 预登录接口

【接口说明】

在调用该接口前,建议先做本地预判断处理,符合条件再调用预登录接口。预登录接口可获取脱敏手机号、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

 

1.5.3. 打开登录界面

【接口说明】

使用该接口前,必须先完成调用初始化和预登录接口。在预登录成功后,才调用该接口打开登录界面,用户点击一键登录按钮,将立即返回登录结果(无网络请求)。

(注意:打开登录界面后,需确保该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.5.4. 打开登录界面(支持动态配置)

【接口说明】

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

失效时间

预登录结果失效时间戳

 

1.5.5. 关闭登录界面

【接口说明】

当返回登录结果后,合作方APP可以调用该接口关闭登录界面。

【调用示例】

CtAuth.getInstance().finishAuthActivity();

【请求参数】

【响应参数】

 

1.5.6. 打开Mini登录界面

【接口说明】

使用该接口前,必须先完成调用初始化和预登录接口。在预登录成功后,才调用该接口打开登录界面,用户点击一键登录按钮,将立即返回登录结果(无网络请求)。

(注意:打开登录界面后,需确保该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.5.7. 打开Mini登录界面(支持动态配置)

【接口说明】

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

失效时间

预登录结果失效时间戳

 

1.5.8. 关闭Mini登录界面

【接口说明】

当返回登录结果后,合作方APP可以调用该接口关闭登录界面。

【调用示例】

CtAuth.getInstance().finishMiniAuthActivity();

【请求参数】

【响应参数】

 

1.5.9. 设置WebView桥接方法

通过设置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");

1.5.10. 网络切换接口

【接口说明】

接入方可以通过此接口实现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

切换耗时

切换网络过程耗时统计