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 synchronized static Map<String, String> getStartInfo()

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.自定义事件

自定义事件正在测试中,如需开通,请联系用户支持QQ:3485772949

推送自定义事件。需要在控制台预先进行配置。

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.收集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类进行混淆,或者其它会修改到类名和方法名的操作