1.2 Android
商户在特定的App应用程序中集成通付盾SDK。此SDK包中的方法只负责采集设备信息并将设备信息发送至通付盾设备指纹服务后台生成用户设备指纹。
1.2.1 SDK导入
解压SDK文件PayEgis_DeviceId_Android_SDK-vx.x.x.zip,得到以下内容:
文件
说明
payegis-did-v{x.x.x}-release.aar
aar形式开发包
payegis-did-v{x.x.x}-release.jar
Jar形式开发包
payegis-did-dex-v{x.x.x}.jar
动态加载原始文件
jniLibs
各种CPU类型的native开发包
设备指纹SDK提供两种集成方式,根据您项目所使用的开发工具选择对应的文件导入。
Android studio配置工程(推荐)
1、添加文件
将设备指纹 SDK 的aar包复制到工程的 libs 目录下,如果有老版本 SDK的包在其中,请删除。如图所示:
2、配置build.gradle文件
在module下的build.gradle文件中添加文件仓库和aar依赖的配置,如下图所示:
添加aar依赖
·aar包中默认提供了armeabi、armeabi-v7a、armeabi-v8a、x86、x86_64五种ABI的支持。
·如果app只需要支持特定的ABI,比如armeabi-v7a,可以在build.gradle添加如下配置:
注:使用aar方式集成无需在应用的AndroidMenifest.xml中申明权限。
完整的build.gradle配置文件可以参考设备指纹Android studio 的DEMO。
eclipse配置工程
1、添加文件
将设备指纹 SDK 的 payegis-did-v{x.x.x}-release.jar文件和jniLibs文件夹下的内容一起复制到工程的 libs 目录下,将payegis-did-dex-v{x.x.x}.jar文件复制到工程的assets目录下,如下图所示。
2、配置 AndroidManifest
将以下代码加入到您工程的AndroidManifest文件中:
//允许读取手机状态的权限
//允许访问网络权限
//允许程序访问有关GSM网络信息
//允许程序访问Wi-Fi网络状态信息
//sdcard读写权限
//允许一个程序访问CellID或WiFi热点来获取粗略的位置
//允许一个程序访问精准位置(如GPS)
//允许程序连接配对过的蓝牙设备
android:name="com.payegis.caesar.sdk.service.DynamicJobService"
android:permission="android.permission.BIND_JOB_SERVICE">
完整的AndroidManifest.xml配置文件可以参考设备指纹eclipse 的DEMO。
1.2.2 注意事项
混淆配置
如果您的APP进行了代码混淆,需要在混淆规则文件中进行如下配置:
-keep class com.payegis.caesar.sdk.** {*;}
如果报出 warning,在报出 warning 的包加入类似的语句:-dontwarn 包名。
关于Android6.0权限说明
Android6.0系统会有运行时权限动态检测,SDK需要进行运行检测的权限如下:
Manifest.permission.ACCESS_COARSE_LOCATION,
Manifest.permission.ACCESS_FINE_LOCATION,
Manifest.permission.WRITE_EXTERNAL_STORAGE,
Manifest.permission.READ_EXTERNAL_STORAGE,
Manifest.permission.READ_PHONE_STATE
Android系统默认会为targetSdkVersion小于23的应用授予了所申请的所有权限。所以如果您APP设置的targetSdkVersion低于23,在运行时也不会崩溃。如果您APP设置的targetSdkVersion大于或等于23,需要在初始化之前对相关权限进行检查和申请。
1、初始化之前需要对相关权限进行检查和申请,示例代码如下,也可参考DEMO中代码。
ArrayList perList &#61; new ArrayList<>();
if (ContextCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.READ_PHONE_STATE) !&#61; PackageManager.PERMISSION_GRANTED) {
perList.add(Manifest.permission.READ_PHONE_STATE);
}
if (ContextCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.READ_EXTERNAL_STORAGE) !&#61; PackageManager.PERMISSION_GRANTED) {
perList.add(Manifest.permission.READ_EXTERNAL_STORAGE);
}
if (ContextCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.WRITE_EXTERNAL_STORAGE) !&#61; PackageManager.PERMISSION_GRANTED) {
perList.add(Manifest.permission.WRITE_EXTERNAL_STORAGE);
}
if (ContextCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.ACCESS_FINE_LOCATION) !&#61; PackageManager.PERMISSION_GRANTED) {
perList.add(Manifest.permission.ACCESS_FINE_LOCATION);
}
if (ContextCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.ACCESS_COARSE_LOCATION) !&#61; PackageManager.PERMISSION_GRANTED) {
perList.add(Manifest.permission.ACCESS_COARSE_LOCATION);
}
if (perList.size() > 0) {
String[] perArr &#61; new String[perList.size()];
perList.toArray(perArr);
ActivityCompat.requestPermissions(this, perArr, PERMISSION_CODE);
}
2、在请求权限后&#xff0c;系统会弹出相应的Dialog提示用户授予权限&#xff0c;如下图所示&#xff1a;
3、用户选择允许或拒绝后&#xff0c;会回调onRequestPermissionsResult方法, 该方法类似于onActivityResult方法。
&#64;Override
public void onRequestPermissionsResult(int requestCode, &#64;NonNull String[] permissions, &#64;NonNull int[] grantResults) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
//your code
}
最低支持版本号
Android SDK最低支持的API Level为9&#xff0c;对应的Android系统版本为2.3。
1.2.3 示例程序
// 获取did sdk实例
sdk &#61; PayegisDidSdk.getInstance();
//设置AppId和AppKey 此处必须使用getApplicationContext()&#xff0c;该行代码放在您APP的Application类内中执行一次即可
sdk.init(getApplicationContext(), Const.APPID, Const.APPKEY);
//这个sessionId是由客户系统产生的&#xff0c;客户系统后台可以根据这个sessionId去查询did
sessionId &#61; RandomUtil.generateLowerString(10);
// 生成设备指纹
sdk.generateDeviceId(sessionId, new PayegisDidCallback() {
&#64;Override
public void actionSucceed(PayegisDidMessage paramPGSMessage) {
// 成功之后的回调&#xff0c;PayegisDidMessage对象中有相应状态码和消息描述
Log.d("payegisdid","init callback succeed: " &#43; paramPGSMessage.getStatus()&#43; " : " &#43;
paramPGSMessage.getMessage());
Toast.makeText(MainActivity.this, "初始化成功", Toast.LENGTH_LONG).show();
// APP接收到回调成功的消息之后再发起查询设备信息的请求
}
&#64;Override
public void actionFailed(PayegisDidMessage paramPGSMessage) {
// 失败之后的回调&#xff0c;PayegisDidMessage对象中有相应状态码和消息描述
Log.d("payegisdid", "init callback failed: " &#43; paramPGSMessage.getStatus()&#43; " : " &#43;
paramPGSMessage.getMessage());
Toast.makeText(MainActivity.this, "初始化失败", Toast.LENGTH_LONG).show();
}
});
1.2.4 应答状态码
状态码
含义
101
SDK正在初始化。
102
参数非法&#xff0c;请设置sessionId
103
参数非法&#xff0c;请设置正确的TAG值
104
数据格式错误
105
手机无法连接到网络
106
设备指纹服务器返回500或404
107
未知错误&#xff0c;请查看返回的错误
108
SocketTimeout
109
ConnectionTimeout
110
采集或上传发生异常
201
SDK加载失败
301
检测内容为空
302
字符检测失败
-1
签名校验不通过
-303
App_type不对
-305
参数无法解密
-306
sessionId为空或长度大于128
1.2.5 生成设备指纹信息
1、导入相关类
import com.payegis.caesar.sdk.PayegisDidSdk;
import com.payegis.caesar.sdk.PayegisDidCallback;
import com.payegis.caesar.sdk.PayegisDidMessage;
2、获取SDK单例对象
PayegisDidSdk sdk &#61; PayegisDidSdk.getInstance();
3、设置AppId和Appkey
调用init方法设置AppId和AppKey&#xff0c;如果是设备指纹本地化部署&#xff0c;还需要设置设备指纹服务端的url。该操作建议放在您APP的Application类内中执行。代码如下&#xff1a;
// 设置AppId和AppKey, 注意此处使用getApplicationContext()
PayegisDidSdk.getInstance().init(getApplicationContext(), Const.APPID, Const.APPKEY, Const.SERVERURL);
init方法参数说明&#xff1a;
参数名称
类型
是否必须
说明
context
Context
Y
Application上下文
AppId
String
Y
通付盾分配给商户的唯一应用ID号(由通付盾派发)
AppKey
String
Y
did服务颁发的AppKey
serverUrl
String
N
did服务地址(如果是设备指纹本地部署这项必须设置)
注&#xff1a;
开发接入所需要的AppId和AppKey请联系通付盾的技术支持咨询。
4、生成设备指纹
调用PayegisDidSdk的generateDeviceId生成设备指纹&#xff0c;如下所示&#xff1a;
//这个sessionId是由客户系统产生的&#xff0c;客户系统后台可以根据这个sessionId去查询did
sessionId &#61; "android" &#43; System.currentTimeMillis();
sdk.generateDeviceId(sessionId, new PayegisDidCallback() {
&#64;Override
public void actionFailed(PayegisDidMessage arg0) {
// TODO Auto-generated method stub
}
&#64;Override
public void actionSucceed(PayegisDidMessage arg0) {
// TODO Auto-generated method stub
}
});
参数说明&#xff1a;
参数名称
类型
说明
sessionId
String
自定义标识&#xff0c;用于后台查询did
payegisDidCallback
PayegisDidCallback
回调函数
生成设备指纹时实现PayegisDidCallback回调来执行初始化后的动作
public abstract interface PayegisDidCallback {
/**
* actionSucceed
*
* &#64;param paramPGSMessage
*/
public abstract void actionSucceed(PayegisDidMessage paramPGSMessage);
/**
* actionFailed
*
* &#64;param paramPGSMessage
*/
public abstract void actionFailed(PayegisDidMessage paramPGSMessage);
}
初始化成功sdk会调用 actionSucceed方法&#xff0c;初始化失败则调用 actionFailed方法。
初始化之后可以使用PayegisDidMessage的getStatus()来获取返回的状态码&#xff0c;以及使用getMessage()来获取返回的信息。状态码和信息请参考1.2.4 应答状态码。
5、查询设备信息
设备指纹的获取是在APP的服务器端进行&#xff0c;APP服务器端根据生成设备指纹时所用到的sessionid&#xff0c;到通付盾的设备指纹服务器端请求当前手机的设备指纹&#xff0c;建议接收到初始化成功的回调之后再发起查询设备信息的请求。
6、setBgTry方法
生成设备指纹时可以设置失败时重试的功能&#xff0c;如果由于网络原因导致上传失败&#xff0c;将会在网络状态发生改变时重新生成设备指纹并上传&#xff0c;尝试的总次数为5次&#xff0c;上传成功则不会再重试。使用方法为在生成设备指纹之前调用setBgTry方法&#xff0c;如&#xff1a;sdk.setBgTry(true);
参数说明&#xff1a;
参数名称
类型
说明
bgTry
boolean
是否重试
1.2.6 Webview设备指纹集成
如需在APP内以Webview形式集成设备指纹&#xff0c;需在webview loadURL方法之前调用设备指纹SDK如下方法。示例代码如下&#xff1a;
PayegisDidSdk sdk &#61; PayegisDidSdk.getInstance();
sdk.setWebview(webview);
webview.loadUrl("your html url");
注&#xff1a;
1、webview所引入的页面需添加设备指纹JS (详情可参见1.1 web)
2、该种集成方式使用webview内页面JS的sessionId查得设备指纹与Android SDK方式所得一致。
3、为提高安全性及数据时效性&#xff0c;建议每次webview loadURL前均进行调用。
1.2.7 事件上报
1、基本功能
SDK提供事件统计分析的功能&#xff0c;APP在特定的场景下调用事件上报的接口&#xff0c;可以将事件数据上传至服务器&#xff0c;后台统计和分析应用使用时长、使用频率、关注内容和行为等数据。
2、获取SDK单例对象
获取SDK单例对象和设置AppId和AppKey的详细流程可以参见1.2.5 生成设备指纹信息
该操作建议放在您APP的Application类内中执行一次即可。
// 初始化设备指纹sdk, 本地部署需要设置url参数
PayegisDidSdk.getInstance().init(this, Const.APPID, Const.APPKEY, Const.URL);
// 设置是否为调试模式
PayegisDidSdk.getInstance().setDebugMode(true);
// 批量上传策略下设置批量的临界值
PayegisDidSdk.getInstance().setBatchEventCount(30);
3、设置发送策略
设置发送策略接口&#xff1a;
/**
* 设置上传策略
* &#64;param policy
*/
public void setUploadPolicy(EnumUploadPolicy policy);
设置策略有如下枚举值:
取值
名称
说明
EnumUploadPolicy.STAT_POLICY_DEFAULT
默认策略
生成的数据在启动时和wifi状态下会全部上传至服务器
EnumUploadPolicy.STAT_POLICY_REALTIME
实时上传策略
生成的数据实时上传至服务器
EnumUploadPolicy.STAT_POLICY_BATCH
批量上传策略
生成的数据批量上传至服务器&#xff0c;批量的临界值可以通过setBatchEventCount方法设置
4、设置批量上传数量
设置批量上传数量接口&#xff1a;
/**
* 设置批量上传数量
*/
public void setBatchEventCount(int count);
上传策略为EnumUploadPolicy.STAT_POLICY_BATCH时通过这个方法可以设置批量的临界值&#xff0c;默认的临界数量为30。
5、设置调试模式
设置debug模式接口&#xff1a;
/**
* 是否打印debug日志
*/
public void setDebugMode(boolean debugMode);
在debug模式下&#xff0c;会有log输出&#xff0c;方便调试&#xff0c;默认是false&#xff0c;日志的tag为PayegisLog
6、账号统计
账号统计接口&#xff1a;
/**
* 统计账号
* &#64;param account
* &#64;param accountType
*/
public void setAccount(String account, EnumAccount accountType);
参数说明&#xff1a;
参数名称
类型
是否必须
说明
account
String
Y
账号名
accountType
EnumAccount
Y
账号类型
账号类型有如下枚举值:
EnumAccount.OWN_ACC 自有账号
EnumAccount.OTH_ACC 第三方账号
7、页面统计
页面统计接口(根据当前activity对象)&#xff1a;
/**
* 页面开始
* &#64;param context
*/
public void trackPageViewBegin(Context context);
/**
* 页面结束
* &#64;param context
*/
public void trackPageViewEnd(Context context);
参数说明&#xff1a;
参数名称
类型
是否必须
说明
context
Context
Y
Activity对象
页面统计接口(根据自定义名称)&#xff1a;
/**
* 页面开始
* &#64;param pageName
*/
public void trackPageViewBegin(String pageName);
/**
* 页面结束
* &#64;param pageName
*/
public void trackPageViewEnd(String pageName);
参数说明&#xff1a;
参数名称
类型
是否必须
说明
pageName
String
Y
页面名称
trackPageViewBegin和trackPageViewEnd必须成对出现&#xff0c;建议分别放在Activity的生命周期方法onResume和onPause中。
示例&#xff1a;统计微信朋友圈单次浏览的时间&#xff0c;可以在朋友圈的页面中加入以下代码&#xff1a;
// onResume()方法中添加
PayegisDidSdk.getInstance().trackPageViewBegin(this);
...
// onPause()方法中添加
PayegisDidSdk.getInstance().trackPageViewEnd(this);
8、基本事件统计
基本事件统计接口&#xff1a;
/**
* 统计自定义事件次数
* &#64;param eventId
* &#64;param params
*/
public void trackCustomEvent(String eventId, Map params);
参数说明&#xff1a;
参数名称
类型
是否必须
说明
eventId
String
Y
事件名称
params
HashMap
N
事件参数
示例&#xff1a;统计微信图片保存的次数&#xff0c;可以图片保存的函数中加入以下代码&#xff1a;
PayegisDidSdk.getInstance().trackCustomEvent("save", "image name");
9、时长事件统计
时长事件统计接口&#xff1a;
/**
* 统计时长事件开始
* &#64;param eventId
* &#64;param params
*/
public void trackCustomEventBegin(String eventId, Map params);
/**
* 统计时长事件结束
* &#64;param eventId
* &#64;param params
*/
public void trackCustomEventEnd(String eventId, Map params);
参数说明&#xff1a;
参数名称
类型
是否必须
说明
eventId
String
Y
事件名称
params
HashMap
N
事件参数
trackCustomEventBegin和trackCustomEventEnd必须成对出现&#xff0c;且两次参数必须一致。
示例&#xff1a;统计某个视频观看的时长&#xff0c;可以调用如下方法&#xff1a;
Map params&#61; new HashMap();
params.put("movie_id" , "5241" );
params.put("movie_name" , "kingkong" );
// 视频播放开始时调用
PayegisDidSdk.getInstance().trackCustomEventBegin("movie", params);
...
// 视频播放结束时调用
PayegisDidSdk.getInstance().trackCustomEventEnd("movie", params);
10、自定义事件统计
基本事件统计接口&#xff1a;
/**
* 统计自定时长事件
* &#64;param time
* &#64;param eventId
* &#64;param params
*/
public void trackCustomKeyValueEventDuration(long time, String eventId, Map params);
参数说明&#xff1a;
参数名称
类型
是否必须
说明
time
long
Y
时长
eventId
String
Y
事件名称
params
HashMap
N
事件参数
示例&#xff1a;跟时长事件统计类似&#xff0c;统计某个视频观看的时长&#xff0c;也可以调用如下方法&#xff1a;
// APP内计算出视频观看总的时间
long time&#61;24000;
Map params&#61; new HashMap();
params.put("movie_id" , "5241" );
params.put("movie_name" , "kingkong" );
// 视频播放结束时调用
PayegisDidSdk.getInstance().trackCustomKeyValueEventDuration(time, "movie", params);
1.2.8 内容过滤
SDK提供文本内容反垃圾检测的接口&#xff0c;调用如下&#xff1a;
// 检测内容
String comment &#61; mComment.getEditableText().toString();
mPayegisSdk.textFilter(comment, new PayegisDidCallback() {
&#64;Override
public void actionSucceed(PayegisDidMessage payegisDidMessage) {
Toast.makeText(getApplicationContext(), "Success!", Toast.LENGTH_SHORT).show();
}
&#64;Override
public void actionFailed(PayegisDidMessage payegisDidMessage) {
Toast.makeText(getApplicationContext(), "失败! status:"&#43; payegisDidMessage.getStatus() &#43; ", message:" &#43; payegisDidMessage.getMessage(), Toast.LENGTH_SHORT).show();
}
});
参数说明&#xff1a;
参数名称
类型
说明
comment
String
检测内容
payegisDidCallback
PayegisDidCallback
回调函数
检测成功会调用 actionSucceed方法&#xff0c;检测失败则调用 actionFailed方法。
调用之后可以使用PayegisDidMessage的getStatus()来获取返回的状态码&#xff0c;以及使用getMessage()来获取返回的信息。状态码和信息请参考1.2.4 应答状态码。