Android客户端日志接入说明

1 流程说明

日志接入流程大致分为三个步骤：
1.客户端日志接入开发负责人根据日志接入流程文档，调用日志接口，完成几个基础日志的记录；
2.掌趣科技数据中心对客户端接入的日志进行格式和字段内容检查；
3.客户端日志接入开发负责人与掌趣技术人员通过日志接入测试用例后，日志接入工作正式完成。

2 接口介绍

2.1 接口介绍

SDK日志接口，用于采集客户端的诸如玩家注册，玩家登录，玩家充值，玩家虚拟物品变更，玩家属性变更等用户行为，为产品运营，推广营销等工作提供数据支持。

在调用日志接口时，客户端需要为日志接口提供日志ID，日志关键字，日志内容三个参数，其中，日志内容(val)是一个json格式的字符串，里面详细描述了该次用户行为的具体信息。例如：一个玩家虚拟物品变更日志，他的几个参数大概是这样的：

{  
    "val": "{         
        \"roleLevel\":\"10\",   
        \"roleVipLevel\":\"2\",  
        \"updateType\":\"1\",   
        \"itemId\":\"diamond\",  
        \"itemName\":\"钻石\",   
        \"itemCount\":\"100\",   
        \"custom\":\"商城购买\"  
    }",  
    "id": "9",  
    "key": "role-item-update"  
}

从示例中可见，
日志的id为9，日志的key为role-item-update 意味着这是一条物品变更日志
当时用户的角色等级为10级
当时用户的vip等级为2级
updateType字段，即消费类型记录的是1，意味着用户获得了道具
itemId字段记录的是diamond，itemName字段记录的是钻石，意味着用户获得的道具叫钻石
itemCount字段记录了100，意味着用户获得的钻石数量是100个
custom字段记录的是商城购买，意味着用户是通过购买操作获得这100个钻石

从这样一条日志记录中，我们就可以分析出某个用户于某个时间（sdk会在发送日志时自动把时间，玩家所在逻辑服，角色名，角色id等信息带上），通过商城购买了100钻石，在系统给他发放这100钻石时，他的等级为10，vip等级为2。

需要注意的地方：
当传入中文字符串时，务必确保该中文字符串使用的是utf8编码。例如，商品名称。
由的产品人员和开发人员自行设定的字段信息，也必须由相应的负责人确保内容的一致性。 例如同一个逻辑服下，如果在用户登录注册时调用日志接口传递的逻辑服标识是1001，那么在调用计费中心的充值计费接口时逻辑服标识也应该是同样的1001，而不应该是其他的值。同样的，如果A用户在购买一个极品武器时记录的物品id是001weapon，那么另外一个用户在拍卖同样一个极品武器时物品id也应该是001weapon。

2.1.1 日志发送接口（客户端调用，必须）

功能说明
收集游戏玩家行为信息，用于统计分析玩家行为。
接口定义

/** 
     * 游戏端需发送的统计日志 
     * @param logID 
     * 日志ID 
     * @param logKey 
     * 日志KEY 
     * @parammap 
     * 日志属性MAP 
     */  
public void Ourpalm_SendGameInfoLog(String logID, String logKey,HashMap<string,object>map);

参数说明

接口示例

HashMap<string,object>map = new HashMap<string,object>();  
map.put("key1", "value1");  
map.put("key2", "value2");  
map.put("key3", "value3");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("logID", "logKey", map);

LogId和LogKey对应表

2.1.2 跟踪玩家虚拟货币变更（客户端调用，必须）

当用户在游戏内，因为种种原因产生虚拟货币的增加和消耗时，需要记录一条对应的虚拟货币变更日志。

