# 关卡分析打点

------

#### **简介**

关卡分析，为开发者提供小游戏详细的关卡数据，分析各关卡玩家的通关状况，帮助开发者从数据角度衡量游戏设计的合理性，调节难易度，观察各关卡道具使用情况和奖励获取状况，对比分析各个指标，通过量化玩家数据，提高游戏体验。

#### **后台使用**

接入关卡分析接口后，登录后台->头部tab切换到【游戏数据】->【产品分析】->【关卡分析】可查看关卡进入用户数据、失败次数、失败率、平均完成时间等）：

![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_020.png)



#### **接入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时（监听wx.onHide事件）关卡退出数据上报。
   > 需要屏蔽掉复活、失败、成功状态下onHide

   参数：

   ```
   levelId: string | number 必传，游戏关卡id
   
   opts: object 选传，扩展参数，目前只支持传递一个属性: attr
   {
        attr: number  战斗属性（例如:关卡战斗中所使用的枪支等级）
   }
   ```

   [点此查看完整示例](stat_level.md#sample)如何添加关卡失败打点代码

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 选传 战斗属性（例如:关卡战斗中所使用的枪支等级）
   }
   ```
   <div id="sample"></div> 完整示例，以上四个接口使用场景：
> 监听游戏wx.onHide关卡数据上报后上报（需要屏蔽掉复活、失败、成功状态），在执行wx.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上报）
            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 );
   }
   ```