diff --git a/SUMMARY.md b/SUMMARY.md index b7c5f2e..d886a0f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,14 +1,26 @@ # Summary ## SDK入门 -* [SDK简介](README.md) -* [SDK下载](download.md) -* [安装步骤](install.md) +* [SDK简介✔️](intro.md) +* [SDK下载✔️](download.md) +* [安装步骤️️️️✔️](install.md) ## SDK手册 -* [SDK模块功能](modules.md) +* [模块概览](modules.md) * [统计模块](stat.md) - * [启动注册打点](stat_active.md) - * [关卡分析打点](stat_level.md) - * [自定义事件打点](stat_event.md) - * [交叉推广位](stat_ads.md) \ No newline at end of file + * [启动注册打点️✔️](stat_active.md) + * [关卡分析打点️️✔️](stat_level.md) + * [自定义事件打点✔️](stat_event.md) + * [交叉推广位✔️](stat_ads.md) +* [分享视频模块](share.md) +* [在线配置模块](online.md) +* [多平台接口模块](platform.md) + * [支付打点](platform_pay.md) + * [授权按钮](platform_common.md#userbtn) + * [检测自动更新](platform_common.md#autoupdate) + * [打开客服消息](platform_common.md#service) + * [震动接口](platform_common.md#vibrate) + * [其他接口](platform_common.md#other) +* [数据模块](data.md) +* [事件模块](event.md) +* [FAQ](faq.md) \ No newline at end of file diff --git a/download.md b/download.md index 2f46cdc..aed51cd 100644 --- a/download.md +++ b/download.md @@ -12,7 +12,7 @@ **新增：** -1. config.js配置ShareData新增share_wxad_id参数:视频广告uid，配置此参数，拉取不到对应的shareKey，推送看视频，不配置或者配置的uid无效则推送分享 +1. config.js配置ShareData新增share_wxad_id参数：视频广告uid，配置此参数，推送看视频，不配置或者配置的uid无效则推送分享 diff --git a/intro.md b/intro.md new file mode 100644 index 0000000..336b4b4 --- /dev/null +++ b/intro.md @@ -0,0 +1,59 @@ +# 噗嗤SDK +PCSDK（噗嗤SDK）是一款封装了微信小游戏、QQ小游戏平台常用api接口和用户行为数据上报的一款产品。 +PCSDK上报小游戏用户所触发的各种行为数据到噗嗤管理后台，后台对数据进行统计分析后多样化的展示数据统计。 + +**PCSDK提供的模块功能：** + +- 统计模块 +- 数据模块 +- 分享视频模块 +- 在线参数模块 +- 跨平台功能模块 + + + +# 噗嗤管理后台 +噗嗤管理后台统计sdk中上报的各项数据进行分析；管理各种sdk中所需要的配置信息：分享/视频配置、配置参数（在线参数配置）、噗嗤游戏导出广告配置、用户事件行为配置。 + +为了开发联调测试阶段不影响游戏已上线运营相关数据或者配置信息，特意对管理后台做了测试和线上服划分，噗嗤管理后台分为：测试服后台，正式服后台： + +噗嗤管理后台后台地址： + +- 正式服后台，地址：https://data.d3games.com/#/login + +- 测试服后台，地址：http://pre-data.d3games.com/#/login + +**友情提示：** + +- **之后文案中后台指的是噗嗤管理后台，而不是微信小程序/小游戏后台。** +- **后台登录账号获取，需提供手机信息给我方运营，运营创建后台登录账号、密码后反馈；登录后台即可使用后台提供的各项服务** + + + +**噗嗤后台概览：** +## ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_006.png) + + + +**后台提供数据分析功能：** + +- 注册/活跃用户，在线时长实时数据分享。 +- 分享数据分析 +- 用户事件行为分析 +- 渠道数据统计分析 + + + +**后台提供配置相关功能：** + +- 分享视频配置 +- 动态配置参数 + + + +# 更多： +- 快速接入，请详读 [安装步骤](install.md) + + + +- 遇到问题可以查看 [FAQ](faq.md) \ No newline at end of file diff --git a/platform.md b/platform.md new file mode 100644 index 0000000..3114470 --- /dev/null +++ b/platform.md @@ -0,0 +1,174 @@ +# 启动注册打点 + +------ + +#### **简介** + +启动注册打点上报用户注册活跃数据，噗嗤管理后台为游戏提供用户数据统计：实时获取活跃、新增用户数、打开次数、在线时长......；注册转化统计。 + + + +#### **后台使用** + +完成启动注册打点后，登录后台->头部tab切换到【游戏数据】->【产品分析】->【实时数据】即可实时查看用户活跃、新增等信息： +![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_008.png) + +点击【注册转化】可查看列表式显示新增、注册、加载完成等详细信息： + +![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_009.png) + + + + + +#### **接入API：** + +| **名称** | **功能说明** | +| ------------------------ | ------------------------------------------------------------ | +| PCSDK.stat.loadingFinish | 加载游戏资源完成时打点，不是微信代码包白屏加载完成，游戏loading自身cdn资源加载完成调用 | +| PCSDK.stat.setLogind | 设置sdk必须要使用的用户id、第一次创建角色的注册时间，游戏接入方登录游戏服务器后调用 | +| PCSDK.stat.active | 用户活跃/新增注册上报，切记在setLogind设置需要的信息过后使用（不限于使用位置），不然会导致新增注册数据统计异常 | + + + + + + + +1. **loadingFinish** + + ```javascript + PCSDK.stat.loadingFinish(): void + ``` + + 定义：加载游戏加载资源完成时打点 + + 参数： + + ``` + 无 + ``` + + 示例：加载完成游戏主界面图片、json资源打点 + + ```javascript + private async initEnv() { + await SDKTools.env(Const.VERSION); + this.loadRes(); + this.loadLogin(); + } + + // 开始加载资源 + private loadRes() { + LoaderManager.I.setCallback(this.onLoadedMain, this.onProgressMain, null, this).loadMain(); + } + + // 资源加载完成 + private onLoadedMain() { + PCSDK.stat.loadingFinish() + } + + // 更新资源加载进度条 + private onProgressMain(ret) { + let progress = ret.data; + this.skin.txtProgress.text = Math.floor(progress * 100) + '%'; + } + ``` + +2. **setLogind** + + ```javascript + PCSDK.stat.setLogind( data: object ): void + ``` + + 定义：游戏登录完成，得到登录用户的用户id和用户第一次注册时间，设置SDK必需的用户信息 + + 参数： + + ```javascript + data: object +{ + userId: string | number 必传, 用户唯一标识id + regTime: number 必传，用户第一次创建角色的注册时间戳 + } + ``` + + 示例：游戏登录完成后，获取用户信息后进行打点（该示例，只是模拟使用环境） + + ```javascript + // 发起登录请求，得到登录数据信息，调用setLogind设置SDK用户信息 + Api.login().then( data => { + let { user_id, user_reg_time } = data; + PCSDK.stat.setLogind({ + userId: data.user_id, + regTime: data.user_reg_time + }); + }); + ``` + +3. **active** + + ```javascript + PCSDK.stat.active(): void + ``` + + 定义：用户活跃/新增注册上报，切记在使用setLogind设置用户信息过后调用此接口，不然会导致新增注册数据统计异常 + + 参数： + + ```javascript + 无 + ``` + + 示例：游戏登录完成后，获取用户信息后进行打点（该示例，只是模拟该接口使用环境） + + ```javascript + // 使用场景1：发起登录请求，得到用户数据信息，调用setLogind设置SDK用户信息后立即调用active + Api.login().then( data => { + let { user_id, user_reg_time } = data; + // 设置用户信息 + PCSDK.stat.setLogind({ + userId: data.user_id, + regTime: data.user_reg_time + }); + // 用户活跃注册打点 + PCSDK.stat.active(); + }); + + // 使用场景2：发起登录请求，得到用户数据信息，调用setLogind设置SDK用户信息。在其他界面调用active + // 资源加载loading界面 + class LoadingScene(){ + constructor(){ + this.login(); + } + + private login(){ + // 登录 + Api.login().then( data => { + let { user_id, user_reg_time } = data; + // 设置用户信息 + PCSDK.stat.setLogind({ + userId: data.user_id, + regTime: data.user_reg_time + }); + // 进入home主页场景 + SceneManager.I.switchScene(HomeScene); + }); + } + } + + // Home页面 + class HomeScene(){ + constructor(){ + this.btnStarGame.on('click', this.onGame, this); + } + + private onGame(){ + // 用户活跃注册打点 + PCSDK.stat.active(); + // 进入游戏页面 + SceneManager.I.switchScene(GameScene); + } + } + + ``` \ No newline at end of file diff --git a/stat_level.md b/stat_level.md index 3c84920..c5d1362 100644 --- a/stat_level.md +++ b/stat_level.md @@ -18,50 +18,265 @@ | **名称** | **功能说明** | | ---------------- | ------------------------------------------------------------ | -| PCSDK.stat.event | 自定义事件打点，使用前请[前往后台](http://pre-data.d3games.com/index.html#/login)进行添加自定义事件key | +| PCSDK.stat.logLevelRelive | 游戏关卡复活上报 | +| PCSDK.stat.logLevelHide | 游戏关卡onHide上报，在游戏界面注册wx.onHide事件，判断不属于复活、失败、成功状态下上报此数据 | +| PCSDK.stat.logLevelFail | 游戏关卡失败上报 | +| PCSDK.stat.logLevelWin | 游戏关卡成功上报 | +| PCSDK.stat.logMerge | 游戏二合一合成最高等级上报 | -1. **event** +1. #### **logLevelRelive** ```javascript - PCSDK.stat.event(event_key: string , event_source: string , opts?: { ext_val?: string | number} ): Promise + PCSDK.stat.logLevelRelive(levelId: string | number , opts?: { attr: number } ): void ``` - 定义：自定义事件打点，可在游戏任何位置定义事件打点 + 定义：关卡复活成功数据上报 参数： ``` - event_key: string 必传，后台配置的事件key + levelId: string | number 必传，游戏关卡id - event_source: string 必传，触发该事件所在页面位置，例如：结算页面、排行榜界面、签到页面。。。 + 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 选传，自定义扩展参数，一些特定的事件想传递更多信息，此参数使用请咨询相关对接人员目前只支持对象一个key（evt_val），多个扩展参数使用'|'连接 + opts: object 选传，扩展参数，目前只支持传递一个属性: attr { - ext_val: '100|1000' + attr: number 战斗属性（例如:关卡战斗中所使用的枪支等级） } ``` - 示例： + + [点此查看完整示例](stat_level.md#sample)如何添加关卡失败打点代码 + +3. #### **logLevelFail** ```javascript - // 签到功能 - private onSign() { - PCSDK.stat.event(EventKeys.FunctionSign, '主界面'); - } + PCSDK.stat.logLevelFail(levelId: string | number , opts: { ctime: number, first: number, attr?: number } ): void + ``` + + 定义：关卡失败数据上报 + + 参数： + + ``` + levelId: string | number 必传，游戏关卡id - // 开始加载资源 - private loadRes() { - PCSDK.stat.event(EventKeys.LoadingExhibition, '加载界面'); - LoaderManager.I.setCallback(this.onLoadedMain, this.onProgressMain, null, this).loadMain(); - } + 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 - // 升级领奖 - private onReward(e: Laya.Event) { - PCSDK.stat.event(EventKeys.LvUpRewards, '升级界面'); - SDKTools.shareDispatch(ShareKey.LevelUpDiamond, { - success: this.handleDoubleReward, - context: this - }); + opts: object 必传，扩展参数 + { + ctime: number 必传 关卡耗时 = 当前时间-关卡进入时间，单位秒 + first: number 必传 是否第一次体验关卡，1是，0否 + attr: number 选传 战斗属性（例如:关卡战斗中所使用的枪支等级） + } + ``` +
完整示例，以上四个接口使用场景： +> 监听游戏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 ); + } + ``` + + \ No newline at end of file -- libgit2 0.21.0