变更类型：用于标识本次变更是新增了虚拟货币还是消耗了虚拟货币，新增记录1，消耗记录0。
自定义变更描述：用于标识用户因为什么原因变更虚拟货币，如任务获得，怪物掉落，系统赠送，副本奖励，世界喊话，家族奉献，婚姻喜宴等等。
货币ID：用于记录本次引发虚拟货币变更的货币ID
货币名称：用于记录本次引发虚拟货币变更的货币名称
是否为珍贵物品：用于区分珍贵物品，一般情况下直接充值获得的即为珍贵物品，例如 钻石和铜币， 钻石可视为珍贵物品，铜币可视为非珍贵物品。
货币个数：用于记录用户本次消费行为涉及多少个货币，如果用户本次消费行为与具体货币无关，则该字段置空即可。
变化后货币数量：用于记录获得或者消耗后剩余的货币数量
变更描述：用于记录货币变化的原因或途径

需要注意的是，如果玩家的一次用户行为导致多种虚拟货币变更，比如完成一次购买同时获得1000钻石20000铜币，则需要记录相应的两条虚拟货币变更日志。

日志格式示例:

HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "1");  
map.put("roleVipLevel", "0");  
map.put("updateType", "0");  
map.put("itemId", "diamond");  
map.put("itemName", "钻石");  
map.put("isPrecious", "1");  
map.put("itemCount", "100");  
map.put("remains", "2000");  
map.put("custom", "购买道具");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("91", "role-income-update", map);

上面日志表示当前登录的角色为了购买道具花费了100钻石、剩余2000 钻石。

2.1.3 跟踪玩家虚拟物品变更（客户端调用，必须）

当用户在游戏内，因为种种原因产生虚拟物品的增加和消耗时，需要记录一条对应的虚拟物品变更日志。

变更类型：用于标识本次变更是新增了虚拟物品还是消耗了虚拟物品，新增记录1，消耗记录0。
自定义变更描述：用于标识用户因为什么原因变更虚拟物品，如任务获得，怪物掉落，系统赠送，副本奖励，世界喊话，家族奉献，婚姻喜宴等等。
商品ID：用于记录用户本次是因为哪一个游戏内的商品引发的虚拟物品变更，例如购买游戏内的装备、经验、头衔、坐骑等。商品名称由游戏策划人员自行定义，比如 0001对应装备图纸，0002对应黄金翅膀，0003对应经验丹，0004对应体力等等。传入0001,0002,0003……这些ID即可
商品名称：用于记录用户本次是因为哪一个游戏内的商品引发的虚拟物品变更，例如购买游戏内的装备、经验、头衔、坐骑等。商品名称由游戏策划人员自行定义，比如 0001装备图纸，0002黄金翅膀，0003经验丹，0004体力等等。统计结果也会直接将日志中的商品名称展示出来，如果用户本次变更行为与具体商品道具无关，则该字段置空即可。
商品个数：用于记录用户本次消费行为涉及多少个商品，如果用户本次消费行为与具体商品无关，则该字段置空即可。
商品剩余个数：用于记录本次商品获得或者消耗后，当前剩余的个数。
变更描述：用于记录本次商品获得或者消耗的原因或途径。

需要注意的是，如果玩家的一次用户行为导致多种虚拟物品变更，比如完成一次史诗副本同时获得1000珍珠20000石币，则需要记录相应的两条虚拟物品变更日志。

日志格式示例:

HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "1");  
map.put("roleVipLevel", "0");  
map.put("updateType", "0");  
map.put("itemId", "diamond");  
map.put("itemName", "钻石");  
map.put("itemCount", "100");  
map.put("remains", "255");  
map.put("custom", "购买");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("9", "role-item-update", map);  
HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "1");  
map.put("roleVipLevel", "0");  
map.put("updateType", "1");  
map.put("itemId", "MGH_Weapon_001");  
map.put("itemName", "玛格汉铁锤");  
map.put("itemCount", "1");  
map.put("remains", "2");  
map.put("custom", "购买");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("9", "role-item-update", map);

上面两条日志表示当前登录的角色马克.吐温为了购买id为玛格汉铁锤 的武器花了100钻石，剩余255钻石，拥有了2把玛格汉铁锤。

2.1.4 跟踪玩家属性变更（客户端调用，必须）

