1.简介

1.1.适用范围

封装了 TapDB 的 SDK,适用于 Cocos2d-x 开发的游戏,同时支持 iOS 和 Android 平台。

1.2.名词解释

名词 含义
玩家 对应一个玩家账户,需要一个唯一的标识符。玩家是统计系统的数据统计基本单位
设备 安装了对应游戏的设备
付费 玩家使用真实货币换取游戏虚拟币或游戏道具
分包渠道 标识游戏安装包渠道来源,需要在代码中设置

2.接入方式

2.1.申请应用

在 TapDB 控制台中注册一个游戏,获得游戏对应的 APP ID,这是一个 16 位的字符串,iOS 和 Android 可共用一个 APP ID。

2.2.向工程中导入 SDK

在 TapDB 网站上下载最新的 SDK,其中包含一个 TapDB_sdk.zip 文件,解压得到 3 个文件夹,include 文件夹里面是头文件,iOS 和 Android 文件夹里面是对应平台的实现代码和库文件。另外,在 Android.mk 里面添加对 TapDB.cpp 的引用。

2.3.添加 Android 支持库

添加 Android v4 支持库到项目中,Android v4 支持库的版本必须不低于 23.0.0,否则可能导致闪退。

如果使用 gradle 依赖安装版本高于 24.2.0 版本的 v4 支持库,可以仅安装 support-compat 模块,参见文档: https://developer.android.com/topic/libraries/support-library/setup.htmlhttps://developer.android.com/topic/libraries/support-library/features.html

如果不方便使用 gradle 进行自动化依赖安装,之前也没有使用到 v4 支持库,可以使用此处提供的 support-compat 模块的 jar 文件, https://static.tapdb.net/web/res/file/upload/2017/0926/android-support-v4.jar

2.4.Android 添加需要的权限

需要为工程中的 AndroidManifest.xml 添加下列权限

权限 是否必须 用途
android.permission.INTERNET 必选 使用网络的权限
android.permission.ACCESS_NETWORK_STATE 必选 获取手机网络连接状态
android.permission.WRITE_EXTERNAL_STORAGE 可选 使用 SD 卡辅助存储设备标识等信息,若不具备此权限,有一部分设备无法进行很好的设备跟踪

2.5.iOS 引入依赖的框架

需要为 Xcode 工程引入下列依赖的框架或库

框架或库 用途
AdSupport.framework 用来获取设备广告标识,跟踪设备
Security.framework 用来进行更好的持久化存储

2.6.调用统计接口

在需要调用统计接口的代码中引入 TapDB.h,并按照后面的接口介绍调用统计接口。

3.接口说明

TapDB.h 包含了类 TapDB,还定义了 TGTUserType/TGTUserSex 两个枚举类型。TapDB 包含的都是静态方法,直接用类名调用即可。TGTUserType 表示玩家类型,TGTUserSex 表示玩家性别。

3.1.初始化

初始化统计系统 SDK,调用这个接口是使用其它接口的先决条件,需要尽早调用。init 方法会初始化 SDK,在此之前不可以调用 SDK 的其他方法。

Android 需要引入 libTyrantdbGameTracker.jar,并且在主 Activity 的 onCreate() 中调用 TyrantdbGameTracker.init(Activity activity, String appId, String channelId, String version, bool requestPermission),最后一个参数固定传递 false。

public static void onStart(string appId, string channel, string version)
字段 可为空 说明
appId 注册游戏时获得的 APP ID
channel 分包渠道,1.2.名词解释中有介绍
version 游戏版本,为空时,自动获取游戏安装包的版本

3.2.跟踪游戏的启停(只适用于 Android)

跟踪玩家游戏次数和游戏时长。需要给游戏中每个 Activity 的 onResume 和 onStop 中添加对应的调用。如:在 MainActivity 里面调用 TyrantdbGameTracker.onStop (this); 即可。

public static void onResume(Context ctx)
public static void onStop(Context ctx)

3.3.记录一个玩家

记录一个玩家(注意是平台用户,不是游戏角色),当玩家登陆时调用,如果是试玩用户,userId 由游戏自己生成,但需要保证唯一性。

