此文档是统计日志sdk接入说明。
在游戏及应用开发商需要接入掌趣SDK时,根据该日志向掌趣统计后台发送游戏内统计日志。
接入掌趣的游戏及应用开发者,包括客户端及服务器端工程师。
玩家:玩家指下载安装和运行游戏及应用的用户,在统计时,玩家这个词本身又包含三层意义,即设备、账户、角色;
设备:指玩家用于安装运行游戏和应用的手机,平板,电脑等硬件设施;
账户:指玩家为了登录游戏和应用而注册的通行证,账户等信息;
角色:指玩家为了进入游戏创建的游戏内角色信息。
用户行为:玩家在游戏和应用内每一个值得被记录的动作都可以称为一次用户行为或者事件或者动作,我们在统计sdk中将玩家用户行为分为基础事件和游戏内事件两大类;
基础事件:包括启动和初始化应用,注册和登录账户,注册和登录角色,客户端心跳等;
游戏内事件:包括玩家的充值,虚拟物品获得与使用,任务、关卡、副本、交互等等。
日志:当玩家在游戏中发生了一次应该被记录的事件,而且这次事件通过统计sdk成功记录,则产生了一条记录对应事件的日志,每个日志都包含多个不同的字段,用于描述事件的不同角度的信息。掌趣统计后台通过对日志的搜集、分析和计算,算出各种事件的统计数据,并将其在掌趣BI后台中展示出来。
维度:在一条日志里,会对一个事件的不同角度的信息进行记录,例如新闻六要素,who,when,where,what,why和how,六要素其实就是同一事件在六个维度上坐标值。在掌趣统计sdk中,会有时间、产品、联运、推广渠道、游戏逻辑服等维度信息来标识一个事件。一些维度信息在掌趣sdk跟应用打包时就已经固化在客户端的配置文件中了,另外一些维度信息则需要客户端开发人员在事件发生时实时获取和记录日志。因此日志接口的每一个参数都是必要和有意义的,请接入时务必确保维度信息的完整性和正确性。
日志接入流程大致分为三个步骤:
1. 客户端日志接入开发负责人根据日志接入流程文档,调用日志接口,完成几个基础日志的记录;
2.掌趣科技数据中心对客户端接入的日志进行格式和字段内容检查;
3.客户端日志接入开发负责人与掌趣技术人员通过日志接入测试用例后,日志接入工作正式完成。
SDK日志接口,用于采集客户端的诸如玩家注册,玩家登录,玩家充值,玩家虚拟物品变更,玩家属性变更等用户行为,为产品运营,推广营销等工作提供数据支持。
在调用日志接口时,客户端需要为日志接口提供日志ID,日志关键字,日志内容三个参数,其中,日志内容(val)是一个json格式的字符串,里面详细描述了该次事件的具体信息。例如,一个玩家充值日志,他的几个参数大概是这样的:
从示例中可见,
日志的id为8,
本次充值的订单号为0162014101420092117000(由开发者自行决定订单号作为订单唯一标识)
本次充值的支付渠道为支付宝
本次充值的货币类型为1 (人民币,见附2.1货币规范)
本次充值的实际支付金额为100元(单位为分,所以接口中的参数值是10000)
本次充值的虚拟币类型为钻石
本次充值的虚拟币发放金额为1000
除了货币类型是附2.1货币规范指定之外,其余信息皆为该游戏的产品人员和开发人员自行设定,其余一些虚拟币类型和商品ID的代码由游戏开发和运营人员自行指定。
当传入中文字符串时,务必确保该中文字符串使用的是utf8编码。例如,商品名称,任务名称,副本场景名称等。
由的产品人员和开发人员自行设定的字段信息,也必须由相应的负责人确保内容的一致性。 例如同一个逻辑服下,如果在用户登录注册时调用日志接口传递的逻辑服标识是1001,那么在调用计费中心的充值计费接口时逻辑服标识也应该是同样的1001,而不应该是其他的值。同样的,如果A用户在购买一个极品武器时记录的物品id是001weapon,那么另外一个用户在拍卖同样一个极品武器时物品id也应该是001weapon。
系统库添加
请于Link Binary With Libraries处添加以下库文件
请在build settings处做一下设置
iOS Deployment Target最低为iOS 5.0
其他请参照DEMO
功能说明
1、初始化统计SDK,以便正常使用各项功能
2、获取初始化数据。
接口定义
参数说明
参数名称 |
重要性 |
类型 |
说明 |
gameVer |
必填 |
string |
游戏版本号 |
gameResVer |
可选 |
string |
游戏资源版本号,如游戏无此概念则可以传"" |
接口示例
功能说明
1、登录成功后调用,传入用户登录类型(用户注册和用户登录)、用户ID、用户名;
2、这个接口会根据传入的用户登录类型自动发送账户注册及账户登录日志。
接口定义
参数说明
参数名称 |
重要性 |
类型 |
说明 |
type |
必填 |
OPGameType |
kGameRegister表示用户注册, kGameLogin 表示用户登录 |
userId |
必填 |
string |
用户ID,登录或注册成功后,返回的用户ID |
userName |
必填 |
string |
用户名 |
接口示例
功能说明
当游戏角色注册(登录)成功时设置游戏角色注册(登录)信息。在调用此接口后SDK会自动生成并发送相应的角色注册(登录)日志
接口定义
参数说明
参数名称 |
重要性 |
类型 |
说明 |
opGameInfo |
必须 |
OPGameInfo |
设置游戏账号信息 |
opGameType |
必须 |
OPGameType |
用户标识游戏角色注册登录状态 注册:kGameRegister 登录:kGameLogin |
OPGameInfo参数说明
参数名称 |
重要性 |
类型 |
说明 |
mGame_RoleName |
必须 |
std::string |
游戏角色名称 |
mGame_RoleId |
必须 |
std::string |
游戏角色 id |
mGame_ServerId |
必须 |
std::string |
游戏服务器id |
mGame_RoleLevel |
必须 |
std::string |
游戏角色等级 |
mGame_RoleVipLevel |
必须 |
std::string |
游戏角色vip等级 |
接口示例
功能说明
打开后能在xcode下方工具栏看到统计SDK客户端相关日志输出,以便游戏接入SDK的时
候进行调试,出正式游戏包时请务必关闭日志输出。
接口定义
参数说明
参数名称 |
重要性 |
类型 |
说明 |
showLogs |
必须 |
bool |
是否打开日志输出 |
功能说明
收集游戏玩家行为信息,用于统计分析玩家行为。
接口定义
参数说明
参数名称 |
重要性 |
类型 |
说明 |
logID |
必须 |
std::string |
日志ID |
logKey |
必须 |
std::string |
日志KEY |
logValJson |
必须 |
std::string |
日志内容,json格式 |
接口示例
logId和LogKey对应表
logId |
Logkey |
描述 |
8 |
role-credit |
玩家充值日志 |
9 |
role-item-update |
玩家虚拟物品变更 |
10 |
role-prop-update |
玩家属性变更 |
1001 |
role-task |
任务 |
1002 |
role-stage |
副本,场景 |
1003 |
role-act |
自定义事件 |
2001 |
role-interact |
自定义交互事件 |
日志logVal字段对照表
当用户已经启动游戏客户端,且通过发货通知接口收到发货通知并给用户成功发货时,需要记录一条对应的发货成功日志来跟踪玩家充值。
支付方式ID:如支付宝,神州付,财付通,微信支付等,由开发者自行指定,需要在同一个产品的所有订单中保持支付方式id的一致性
订单号:由开发者自行指定该笔充值的唯一标识
订单金额:即发货通知接口的订单金额
货币类型:玩家支付的是人民币还是美元或者欧元,见附2.1货币规范
商品ID:用于记录本次充值给用户发放了哪一个商品,商品id建议由英文字母或数字组成,以避免乱码等问题。
商品名称:商品名称建议为中文信息。
日志时间字段,sdk会根据调用日志接口时间自行填充。
用户id,角色名称,角色id等字段,sdk会根据角色登录时保存的信息自行填充。
LogId |
日志名称 |
LogKey |
字段名 |
字段类型 |
字段说明 |
备注 |
8 |
玩家充值日志 |
role-credit |
roleLevel |
Integer |
角色等级 |
必需 |
roleVipLevel |
Integer |
角色vip等级 |
必需 |
|||
payChannelId |
String |
支付方式 |
例如,91支付,UC支付等,非必需 |
|||
orderNo |
String |
订单号 |
必需 |
|||
currencyType |
String |
货币类型 |
(参照附2.1货币规范)必需 |
|||
currencyAmount |
Integer |
订单金额 |
单位:分,必需 |
|||
itemId |
String |
商品ID |
游戏中商品或者道具ID,必需 |
|||
itemName |
String |
商品名称 |
便于运营人员识别商品,一般传入中文,必需 |
|||
itemCount |
Integer |
商品个数 |
必需 |
日志格式示例:
该记录表示当前登录的角色马克.吐温充值100分人民币购买游戏内100钻石
当用户在游戏内,因为种种原因产生虚拟物品(含虚拟货币)的增加和消耗时,需要记录一条对应的虚拟物品变更日志。
变更类型:用于标识本次变更是新增了虚拟物品还是消耗了虚拟物品,新增记录1,消耗记录0。
自定义变更描述:用于标识用户因为什么原因变更虚拟物品(虚拟货币),如任务获得,怪物掉落,系统赠送,副本奖励,世界喊话,家族奉献,婚姻喜宴等等。
商品ID:用于记录用户本次是因为哪一个游戏内的商品引发的虚拟物品变更,例如购买游戏内的装备、经验、头衔、坐骑等。商品名称由游戏策划人员自行定义,比如 0001对应装备图纸,0002对应黄金翅膀,0003对应经验丹,0004对应体力等等。传入0001,0002,0003……这些ID即可
商品名称:用于记录用户本次是因为哪一个游戏内的商品引发的虚拟物品变更,例如购买游戏内的装备、经验、头衔、坐骑等。商品名称由游戏策划人员 自行定义,比如0001_装备图纸,0002_黄金翅膀,0003_经验丹,0004_体力等等。统计结果也会直接将日志中的商品名称展示出来,如果用户本次变更行为 与具体商品道具无关,则该字段置空即可。
商品个数:用于记录用户本次消费行为涉及多少个商品,如果用户本次消费行为与具体商品无关,则该字段置空即可。
需要注意的是,如果玩家的一次事件导致多种虚拟物品变更,比如完成一次史诗副本同时获得1000珍珠20000石币,则需要记录相应的两条虚拟物品变更日志。
LogId |
日志名称 |
LogKey |
字段名 |
字段类型 |
字段说明 |
备注 |
9 |
玩家虚拟物品变更日志 |
role-item-update |
roleLevel |
Integer |
角色等级 |
必需 |
roleVipLevel |
Integer |
角色vip等级 |
必需 |
|||
updateType |
String |
变更类型 |
1:新增 0:消耗 必需 |
|||
itemId |
String |
商品ID |
必需 |
|||
itemName |
String |
商品名称 |
便于运营人员识别商品,一般传入中文,必需 |
|||
itemCount |
Integer |
商品个数 |
必需 |
|||
custom |
String |
自定义 |
本次虚拟物品变更的其他相关信息,非必需 |
日志格式示例:
上面两条日志表示当前登录的角色马克.吐温为了购买id为玛格汉铁锤 的武器花了100钻石。
当用户的角色,发生一些属性上的变化时,记录相应的角色属性变更日志。例如等级提升,军衔提升,VIP等级提升,属性点重配,种族天赋变更等等。
属性标识:角色变更了哪种属性,其中等级标识为level,VIP等级标识为viplevel,其余属性标识由游戏产品和开发人员自行设定。
新属性值:角色完成属性变更之后,该属性的值变成了什么。
变更值:如果该属性值是一个数字,比如等级level,那么本次用户的等级变更了多少,例如购买大礼包level连升三级,则变更值为3。
LogId |
日志名称 |
LogKey |
字段名 |
字段类型 |
字段说明 |
备注 |
10 |
玩家属性变更日志 |
role-prop-update |
roleLevel |
Integer |
角色等级 |
必需 |
roleVipLevel |
Integer |
角色vip等级 |
必需 |
|||
propKey |
String |
属性标识 |
必需 |
|||
propValue |
String |
新属性值 |
必需 |
|||
rangeability |
String |
变更值 |
必需 |
|||
日志格式示例:
该记录表示当前角色马克.吐温连升了两级,目前等级为3。他的vip等级升了一级,目前vip等级为1
当运营人员需要对游戏内的任务完成情况,关卡完成情况进行记录时,即可记录一条游戏自定义事件。在记录日志之前,游戏运营人员有必要向掌趣科技统计后台提供一份任务,关卡,以及其他自定义事件的id和名称对照表,并在掌趣科技统计后台描述任务,关卡,道具之间的关系。
任务,副本关卡日志的格式均为stageId,stageName,detail三个字段,三个字段的值完全由游戏研发人员和运营人员自行指定,例如新手引导任务可以用 newbieguide标识stageId,也可以用task001或其他字符串标识来表示stageId,任务完成,既可以用 SUCC表示,也可以用complete表示,还可以根据任务的中断,放弃,失败等多种状况,为同一个任务记录多条日志。对于同一种事件结果,建议使用同样的detail内容来描述。尽量做到同一个detail的含义一致,同一个事件结果的detail一致。
需要注意的地方:
无论是任务,关卡还是其他自定义事件日志,taskId/stageId/actId字段都必须是相对于该日志的logId唯一,不能够与其他任务,关卡或道具的id字段重复。
尽管任务,副本/场景,以及游戏自定义事件三个日志的字段数量和格式相同,但是我们希望研发人员能够按照预设的不同logid和logkey分别记录这三类日志,这样一来,便于将相对重要的日志同其它日志区分出来,也便于我们对任务和场景副本日志采用预设的特定算法来进行统计运算。
我们要求用以下的默认字段来记录事件日志的detail,以便统计后台可以用默认的配置来对游戏自定义事件进行计算成功率,通过率等进一步指标。
如果列表中的detail无法满足游戏的日志记录要求,也允许各个游戏使用自己定义的detail来记录日志,实际上在下面的日志范例中也有一些detail字段灵活发挥的情况。
事件类型 |
detail |
含义 |
|
role-task |
accept |
接任务 |
|
fail |
任务失败 |
||
cancel |
放弃任务 |
||
succ |
达成任务条件 |
||
complete |
任务完成 |
||
role-stage |
begin |
场景开始 |
|
fail |
场景失败 |
||
cancel |
场景取消 |
||
end |
场景结束 |
||
role-act |
begin |
事件开始 |
|
fail |
事件失败 |
||
cancel |
事件取消 |
||
end |
事件结束 |
LogId |
日志名称 |
key |
字段名 |
字段类型 |
字段说明 |
1001 |
任务 |
role-task |
roleLevel |
Integer |
角色等级,必需 |
roleVipLevel |
Integer |
角色vip等级,必需 |
|||
taskId |
String |
任务编码,英文或数字,必需 |
|||
taskName |
String |
任务名称,最好传中文,必需 |
|||
detail |
String |
相关信息,全为英文,参考上面detail定义,必需 |
这两条日志表示,当前角色马克.吐温在17:11:30接受了新手流程任务1,在17:12:30完成了新手流程任务1.
LogId |
日志名称 |
key |
字段名 |
字段类型 |
字段说明 |
1002 |
副本场景日志 |
role-stage |
roleLevel |
Integer |
角色等级,必需 |
roleVipLevel |
Integer |
角色vip等级,必需 |
|||
stageId |
String |
副本场景标识,英文或数字,必需 |
|||
stageName |
String |
副本场景名称,最好传中文,必需 |
|||
detail |
String |
相关信息,全为英文,参考上面detail定义,必需 |
LogId |
日志名称 |
key |
字段名 |
字段类型 |
字段说明 |
1003 |
游戏自定义事件 |
role-act |
roleLevel |
Integer |
角色等级,必需 |
roleVipLevel |
Integer |
角色vip等级,必需 |
|||
actId |
String |
事件标识,英文或数字,必需 |
|||
actName |
String |
事件名称,最好传中文,必需 |
|||
detail |
String |
相关信息,全为英文,参考上面detail定义,必需 |
以上日志表示,当前角色马克吐温于2014-04-18 17:11:30 进入死亡矿井。
下面我们用一系列日志,来记录一个复杂的副本过程,以此作为游戏内自定义事件的开发样例
logkey |
事件 |
日志 |
role-task |
接受任务:迪菲亚兄弟会 |
time:2014-04-18 20:00:00
taskName:迪菲亚兄弟会 |
role-stage |
进入死亡矿井 |
time:2014-04-18 21:00:00
stageName:死亡矿井 |
role-act |
boos战格鲁巴托克开始 |
time:2014-04-18 21:05:00
actName:boos战格鲁巴托克 |
role-act |
boss战格鲁巴托克完成 |
time:2014-04-18 21:07:00
actName:boss战格鲁巴托克 |
role-act |
boos战格范克里夫开始 |
time:2014-04-18 21:20:00
actName:boos战格范克里夫 |
role-act |
boss战格范克里夫失败 |
time:2014-04-18 21:21:00
actName:boos战格范克里夫 |
role-act |
死亡 |
time:2014-04-18 21:21:00
actName:角色死亡 |
role-stage |
出死亡矿井 |
time:2014-04-18 21:21:20
stageName:死亡矿井 |
role-stage |
进入死亡矿井 |
time:2014-04-18 21:23:20
stageName:死亡矿井 |
role-act |
复活 |
time:2014-04-18 21:23:21 actName:复活 detail:relive |
role-act |
boos战格范克里夫开始 |
time:2014-04-18 21:25:00
actName:boos战格范克里夫 |
role-act |
boos战格范克里夫完成 |
time:2014-04-18 21:30:00
actName:boos战格范克里夫 |
role-task |
任务迪菲亚兄弟会达到完成条件 |
time:2014-04-18 21:30:00
taskName:迪菲亚兄弟会 |
role-stage |
出死亡矿井 |
time:2014-04-18 21:40:20
stageName:死亡矿井 |
role-task |
交任务:迪菲亚兄弟会 |
time:2014-04-18 21:45:00
taskName:迪菲亚兄弟会 |
从中,运营人员可以发现,当前角色马克.吐温进入死亡矿井后,顺利击败第一个boss,但是在挑战最终boss范克里夫时不幸阵亡,玩家没有气馁,复活之后重整旗鼓,终于击败范克里夫,打通了死亡矿井,完成了任务迪菲亚兄弟会。
游戏中除了角色与系统间发生的事件之外,还会有玩家之间的交互事件,这类事件使用交互事件日志来记录。
与游戏自定义事件相比,交互事件多了一个交互对象的概念,targetType字段用于描述本次交互
的对象是哪一类对象,0、系统交互,1、玩家之间互动,2、游戏自定义交互。
系统交互事件应该尽量使用游戏自定义事件来记录,除非交互对象较为重要需要额外记录。
targetCode用于描述当前玩家与具体哪一个对象进行了交互,当targetType为2时,targetCode必须为对方角色id,targetInfo必须为对方逻辑服标识。
LogId |
日志名称 |
key |
字段名 |
字段类型 |
字段说明 |
2001 |
交互行为 |
role-interact |
roleLevel |
Integer |
角色等级,必需 |
roleVipLevel |
Integer |
角色vip等级,必需 |
|||
interactId |
String |
自定义事件编码,数字或字母,必需 |
|||
interactName |
String |
自定义事件名称,建议写中文,必需 |
|||
targetType |
String |
目标类型,0:系统,1:玩家,2:自定义类型,必需 |
|||
targetCode |
String |
目标,若目标类型为玩家则为对方角色ID,必需 |
|||
targetInfo |
String |
目标详细信息,若目标类型为玩家,则为对方逻辑服ID,非必需 |
|||
detail |
String |
相关信息,全为英文,参考上面detail定义,必需 |
交互日志举例
这条日志表示当前玩家马克吐温添加了玩家珍妮佛为好友
logKey |
事件 |
日志 |
role-interact |
加入公会:圣光兄弟会 |
time:2014-04-18 22:00:00
interactName:加入公会 |
role-act |
获得一次公会等级提升 |
time:2014-04-18 22:01:00
actName:公会等级提升 |
role-interact |
对敌对公会:战神传说发起公会战争 |
time:2014-04-18 22:10:00
interactName:参战 |
role-stage |
进入战场:长城 |
time:2014-04-18 22:11:00
stageName:进入战场 |
role-interact |
攻击敌对玩家 |
time:2014-04-18 22:11:21
interactName:PVP攻击 |
role-interact |
被敌对玩家杀死 |
time:2014-04-18 22:11:39
interactName:pvp战败死亡 |
role-interact |
被敌对玩家嘲弄 |
time:2014-04-18 22:11:42
interactName:遭到嘲弄 |
role-debit |
使用收费道具:复仇之镰 |
time:2014-04-18 22:11:50 |
role-interact |
攻击敌对玩家 |
time:2014-04-18 22:11:21
interactName:pvp攻击 |
role-interact |
击杀敌对玩家 |
time:2014-04-18 22:11:39
interactName:pvp战斗击杀对方 |
role-stage |
退出战场:长城 |
time:2014-04-18 22:11:00
stageName:退出战场 |
从上面一系列日志,我们可以发现,玩家马克吐温在加入公会圣光兄弟会后,被卷入了一场公会战争,他在战场上被敌人杀死,随后使用收费道具复仇杀死对方。
以下是我们对日志接入功能的一些开发建议,由于网游服务端和客户端技术复杂多变,我们无法面面俱到的为所有游戏提供一套统一的接入规范,因此分享一些接入过程中我们认为对日志发送功能较为有利的开发经验和建议。
详细观察我们的日志发送接口,会发现它仅仅由三个参数组成,分别是logId,logKey和logJson,其中logJson是key-val形式的一个映射表。因此我们希望游戏接入日志时,能够预先在客户端和服务器端之间架设这样一个协议:
消息头——日志发送协议ID
消息体——由三个参数组成,分别为logId,logKey和logJson(一个将key-val映射转换为json格式的字符串)
只要服务器端通过该协议向客户端推送了这样一个消息,那么客户端就把消息体的三个参数转换为样例代码中的logId,logKey和logJson对象,然后调用掌趣sdk提供的日志发送接口发送即可。
将来如果有日志格式的改变或者有新的日志需要发送,我们不需要更新已经上线的客户端,只要在服务端增加相应的代码即可完成新日志发送。这样可以避免由于统计数据需求导致强制更新客户端。
102 |
网络异常,请检查网络 |
103 |
数据异常 |
104 |
SDK初始化参数错误 |
105 |
SDK语言配置文件错误 |
106 |
Ourpalm.cfg配置文件错误 |
107 |
SDK未初始化成功 |
108 |
SDK未设置登录回调 |
109 |
未设置服务器id |
110 |
未设置价格 |
111 |
未设置货币类型 |
112 |
未设置商品名称 |
113 |
未设置商品id |
在MIS中的货币有总共九种,货币ID是没有限定位数的纯自增值。
1 |
人民币 |
分 |
2 |
美元 |
美分 |
3 |
日元 |
円 |
4 |
港币 |
分 |
5 |
英镑 |
便士 |
6 |
新加坡币 |
分 |
7 |
越南盾 |
分 |
8 |
台币 |
元 |
9 |
韩币 |
分 |
10 |
泰铢 |
萨当 |
11 |
卢布 |
戈比 |