当用户的角色，发生一些属性上的变化时，记录相应的角色属性变更日志。例如等级提升，军衔提升，VIP等级提升，属性点重配，种族天赋变更等等。
属性标识：角色变更了哪种属性，其中等级标识为level，VIP等级标识为viplevel，其余属性标识由游戏产品和开发人员自行设定。
新属性值：角色完成属性变更之后，该属性的值变成了什么。
变更值：如果该属性值是一个数字，比如等级level，那么本次用户的等级变更了多少，例如购买大礼包level连升三级，则变更值为3。
变更描述：用于记录属性变化的原因或途径

日志格式示例：

HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "3");  
map.put("roleVipLevel", "0");  
map.put("propKey", "level");  
map.put("propValue", "3");  
map.put("rangeability", "2");  
map.put("custom", "");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("10", "role-prop-update", map);  
HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "2");  
map.put("roleVipLevel", "1");  
map.put("propKey", "vipLevel");  
map.put("propValue", "1");  
map.put("rangeability", "1");  
map.put("custom", "首次充值");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("10", "role-prop-update", map);

该记录表示当前角色马克.吐温连升了两级，目前等级为3。他的vip等级升了一级，目前vip等级为1

2.1.5 跟踪玩家游戏内商品属性变更

某些游戏的游戏内商品也有各种属性，比如射击类有戏的枪械会因为改装增加各种新功能，赛车游戏的赛车可以更改引擎、喷漆、轮胎，rpg游戏的玩家会饲养和升级宠物，升级随从的等级和装备等等，因此我们提供了一个游戏内商品属性变更日志，用于记录游戏内各种物品，道具，宠物，随从，武器的等级、技能等属性变更情况。
玩家商品属性变更日志的格式与玩家属性变更日志的区别在于，商品属性变更日志中多了两个用于描述商品的itemId和itemName字段。

日志格式示例：

HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "1");  
map.put("roleVipLevel", "0");  
map.put("itemId", "tank_m4");  
map.put("itemName", "M4谢尔曼中型坦克");  
map.put("propKey", "level");  
map.put("propValue", "3");  
map.put("rangeability", "1");  
map.put("custom", "强化装备");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("13", "role-item-prop-update", map);

该条日志记录，玩家的M4谢尔曼中型坦克等级提升1级，现在的等级为3级

需要注意的是，只有游戏内对玩家游戏体验非常重要的游戏内商品，比如能够辅助战斗的宠物、随从，赛车游戏的赛车和射击游戏的枪械等等才需要记录该日志； 另外有一个需要注意的地方是role-prop-update用于记录玩家游戏角色的等级和其他属性变更信息，而role-item-prop-update用于记录玩家角色持有的游戏内商品属性变更，两个日志的用途不同，描述的对象也不一样，请在接入时注意区分。

2.1.6 跟踪玩家游戏内卡牌属性变更(适用于卡牌类游戏)

对于卡牌类游戏而言，卡牌的收集和升级一直是游戏重点，比如卡牌的稀有程度，等级变化，技能等级等等，因此我们提供了一个游戏内卡牌属性变更日志，用于记录游戏内对应英雄、侠客、随扈等等卡牌的属性变更情况。
玩家卡牌属性变更日志的格式与玩家商品属性变更日志的区别在于，商品属性变更日志中记录的是游戏内商品道具的属性变更，比如武器装备升级之类，而卡牌属性变更则适用于卡牌类游戏。

日志格式示例：

HashMap<string,object>map = new HashMap<string,object>();  
map.put("roleLevel", "1");  
map.put("roleVipLevel", "0");  
map.put("cardId", "blr_man_001");  
map.put("cardName", "李星云");  
map.put("propKey", "level");  
map.put("newValue", "蓝+1");  
map.put("oldValue", "绿");  
map.put("custom", "强化装备");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("14", "role-card-prop-update", map);

该条日志记录，玩家的侠客——李星云，进阶从绿变成了蓝+1。