public static void setUser(const char *userId, TGTUserType userType, TGTUserSex userSex,
 int userAge, const char *userName)
字段 可为空 说明
userId 玩家 ID(注意是平台用户 ID,不是游戏角色 ID),不同玩家要是唯一的,不同用户平台可能存在相同的用户 ID,需要想办法做区分
userType 玩家类型,见类型详细定义
userSex 玩家性别,见类型详细定义
userAge 玩家年龄,无法获知玩家年龄直接传递 0
userName 玩家名称

3.4.玩家等级

设置玩家等级,玩家登陆时或升级时调用。

public static void setLevel(int level)
字段 可为空 说明
level 玩家等级

3.5.玩家区服

设置玩家区服,玩家登陆时或更换区服时调用。

public static void setServer(const char *server)
字段 可为空 说明
server 玩家服务器

3.6.发起充值请求

(推荐使用服务端充值统计接口)

当玩家发起充值请求时调用。

提醒:由于客户端行为,不可避免会有投机者尝试破解充值; 如果没有通过服务器校验,一定会造成数据不准确,强烈建议使用服务器接口进行充值数据回调。 (4.1.充值统计接口)

public static void onChargeRequest(const char *orderId, const char *product,
 long amount, const char * currencyType, long virtualCurrencyAmount, const char *payment)
字段 可为空 说明
orderId 订单 ID
product 产品名称
amount 充值金额(单位分,即无论什么币种,都需要乘以 100)
currencyType 货币类型,参考:人民币 CNY,美元 USD;欧元 EUR
virtualCurrencyAmount 充值获得的虚拟币
payment 支付方式,如:支付宝

3.7.充值成功

充值成功时调用,需要与充值请求成对调用

public static void onChargeSuccess(const char *orderId)
字段 可为空 说明
orderId 订单 ID,与之前调用的充值请求传递的 ID 对应

3.8.充值失败

充值失败时调用,需要与充值请求成对调用

public static void onChargeFail(const char *orderId, const char *reason)
字段 可为空 说明
orderId 订单 ID,与之前调用的充值请求传递的 ID 对应
reason 失败原因

3.9.仅充值成功

当客户端无法跟踪充值请求发起,只能跟踪到充值成功的事件时,调用该接口记录充值信息

public static void onChargeOnlySuccess(const char *orderId, const char *product,
long amount, const char *currencyType, long virtualCurrencyAmount, const char *payment)
字段 可为空 说明
orderId 订单 ID
product 产品名称
amount 充值金额(单位分,即无论什么币种,都需要乘以 100)
currencyType 货币类型,参考:人民币 CNY,美元 USD;欧元 EUR
virtualCurrencyAmount 充值获得的虚拟币
payment 支付方式,如:支付宝

4.服务端统计接口

4.1.充值统计接口

由于客户端接入充值统计可能会不太准确,这里提供服务端充值统计方法,需要忽略掉 SDK 中的相关充值统计接口

接口:https://e.tapdb.net/event
内容(注意后面还需要处理一下):
{
    "module": "GameAnalysis", //固定
    "ip": "8.8.8.8", //充值用户的 IP,可选
    "name": "charge", //固定
    "index": "APPID", //APPID 注意替换成 TapDB 的 appid
    "identify": "user_id", //user_id,必须和客户端的 setUser 接口传递的 user_id 一样,并且该用户已经通过 SDK 接口进行过统计
    "properties": {
        "order_id": "100000", //order_id,可选,若传递此参数,需要保证 order_id 唯一,重复订单不计入统计
        "amount": 100, //充值金额(必须是整数,单位分,即无论什么币种,都需要乘以 100),必传
        "virtual_currency_amount": 100, //获赠虚拟币数量,必传,可为 0
        "currency_type": "CNY", //货币类型,可选,不传或者不是正确的货币类型,统一处理成人民币分
        "product": "item1", //充值包名称,可选
        "payment": "alipay" //充值途径,可选
    }
}

假如游戏的 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 TapDB 的 appid
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 认为发送成功,否则认为失败