1.简介
1.1.适用范围
TapDB提供一套SDK,游戏开发者可以将其集成到游戏中。系统会收集用户数据,并进行分析,最终形成数据报表,帮助游戏开发者分析用户行为并优化游戏。
目前SDK适用于Android 4.0及以上的系统。
1.2.名词解释
名词 | 含义 |
---|---|
设备 | 安装了游戏的设备 |
分包渠道 | 标识游戏安装包的渠道,需要在代码中设置,可作为控制后台的过滤条件 |
用户 | 对应一个用户账户,需要一个唯一的标识符 |
付费 | 用户使用真实货币换取游戏虚拟币或游戏道具 |
2.使用方法
2.1.申请应用
在TapDB控制台中注册一个游戏,获得游戏对应的APP ID。这是一个长度为16的字符串。iOS和Android可共用一个APP ID。
2.2.向工程中导入SDK
在TapDB网站上下载最新的SDK,其中包含一个库文件libTapDB.jar。将该库文件加入到项目依赖库中。
2.3.添加需要的权限
为工程中的AndroidManifest.xml添加下列权限。
权限 | 是否必须 | 用途 |
---|---|---|
android.permission.INTERNET | 是 | 使用网络的权限 |
android.permission.ACCESS_NETWORK_STATE | 是 | 获取手机网络连接状态 |
2.4.调用推送接口
在需要调用推送接口的代码中引入类com.tapdb.sdk.TapDB,其中包含的都是静态方法。按照后面的接口介绍调用接口。
3.接口说明
3.1.初始化
初始化TapDB SDK。调用这个接口是使用其它接口的先决条件,需要尽早调用。一般建议在MainActivity的OnCreate中调用。如果多次调用,只有第一次调用有效。
public static void init(Context context, String appId, String channel, String gameVersion)
字段 | 可为空 | 说明 |
---|---|---|
context | 否 | 当前应用的Context对象。一般使用MainActivity对象 |
appId | 否 | 在控制台注册得到到的APP ID |
channel | 是 | 长度大于0并小于等于256。分包渠道。1.2.名词解释中有介绍 |
gameVersion | 是 | 长度大于0并小于等于256。游戏版本。为空时,自动获取游戏安装包的版本(AndroidManifest.xml中的versionName) |
3.2.获取初始化参数
调用init初始化后,可以调用一下接口获取初始化参数。
/**
* 获取init调用时的appId和channel参数
* @return 包含appId和channel的Map,值可能为null
*/
public static void init(Context context, String appId, String channel, String gameVersion)
3.3.记录一个用户
记录一个用户。当用户登陆时调用。
public static void setUser(String userId)
字段 | 可为空 | 说明 |
---|---|---|
userId | 否 | 长度大于0并小于等于256。只能包含数字、大小写字母、下划线(_)、横线(-),用户ID。不同用户需要保证ID的唯一性 |
3.4.用户名称
设置用户名。
public static void setName(String name)
字段 | 可为空 | 说明 |
---|---|---|
name | 否 | 长度大于0并小于等于256。用户名 |
3.5.用户等级
设置用户等级。用户登录或升级时调用。
public static void setLevel(int level)
字段 | 可为空 | 说明 |
---|---|---|
level | 否 | 大于等于0。用户等级 |
3.6.用户所在服务器
设置用户所在服务器。用户登陆或切换服务器时调用。
public static void setServer(String server)
字段 | 可为空 | 说明 |
---|---|---|
server | 否 | 长度大于0并小于等于256。用户所在服务器 |
3.7.充值
充值成功时调用。SDK推送和4.1中描述的服务端推送方法只能选择其中一种。建议优先选择服务端推送方式,以保证数据的准确性。
public static void onCharge(String orderId, String product, long amount, String currencyType, String payment)
字段 | 可为空 | 说明 |
---|---|---|
orderId | 是 | 长度大于0并小于等于256。订单ID。传递订单ID可进行排重,防止计算多次 |
product | 是 | 长度大于0并小于等于256。商品名称 |
amount | 否 | 大于0并小于等于100000000000。充值金额。单位分,即无论什么币种,都需要乘以100 |
currencyType | 是 | 货币类型。国际通行三字母表示法,为空时默认CNY。参考:人民币 CNY,美元 USD;欧元 EUR |
payment | 是 | 长度大于0并小于等于256。充值渠道 |
常见货币类型的格式参考汇率表
3.8.自定义事件
推送自定义事件。需要在控制台预先进行配置。
public static void onEvent(String eventCode, JSONObject properties)
字段 | 可为空 | 说明 |
---|---|---|
eventCode | 否 | 在控制台中配置得到的事件编码 |
properties | 是 | 事件属性。需要和控制台的配置匹配。值需要是长度大于0并小于等于256的字符串或绝对值小于1E11的浮点数 |
3.9.跟踪游戏的启停
跟踪用户游戏次数和游戏时长。需要给游戏中每个Activity的onResume和onStop中添加对应的调用。如果多个Activity继承同一个父类,只需要在父类中添加调用即可。比如onResume方法,直接在Activity的onResume方法的最后添加TapDB.onResume(this)即可。
public static void onResume(Activity activity)
public static void onStop(Activity activity)
字段 | 可为空 | 说明 |
---|---|---|
activity | 否 | 当前Activity对象。一般传递"this" |
4.服务端推送接口
4.1.充值推送接口
由于SDK推送可能会不太准确,这里提供服务端充值推送方法。需要忽略掉SDK中的相关充值推送接口。
接口:https://e.tapdb.net/event
内容(注意后面还需要处理一下):
{
"module": "GameAnalysis", // 固定参数
"ip": "8.8.8.8", // 可选。充值用户的IP
"name": "charge", // 固定参数
"index": "APPID", // 必需。注意APPID需要被替换成TapDB的appid
"identify": "userId", // 必需。用户ID。必须和SDK的setUser接口传递的userId一样,并且该用户已经通过SDK接口进行过推送
"properties": {
"order_id": "100000", // 可选。长度大于0并小于等于256。订单ID。传递订单ID可进行排重,防止计算多次
"amount": 100, // 必需。大于0并小于等于100000000000。充值金额。单位分,即无论什么币种,都需要乘以100
"currency_type": "CNY", // 可选。货币类型。国际通行三字母表示法,为空时默认CNY。参考:人民币 CNY,美元 USD;欧元 EUR
"product": "item1", // 可选。长度大于0并小于等于256。商品名称
"payment": "alipay" // 可选。长度大于0并小于等于256。充值渠道
}
}
假如游戏的appid为abcd1234。构建出json字符串后,去掉空格和换行符,然后再进行一次urlencode。再把结果作为POST数据推送
先替换换行符和空格,变成:
{"module":"GameAnalysis","name":"charge","index":"abcd1234","identify":"user_id","properties":{"order_id":"100000","amount":100,"virtual_currency_amount":100,"currency_type":"CNY","product":"item1","payment":"alipay"}}
然后urlencode,变成如下形式。某些版本的urlencode可能会把':'和','进行编码,不会影响实际使用。
%7B%22module%22:%22GameAnalysis%22,%22name%22:%22charge%22,%22index%22:%22abcd1234%22,%22identify%22:%22user_id%22,%22properties%22:%7B%22order_id%22:%22100000%22,%22amount%22:100,%22virtual_currency_amount%22:100,%22currency_type%22:%22CNY%22,%22product%22:%22item1%22,%22payment%22:%22alipay%22%7D%7D
成功判断:返回的HTTP Code为200时认为发送成功,否则认为失败
常见货币类型的格式参考汇率表
4.2.在线数据推送接口
由于SDK无法推送准确的在线数据,这里提供服务端在线数据推送接口。游戏服务端可以每隔5分钟自行统计在线人数,通过接口推送到TapDB。TapDB进行数据汇总展现。
接口:https://se.tapdb.net/tapdb/online
方法:POST
格式:json
必需头信息:Content-Type: application/json
请求内容:
参数名 | 参数类型 | 参数说明 |
---|---|---|
appid | string | 游戏的APP ID |
onlines | array | 多条在线数据(最多100条) |
其中onlines数组的结构为
参数名 | 参数类型 | 参数说明 |
---|---|---|
server | string | 服务器。TapDB对同一服务器每一个自然5分钟仅接受一次数据 |
online | int | 在线人数 |
timestamp | long | 当前统计数据的时间戳(秒)。TapDB会按照自然5分钟进行数据对齐 |
示例:
{
"appid":"gkjasd13bbsa1sdk",
"onlines":[{
"server":"s1",
"online":123,
"timestamp":1489739590
},{
"server":"s2",
"online":188,
"timestamp":1489739560
}]
}
成功判断:返回的HTTP Code为200时认为发送成功,否则认为失败
5.收集OAID
TapDB在2.1.2中新增了OAID获取功能,需要将下载到的SDK目录中OAID文件夹下的 milt_mdid_1.0.10.aar 放⼊入项⽬目 libs⽬目录下,并且将 supplierconfig.json 放⼊入assets ⽂文件夹内,具体路路径 app/src/main/ assets , 配置⽂文件内容⽆无需修改。
6.收集IMEI或MEID
部分广告渠道(如:“广点通”)仅支持使用IMEI进行广告渠道匹配。而获取IMEI需要向用户申请更多的权限,涉及用户隐私,并可能会导致Google Play无法上架。如果确实需要进行这些广告渠道的匹配,请按照下列步骤操作。
1.将SDK中的libTapDB-IMEI.jar添加到项目依赖库中
2.增加Android Support V4库的引用,版本必须不低于23.0.0。如果项目本身不依赖Android Support V4库,可以直接使用SDK中的android-support-v4.jar
3.在AndroidManifest.xml中增加android.permission.READ_PHONE_STATE权限
4.在调用SDK的初始化init接口之前,向用户申请获得android.permission.READ_PHONE_STATE的授权
5.不能对com.tapdb.util.deprecated.IMEI类进行混淆,或者其它会修改到类名和方法名的操作