2.1.7 事件相关日志

当运营人员需要对游戏内的任务完成情况，关卡完成情况进行记录时，即可记录一条游戏自定义事件。在记录日志之前，游戏运营人员有必要向掌趣科技统计后台提供一份任务，关卡，以及其他自定义事件的id和名称对照表，并在掌趣科技统计后台描述任务，关卡，道具之间的关系。

任务，副本关卡日志的格式均为stageId,stageName,detail三个字段，三个字段的值完全由游戏研发人员和运营人员自行指定，例如新手引导任务可以用 newbieguide标识stageId，也可以用task001或其他字符串标识来表示stageId，任务完成，既可以用 SUCC表示，也可以用complete表示，还可以根据任务的中断，放弃，失败等多种状况，为同一个任务记录多条日志。对于同一种事件结果，建议使用同样的detail内容来描述。尽量做到同一个detail的含义一致，同一个事件结果的detail一致。

需要注意的地方：
无论是任务，关卡还是其他自定义事件日志，taskId/stageId/actId字段都必须是相对于该日志的logId唯一，不能够与其他任务，关卡或道具的id字段重复。

尽管任务，副本/场景，以及游戏自定义事件三个日志的字段数量和格式相同，但是我们希望研发人员能够按照预设的不同logid和logkey分别记录这三类日志，这样一来，便于将相对重要的日志同其它日志区分出来，也便于我们对任务和场景副本日志采用预设的特定算法来进行统计运算。

我们要求用以下的默认字段来记录事件日志的detail，以便统计后台可以用默认的配置来对游戏自定义事件进行计算成功率，通过率等进一步指标。
如果列表中的detail无法满足游戏的日志记录要求，也允许各个游戏使用自己定义的detail来记录日志。

其中detail字段建议取值如下所示：

日志格式示例：

HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "10");  
map.put("roleVipLevel", "2");  
map.put("taskId", "newbieguide1");  
map.put("taskName", "新手引导流程1");  
map.put("detail", "accept");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("1001", "role-task", map);  
HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:12:30");  
map.put("roleLevel", "10");  
map.put("roleVipLevel", "2");  
map.put("taskId", "newbieguide1");  
map.put("taskName", "新手引导流程1");  
map.put("detail", "complete");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("1001", "role-task", map);

这两条日志表示，当前角色马克.吐温在17:11:30接受了新手流程任务1，在17:12:30完成了新手流程任务1.

其中detail字段建议取值如下所示：

日志格式示例：

HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "10");  
map.put("roleVipLevel", "2");  
map.put("stageId", "DeadminesIstanc");  
map.put("stageName", "死亡矿井");  
map.put("detail", "begin");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("1002", "role-stage", map);

以上日志表示，当前角色进入死亡矿井。

日志格式示例：

HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "10");  
map.put("roleVipLevel", "2");  
map.put("actId", "fight.mineer");  
map.put("actName", "战斗.狗头人矿工");  
map.put("detail", "begin");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("1003", "role-act", map);

以上日志表示，当前角色和狗头人旷工进行战斗。

2.1.8 自定义交互事件

游戏中除了角色与系统间发生的事件之外，还会有玩家之间的交互事件，这类事件使用交互事件日志来记录。

与游戏自定义事件相比，交互事件多了一个交互对象的概念，targetType字段用于描述本次交互的对象是哪一类对象，0、系统交互，1、玩家之间互动，2、游戏自定义交互。 系统交互事件应该尽量使用游戏自定义事件来记录，除非交互对象较为重要需要额外记录。
targetCode用于描述当前玩家与具体哪一个对象进行了交互，当targetType为2时，targetCode必须为对方角色id，targetInfo必须为对方逻辑服标识。

日志格式示例：

HashMap<string,object>map = new HashMap<string,object>();  
// map.put("time", "2014-04-18 17:11:30");  
map.put("roleLevel", "10");  
map.put("roleVipLevel", "2");  
map.put("interactId", "addfriend");  
map.put("interactName", "添加好友");  
map.put("targetType", "1");  
map.put("targetCode", "0010000067543");  
map.put("targetInfo", "珍妮佛");  
map.put("detail", "ENTER");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SendGameInfoLog("2001", "role-interact", map);

