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,将TapDB_iOS.framework导入到Xcode工程中。

2.3.引入依赖的框架

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

框架或库 用途
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.获取初始化参数

调用init初始化后,可以调用一下接口获取初始化参数。

/**
 * 目前TapDB SDK仅支持单实例模式,如果多次调用onStart方法,只有最初传入的appid生效。调用该函数可以获取生效的信息
 * 返回值:包含appId和channel的NSDictionary,对应的value均可能为nil
 */
+ (NSDictionary *)getStartInfo;

3.3.记录一个玩家

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

+ (void)setUser:(NSString *)userId;
+ (void)setName:(NSString *)name;
字段 可为空 说明
userId 玩家ID(注意是平台用户ID,不是游戏角色ID),不同玩家要是唯一的,不同用户平台可能存在相同的用户ID,需要想办法做区分
userName 玩家名称

3.4.玩家等级

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

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

3.5.玩家区服

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

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

3.6.充值

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

充值成功时调用。

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

+ (void)onChargeSuccess:(NSString *)orderId product:(NSString *)product amount:(NSInteger)amount currencyType:(NSString *)currencyType payment:(NSString *)payment;
字段 可为空 说明
orderId 订单ID
product 产品名称
amount 充值金额(单位分,即无论什么币种,都需要乘以100)
currencyType 货币类型,参考:人民币 CNY,美元 USD;欧元 EUR
payment 支付方式,如:支付宝
字段 可为空 说明
orderId 订单ID,与之前调用的充值请求传递的ID对应

3.7.自定义事件

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

需要发送自定义事件时调用,自定义事件的eventCode和properties属性都必须在控制后台预先配置,等待1分钟左右的生效时间后,才可以使用SDK进行发送

+ (void)onEvent:(NSString *)eventCode properties:(NSDictionary *)properties;
字段 可为空 说明
eventCode 事件code,需要在控制后台预先配置
properties 事件属性,具体字段需要在控制后台预先配置

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认为发送成功,否则认为失败