1.简介

1.1.适用范围

TapDB提供一套SDK,游戏开发者可以将其集成到游戏中,系统会收集玩家数据,并进行分析,最终形成数据报表,帮助游戏开发者分析玩家行为并优化游戏。

目前SDK适用于iOS 5.0及以上的系统,支持armv7/armv7s/arm64架构。

1.2.名词解释

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

2.接入方式

2.1.申请应用

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

2.2.向Xcode工程中导入SDK

在TapDB网站上下载最新的SDK,其中包含一个头文件TyrantdbGameTracker.h和一个静态链接库文件libTyrantdbGameTracker.a。将两个文件导入到Xcode工程中,并确保所有需要用到SDK的Target都链接到静态库文件。

2.3.引入依赖的框架

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

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

2.4.调用统计接口

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

3.接口说明

头文件中定义了一个TyrantdbGameTracker类和TGTUserType/TGTUserSex两个枚举类型。TyrantdbGameTracker包含的都是静态方法,直接用类名调用即可。TGTUserType表示玩家类型,TGTUserSex表示玩家性别。

3.1.初始化

初始化统计系统SDK,调用这个接口是使用其它接口的先决条件,需要尽早调用。一般建议在AppDelegate的application:didFinishLaunchingWithOptions:中调用。

+ (void)onStart:(NSString *)appId channel:(NSString *)channel version:(NSString *)version;
字段 可为空 说明
appId 注册游戏时获得的APP ID
channel 分包渠道,1.2.名词解释中有介绍
version 游戏版本,为空时,自动获取游戏安装包的版本(Xcode配置中的Version)

3.2.记录一个玩家

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

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

3.3.玩家等级

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

+ (void)setLevel:(NSInteger)level;
字段 可为空 说明
level 玩家等级

3.4.玩家区服

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

+ (void)setServer:(NSString *)server;
字段 可为空 说明
server 玩家服务器

3.5.发起充值请求

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

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

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

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

3.6.充值成功

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

+ (void)onChargeSuccess:(NSString *)orderId;
字段 可为空 说明
orderId 订单ID,与之前调用的充值请求传递的ID对应

3.7.充值失败

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

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

3.8.仅充值成功

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

+ (void)onChargeOnlySuccess:(NSString *)orderId product:(NSString *)product amount:(NSInteger)amount currencyType:(NSString *)currencyType virtualCurrencyAmount:(NSInteger)virtualCurrencyAmount payment:(NSString *)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认为发送成功,否则认为失败