这条日志表示当前玩家马克吐温添加了玩家珍妮佛为好友

2.2 特殊属性设置接口（客户端调用，可选）

功能说明
有一些角色和账户的属性标识，例如种族、职业、天赋之类的用户分类信息，每个游戏都不一样，难以被标准格式的日志兼容，却又对运营人员实时分析用户行为较为重要，就需要记录一下角色或者账户特殊属性。

该接口是可选调用的，如果用户的属性已经可以通过其他日志进行充分描述，则不必调用此接口。

如果已经调用特殊属性接口为角色或账户记录特殊属性值，那么在用户登出角色或账户时，务必清空对应角色账户的属性值，以避免用户更改其他角色或账户登录时，发生属性混淆。
接口定义

/** 
     * 设置统计日志的特殊属性 
     * @param specAttr 
     * 游戏端需要设置的属性参数 
*/  
public void Ourpalm_SetSpecAttr(HashMap<string, string="">specAttr);

参数说明

接口示例

HashMap<string,string>map = new HashMap<string,string>();  
map.put("key1", "value1");  
map.put("key2", "value2");  
map.put("key3", "value3");  
Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_SetSpecAttr(map);

2.3 取消已设置的特殊属性字段（客户端调用，可选）

功能说明
对之前已经设置的特殊属性字段进行清空。接口定义

/** 
 * 清空游戏特殊属性数据 
 */  
public void Ourpalm_CleanSpecAttr();

接口示例

Ourpalm_Entry.getInstance(MainActivity.this).Ourpalm_CleanSpecAttr();

3 开发建议

以下是我们对日志接入功能的一些开发建议，由于网游服务端和客户端技术复杂多变，我们无法面面俱到的为所有游戏提供一套统一的接入规范，因此分享一些接入过程中我们认为对日志发送功能较为有利的开发经验和建议。

3.1 日志发送协议

如果观察我们的日志发送接口，就会发现它仅仅由三个参数组成，分别是logId，logKey和logJson，其中logJson是key-val形式的一个映射表。因此我们希望游戏接入日志时，能够预先在客户端和服务器端之间架设这样一个协议：
消息头——日志发送协议ID
消息体——由三个参数组成，分别为logId,logKey和logJson(一个将key-val映射转换为json格式的字符串)
只要服务器端通过该协议向客户端推送了这样一个消息，那么客户端就把消息体的三个参数转换为样例代码中的logId,logKey和logJson对象，然后调用掌趣sdk提供的日志发送接口发送即可。
这样一来，将来如果有日志格式的改变或者有新的日志需要发送，我们都不需要更新已经上线的客户端，只要在服务端增加相应的代码即可。可以避免由于统计数据需求导致强制更新客户端。

3.2 不重复的角色ID字段

角色ID字段是玩家的身份标识，很多游戏都会开通多个服务器并且在多个服务器之间出现重复的角色ID，我们建议最好用某种方式确保所有服务器的角色id都是不重复的。
原因是手游运营到后期往往会进行合服或者分服操作，分服问题不大，一旦发生合服，则往往角色ID相同的玩家容易因为数据冲突发生各种各样的问题，这时候开发人员对角色ID的任何更改，都将导致统计数据的不准确，因此我们建议在游戏设计阶段就考虑到合服问题，将角色标识做成全服唯一的，以绝后患。

3.3 玩家特殊属性

玩家特殊属性，主要用于某些网游的运营活动，玩家特殊跟踪等功能，由于玩家的属性可能随着游戏不断升级日趋复杂，某些属性会增加进来，另外一些属性会被剔除出去，因此我们建议玩家属性信息的代码应该做成一个可以不断增改的key-val映射，并在玩家属性变更时调用我们的特殊属性设置接口实时更新。