# 关卡分析打点
------
#### **简介**
关卡分析，为开发者提供小游戏详细的关卡数据，分析各关卡玩家的通关状况，帮助开发者从数据角度衡量游戏设计的合理性，调节难易度，观察各关卡道具使用情况和奖励获取状况，对比分析各个指标，通过量化玩家数据，提高游戏体验。
#### **后台使用**
接入关卡分析接口后，登录后台->头部tab切换到【游戏数据】->【产品分析】->【关卡分析】可查看关卡进入用户数据、失败次数、失败率、平均完成时间等）：
#### **接入API**：
| **名称** | **功能说明** |
| ---------------- | ------------------------------------------------------------ |
| PCSDK.stat.logLevelRelive | 游戏关卡复活上报 |
| PCSDK.stat.logLevelHide | 游戏关卡onHide上报，在游戏界面注册wx.onHide事件，判断不属于复活、失败、成功状态下上报此数据 |
| PCSDK.stat.logLevelFail | 游戏关卡失败上报 |
| PCSDK.stat.logLevelWin | 游戏关卡成功上报 |
| PCSDK.stat.logMerge | 游戏二合一合成最高等级上报 |
1. #### **logLevelRelive**
```javascript
PCSDK.stat.logLevelRelive(levelId: string | number , opts?: { attr: number } ): void
```
定义：关卡复活成功数据上报
参数：
```
levelId: string | number 必传，游戏关卡id
opts: object 选传，扩展参数，目前只支持传递一个属性: attr
{
attr: number 战斗属性（例如:关卡战斗中所使用的枪支等级）
}
```
[点此查看完整示例](stat_level.md#sample)如何添加关卡复活成功打点代码
2. #### **logLevelHide**
```javascript
PCSDK.stat.logLevelHide(levelId: string | number , opts?: { attr: number } ): void
```
定义：监听游戏战斗界面onHide时上报关卡的数据。什么是界面onHide？[请详读微信小游戏wx.onHide](https://developers.weixin.qq.com/minigame/dev/api/base/app/life-cycle/wx.onHide.html)
注意事项：
> 1）游戏战斗界面监听平台的onHide事件，使用此api上报关卡onHide打点。
>
>
> 2）游戏战斗界面退出后，要移除onHide事件监听，避免在其他界面下，onHide时候执行此次上报。
>
>
> 3）一定要屏蔽游戏复活中、游戏失败、游戏通过成功状态，这三种状态下避免上报此打点，详看下面示例。
参数：
```
levelId: string | number 必传，游戏关卡id
opts: object 选传，扩展参数，目前只支持传递一个属性: attr
{
attr: number 战斗属性（例如:关卡战斗中所使用的枪支等级）
}
```
[点此查看完整示例](stat_level.md#sample)如何添加关卡onHide打点代码
3. #### **logLevelFail**
```javascript
PCSDK.stat.logLevelFail(levelId: string | number , opts: { ctime: number, first: number, attr?: number } ): void
```
定义：关卡失败数据上报
参数：
```
levelId: string | number 必传，游戏关卡id
opts: object 必传，扩展参数，目前只支持传递一个属性: attr
{
ctime: number 必传 关卡耗时 = 当前时间-关卡进入时间，单位秒
first: number 必传 是否第一次体验关卡，1是，0否
attr: number 选传 战斗属性（例如:关卡战斗中所使用的枪支等级）
}
```
[点此查看完整示例](stat_level.md#sample)如何添加关卡失败打点代码
4. #### **logLevelWin**
```javascript
PCSDK.stat.logLevelWin(levelId: string | number , opts: { ctime: number, first: number, attr?: number } ): void
```
定义：关卡成功通关数据上报
参数：
```
levelId: string | number 必传，游戏关卡id
opts: object 必传，扩展参数
{
ctime: number 必传 关卡耗时 = 当前时间-关卡进入时间，单位秒
first: number 必传 是否第一次体验关卡，1是，0否
attr: number 选传 战斗属性（例如:关卡战斗中所使用的枪支等级）
}
```
完整示例，以上四个接口使用场景：
> SDK中监听了onHide事件，当游戏onHide时，SDK会发送事件名为'app.hide'的自定义事件，开发者可在代码中使用PCSDK.event.bindEvent监听该事件，使用PCSDK.event.removeEvent移除对应监听事件，[详细文档event模块文档请阅读event事件模块](evennt.md)。
```javascript
/**
* 游戏界面
**/
exports class GameScene extends BaseView{
// 关卡id
private missionId: number;
// 当前选中使用的枪支等级
private currSelectGun: number;
// 游戏状态机
private gameState: GameState;
// 关卡开始时间
private enterTime: number;
constructor(){
this.gameState = GameState.Idle;
}
// 游戏界面打开
open(){
super.open();
this.gameState = GameState.Idle;
this.enterTime = new Date().getTime();
this.addEvent();
}
// 游戏界面关闭
close(){
super.close();
this.removeEvent();
}
// 添加游戏事件监听
private addEvent(){
// 监听SDK中app.hide事件事件消息
PCSDK.event.bindEvent( 'app.hide', this.handleHide, this);
// 监听游戏中level.relive事件消息
EventCenter.I.add('level.relive', this, this.handleLevelRelive);
}
// 移除游戏事件监听
private removeEvent(){
PCSDK.event.removeEvent( 'app.hide', this.handleHide, this);
EventCenter.I.remove('level.relive', this, this.handleLevelRelive);
}
// 游戏复活中
private doGameRelive(){
this.setState(GameState.Relive);
}
// 游戏通关失败
private doGameFail(){
this.setState(GameState.Fail);
}
// 游戏通关成功
private doGameWin(){
this.setState(GameState.Win);
}
// SDK发出的app.hide事件监听
private handleHide() {
// 战斗界面onHide上报logLevelHide（游戏通关成功、游戏通关失败、游戏复活中不进行上报logLevelHide打点）
if(!(this.isState(GameState.Win) || this.isState(GameState.Fail) || this.isState(GameState.Relive)))
PCSDK.stat.logLevelHide(this.missionId, {
attr: this.currSelectGun
});
}
// 监听关卡复活成功消息
private handleLevelRelive(){
// 关卡复活成功上报
PCSDK.stat.logLevelRelive(this.missionId, {
attr: this.currSelectGun
});
}
private isState(state: GameState) {
return this.state === state;
}
// 设置状态机
private setState(state: GameState) {
if (this.isState(state)) return;
this.state = state;
let costTime: number; // 关卡消耗时间
let failNum: number; // 关卡失败次数
switch (state) {
case GameState.Win: // 处理成功
// 关卡成功上报
costTime = new Date().getTime() - this.enterTime;
failNum = DataManager.I.LocalModel.getMissionFailNum(this.missionId);
PCSDK.stat.logLevelWin(this.missionId, {
ctime: costTime,
first: failNum ? 0 : 1,
attr: this.currSelectGun
});
break;
case GameState.Fail: // 处理失败
// 关卡失败上报
costTime = new Date().getTime() - this.enterTime;
failNum = DataManager.I.LocalModel.getMissionFailNum(this.missionId);
PCSDK.stat.logLevelFail(this.missionId, {
ctime: costTime,
first: failNum ? 0 : 1,
attr: this.currSelectGun
});
break;
case GameState.Relive:// 处理复活中
// 弹出复活操作界面
PopWinManager.I.openPopwin(RelivePopwinn);
break;
}
}
}
/**
* 复活界面
**/
exports class RelivePopwinn extends BaseView{
// 复活界面关闭
close(){
super.close();
// 关闭模拟:复活成功，发送复活成功消息
EventCenter.I.emit('level.relive');
}
}
// 游戏状态状态机
enum GameState{
Idle, // 初始状态
Fail, // 失败状态
Win, // 成功通关状态
Relive // 正在复活状态
}
```
5. #### **logMerge**
```javascript
PCSDK.stat.logMerge(mergeLv: number): void
```
定义：游戏二合一合成最高等级上报
参数：
```
mergeLv: number 必传，二合一合成最高等级
```
示例：二合一部分，合成最高等级时候上报
```javascript
// 合成最新等级合成
private handleMergeLastestLv(lastestLv: number){
// 合成最新等级上报
PCSDK.stat.logMerge( lastestLv );
}
```