From 6a23c5dbb9a57d6c0cf1d5380de1caee8f7722ba Mon Sep 17 00:00:00 2001 From: 小川 费 <449111130@qq.com> Date: Fri, 20 Sep 2019 16:41:49 +0800 Subject: [PATCH] 1 --- SUMMARY.md | 12 +++++------- images/sdk_029.png | Bin 0 -> 105752 bytes images/sdk_video_001.mp4 | Bin 0 -> 2153060 bytes images/sdk_video_002.mp4 | Bin 0 -> 1014796 bytes install.md | 3 +-- platform.md | 378 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------------------------------------------------------------------------------- word/噗嗤SDK（PCSDK）.xmind | Bin 338168 -> 0 bytes 7 files changed, 285 insertions(+), 108 deletions(-) create mode 100644 images/sdk_029.png create mode 100644 images/sdk_video_001.mp4 create mode 100644 images/sdk_video_002.mp4 diff --git a/SUMMARY.md b/SUMMARY.md index c04d8e1..8716b3b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -14,13 +14,11 @@ * [交叉推广位](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) +* [多平台接口模块](platform.md) + * [支付打点](platform.md#logpay) + * [检测自动更新](platform.md#checkUpdate) + * [打开客服消息](platform.md#service) + * [震动接口](platform.md#vibrate) * [数据模块](data.md) * [事件模块](event.md) * [FAQ❎](faq.md) \ No newline at end of file diff --git a/images/sdk_029.png b/images/sdk_029.png new file mode 100644 index 0000000..d724cce Binary files /dev/null and b/images/sdk_029.png differ diff --git a/images/sdk_video_001.mp4 b/images/sdk_video_001.mp4 new file mode 100644 index 0000000..ed8fdf3 Binary files /dev/null and b/images/sdk_video_001.mp4 differ diff --git a/images/sdk_video_002.mp4 b/images/sdk_video_002.mp4 new file mode 100644 index 0000000..a00e950 Binary files /dev/null and b/images/sdk_video_002.mp4 differ diff --git a/install.md b/install.md index 0b6a9bd..3e2eb2d 100644 --- a/install.md +++ b/install.md @@ -60,9 +60,8 @@ - * #### 根据运营提供的信息修改sdk文件夹下的**config**.js文件（可横向拖动查看查看更多====>）
- +
```javascript export default { IsDebug: false, // 是否debug模式，debug模式会打印log，可使用stat模块setDebug api进行修改 diff --git a/platform.md b/platform.md index 7011f02..71e935b 100644 --- a/platform.md +++ b/platform.md @@ -1,23 +1,34 @@ -# 多平台接口模块 +# 多平台接口模块：PCSDK.platform ------ #### **简介** -启动注册打点上报用户注册活跃数据，噗嗤管理后台为游戏提供用户数据统计：实时获取活跃、新增用户数、打开次数、在线时长......；注册转化统计。 +所谓多平台指的是微信小游戏、QQ轻游戏、今日头条、oppo等游戏发布的平台。微信和QQ接口文档api相似度99%，微信、QQ、今日头条平台的接口api相似度80%以上，虽然相似度很高，但是仍需要针对差异性做一些处理。多平台接口模块就是想要在SDK内部去抹平了各个平台差异性的处理，达到同一个api调用，应用多个平台的作用。 +#### **此模块是参照微信小游戏提供的api进行封装的公用方法，提供了以下游戏中常用到的功能：** +**支付打点：logPay** (此模块保留logPay调用只是为了兼容已经接入的游戏，该api已经归类到【统计模块】下面的[支付打点](stat_pay.md)栏)。 -#### **后台使用** +**打开客服消息：openCustomerServiceConversation** 整理[wx.openCustomerServiceConversation](https://developers.weixin.qq.com/minigame/dev/api/open-api/customer-message/wx.openCustomerServiceConversation.html) -完成启动注册打点后，登录后台->头部tab切换到【游戏数据】->【产品分析】->【实时数据】即可实时查看用户活跃、新增等信息： -![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_008.png "🔍点击查看大图") +**检测版本更新：checkUpdate** 整理来自：[wx.getUpdateManager](https://developers.weixin.qq.com/minigame/dev/api/base/update/UpdateManager.html) -点击【注册转化】可查看列表式显示新增、注册、加载完成等详细信息： +**显示模态弹出框：showModal** 整理来自：[wx.showModal](https://developers.weixin.qq.com/minigame/dev/api/ui/interaction/wx.showModal.html) -![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_009.png "🔍点击查看大图") +**复制文本：copy** 整理来自：[wx.setClipboardData](https://developers.weixin.qq.com/minigame/dev/api/device/clipboard/wx.setClipboardData.html) +**长震动：vibrateLong** 整理来自：[wx.vibrateLong](https://developers.weixin.qq.com/minigame/dev/api/device/vibrate/wx.vibrateLong.html) +**短震动：vibrateShort** 整理来自：[wx.vibrateShort](https://developers.weixin.qq.com/minigame/dev/api/device/vibrate/wx.vibrateShort.html) + +**更新转发属性：updateShareMenu** 整理来自：[wx.updateShareMenu](https://developers.weixin.qq.com/minigame/dev/api/share/wx.updateShareMenu.html) + +**微信小游戏推荐弹窗组件GamePortal：isGamePortalPlaying 与 gamePortalShow** 整理来自：[wx.createGamePortal](https://developers.weixin.qq.com/minigame/dev/api/game-portal/GameBanner.html) + +**微信小游戏推荐icon组件GameIcon：gameIconShow 与 gameIconDestroy** 整理来自：[wx.createGameIcon](https://developers.weixin.qq.com/minigame/dev/api/game-portal/wx.createGameIcon.html) + +**微信小游戏插屏广告组件InterstitialAd：isInterstitialPlaying 与 interstitialShow** 整理来自：[wx.createInterstitialAd](https://developers.weixin.qq.com/minigame/dev/api/ad/InterstitialAd.html) @@ -25,150 +36,319 @@ | **名称** | **功能说明** | | ------------------------ | ------------------------------------------------------------ | -| PCSDK.stat.loadingFinish | 加载游戏资源完成时打点，不是微信代码包白屏加载完成，游戏loading自身cdn资源加载完成调用 | -| PCSDK.stat.setLogind | 设置sdk必须要使用的用户id、第一次创建角色的注册时间，游戏接入方登录游戏服务器后调用 | -| PCSDK.stat.active | 用户活跃/新增注册上报，切记在setLogind设置需要的信息过后使用（不限于使用位置），不然会导致新增注册数据统计异常 | - - +| PCSDK.platform.logPay | 支付统计打点，支付完成（取消、成功、失败）的打点 | +| PCSDK.platform.openCustomerServiceConversation | 进入客服会话，可打开一个普通的客服会话，也可打开客服会话发送体力、钻石和进入跳转充值等，[具体用法请看](platform.md#service)| +| PCSDK.platform.checkUpdate | 检测版本是否有更新，如果版本更新会弹出确认框 | +| PCSDK.platform.vibrateShort | 使手机发生较短时间的振动（15 ms） | +| PCSDK.platform.vibrateLong | 使手机发生较长时间的振动（400 ms) | -1. **loadingFinish** +
+1. **logPay** ```javascript - PCSDK.stat.loadingFinish(): void + PCSDK.platform.logPay( params: object ): void ``` - 定义：加载游戏加载资源完成时打点 + 定义：开发者游戏充值完成后，上报支付结果打点，支付结果类型：0（支付失败），1（支付成功），-1（取消支付）。该api需在[config.js中配置MidasPay](install.md#configJs)信息。 参数： ``` + params object 必传 打点参数 + { + type: number 必传 支付类型：0（支付失败），1（支付成功），-1（取消支付）; + source: string 必传 游戏服务商生成的订单号，没有则为空字符串 + amount: number 必传 实际支付金额，单位分 + buy_id: string | number; 必传 商品ID + buy_name: string; 必传 商品名称 + item_info: string 必传 获得的道具内容：道具id及数量，逗号分隔，多项使用分号分隔 => 1,1;2,10;3,100 + } + ``` + 返回值： + + ``` + void 无 ``` - 示例：加载完成游戏主界面图片、json资源打点 + 示例：客户端游戏支付完成后上报支付打点，下例只是演示logPay用法 ```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) + '%'; + private reqPay() { + Api.I.pay().then( ret => { + switch(ret.code){ + case 1: // 支付成功回调处理 + PCSDK.platform.logPay({ + type: 1, // 成功支付 + source: "10000400", // 订单号，没有则为空字符串 + amount: 10 * 100, // 10元 + buy_id: 58, // 支付的商品id + buy_name: "钻石*152，金币*188888888", + item_info: "40,152;90,188888888" // 例如 钻石id：40 金币id：90 + }); + break; + + case 0: // 支付失败回调处理 + PCSDK.platform.logPay({ + type: 0, // 失败支付 + source: "10000400", // 订单号，没有则为空字符串 + amount: 10 * 100, // 10元 + buy_id: 58, // 支付的商品id + buy_name: "钻石*152，金币*188888888", + item_info: "40,152;90,188888888" // 例如 钻石id：40 金币id：90 + }); + break; + + case -1: // 支付取消回调处理 + PCSDK.platform.logPay({ + type: -1, // 取消支付 + source: "10000400", // 订单号，没有则为空字符串 + amount: 10 * 100, // 10元 + buy_id: 58, // 支付的商品id + buy_name: "钻石*152，金币*188888888", + item_info: "40,152;90,188888888" // 例如 钻石id：40 金币id：90 + }); + break; + } + }); } ``` - -2. **setLogind** +
+2. **openCustomerServiceConversation** ```javascript - PCSDK.stat.setLogind( data: object ): void + PCSDK.platform.openCustomerServiceConversation( params?: _CustomerServiceConversationObject ): void ``` - 定义：游戏登录完成，得到登录用户的用户id和用户第一次注册时间，设置SDK必需的用户信息 + 定义：进入客服会话，可打开一个普通的客服会话，也可打开客服会话发送体力和进入跳转充值 参数： ```javascript - data: object -{ - userId: string | number 必传, 用户唯一标识id - regTime: number 必传，用户第一次创建角色的注册时间戳 + params _CustomerServiceConversationObject 选传，不传递打开一个普通的客户会话。[参数说明参照](https://developers.weixin.qq.com/minigame/dev/api/open-api/customer-message/wx.openCustomerServiceConversation.html) + { + sessionFrom string 选传 会话来源 + showMessageCard boolean 选传 是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息 + sendMessageTitle string 选传 会话内消息卡片标题 + sendMessagePath string 选传 会话内消息卡片路径 + sendMessageImg string 选传 会话内消息卡片图片路径 + success function 选传 接口调用成功的回调函数 + fail function 选传 接口调用失败的回调函数 + complete function 选传 接口调用结束的回调函数（调用成功、失败都会执行） } ``` - 示例：游戏登录完成后，获取用户信息后进行打点（该示例，只是模拟使用环境） + 示例1：进入普通的客服会话 ```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 - }); - }); + PCSDK.platform.openCustomerServiceConversation(); + ``` + 示例2：应用场景如进入客服会话跳转领取体力、钻石等等： 示例为跳转客服领取18888钻石奖励，success函数中记录数据状态（用于客服返回，执行onShow生命周期函数时逻辑判断）。 + + + ```javascript + // 跳转客服领取18888钻石奖励，开发者可根据示例修改 + PCSDK.platform.openCustomerServiceConversation({ + showMessageCard: true, + sendMessageTitle: '钻石已发送，点击领取钻石！', + sendMessagePath: '', + sendMessageImg: 'http://dep.miso-lab.com/mergeguns/bin/res/image/service_reward.png', // 图片icon对应的域名记得加入到request和download白名单中 + success: () => { + // 打开跳转客服成功，记录成功状态，在游戏全局注册的onShow监听通过判断这个状态去请求接口领取奖励 + // 记录数据状态，onShow的时候读取数据状态判断，只是演示操作，可根据实际情况修改 + AppDataManager.I.set('service.reward.data', { + status: 1, // 可以领奖 + reward: 18888 // 获得18888钻石 + }); + }, + fail: (err) => { + console.log("openCustomerServiceConversation fail: ", err); + } + }); + + // 在游戏中全局注册的onShow事件监听中检测是 + // 游戏入口：Main.cs + class Main { + constructor() { + this.init(); + } + + private init() { + PCSDK.event.add('app.show', this.onShow, this); // 等同于wx.onShow(this.onShow.bind(this)); + PCSDK.event.add('app.hide', this.onHide, this); // 等同于wx.onHide(this.onHide.bind(this)); + } + + private onShow(opts) { + // 判断是否是来源于客服会话，上面的openCustomerServiceConversation的success设置的数据状态做判断 + let serviceRewardData = AppDataManager.I.get('service.reward.data'); + if (serviceRewardData && serviceRewardData.status === 1) { + AppDataManager.I.set('service.reward.data', null); + // 奖励发放，处理发放后的逻辑，比如每天只能领取一次的记录，防止重复刷奖励 + } + } + + private onHide(){ + // 监听平台的onHide事件 + } + } ``` + 示例3：应用场景例如进入客服会话，success函数中记录数据状态（用于客服返回，执行onShow生命周期函数时逻辑判断），点击右下角的充值按钮后，跳转充值，充值完成后在onShow中处理：需要后台提供api接口，验证充值合理性并发放奖励，**此接口需要后端支持**。 + -3. **active** + ```javascript + // 跳转客服充值，开发者可根据示例修改，sendMessagePath请严格按照示例中提供的参数 + /** + * 充值跳转客服 + * @param itemId 购买道具商品id + * @param money 购买商品花费，单位元 + */ + private openServiceWithItem(itemId: number, money: number) { + PCSDK.platform.openCustomerServiceConversation({ + showMessageCard: true, + sendMessageTitle: `充值${money}元`, + sendMessagePath: `channel=${PCSDK.data.ChannelId}&item=${itemId}&uid=${PCSDK.data.UserId}&pf=${PCSDK.data.SystemId}`, + sendMessageImg: 'http://dep.miso-lab.com/idiom/bin/share/pay.png', // 图片icon对应的域名记得加入到request和download白名单中 + success: () => { + // 打开跳转客服成功，记录成功状态，onShow通过判断这个状态去请求接口领取奖励 + // 记录数据状态，onShow的时候读取数据状态判断，只是演示操作，可根据实际情况修改 + AppDataManager.I.set('service.pay.data', { + status: 1, // 可以领奖 + itemId: itemId, // 购买道具商品id + money: money // 购买商品花费，单位元 + }); + }, + fail: (err) => { + console.log("openCustomerServiceConversation fail: ", err); + } + }); + } + + // 在游戏中全局注册的onShow事件监听中检测是 + // 游戏入口：Main.cs + class Main { + constructor() { + this.init(); + } + + private init() { + PCSDK.event.add('app.show', this.onShow, this); // 等同于wx.onShow(this.onShow.bind(this)); + PCSDK.event.add('app.hide', this.onHide, this); // 等同于wx.onHide(this.onHide.bind(this)); + } + + private onShow(opts) { + // 判断是否是来源于客服会话，上面的openCustomerServiceConversation的success设置的数据状态做判断 + let serviceRewardData = AppDataManager.I.get('service.pay.data'); + if (serviceRewardData && serviceRewardData.status === 1) { + AppDataManager.I.set('service.pay.data', null); + // 领取奖励的逻辑，比如每天只能领取一次的记录，防止重复刷奖励 + // 请求后端接口验证奖励合理性 + } + } + + private onHide(){ + // 监听平台的onHide事件 + } + } + ``` +
+3. **checkUpdate** ```javascript - PCSDK.stat.active(): void + PCSDK.platform.checkUpdate( params?: _ShowModalObject ): void ``` - 定义：用户活跃/新增注册上报，切记在使用setLogind设置用户信息过后调用此接口，不然会导致新增注册数据统计异常 + 定义：检测版本是否有更新，如果版本有更新会弹出确认框，参数可不传递，不传递有版本更新会弹出下图的默认确认框；开发者可自定义弹出框的显示样式，参数与[wx.showModal](https://developers.weixin.qq.com/minigame/dev/api/ui/interaction/wx.showModal.html)一模一样。 + 建议此api在游戏的入口调用。 + ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_029.png "🔍点击查看大图") 参数： ```javascript - 无 + params _ShowModalObject 选传 不传递有版本更新会弹出上图样式默认确认框；开发者可自定义弹出框的显示样式，参数参照wx.showModal的参数 + { + title string 选传 提示的标题，默认为：更新提示 + content string 选传 提示的内容，默认为：新版本已经准备好，是否重启应用？ + showCancel boolean 选传 是否显示取消按钮，默认为：false不显示 + cancelText string 选传 取消按钮的文字，最多4个字符 + cancelColor string 选传 取消按钮的文字颜色，必须是16进制格式的颜色字符串 + confirmText string 选传 确认按钮的文字，最多4个字符 + confirmColor string 选传 确认按钮的文字颜色，必须是16进制格式的颜色字符串 + success function 选传 接口调用成功的回调函数 + fail function 选传 接口调用失败的回调函数 + complete function 选传 接口调用结束的回调函数（调用成功、失败都会执行） + } ``` - 示例：游戏登录完成后，获取用户信息后进行打点（该示例，只是模拟该接口使用环境） + 示例：在游戏入口类中检测是否有版本更新 ```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(); + class Main { + constructor() { + this.init(); } - 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 init() { + this.checkUpdate(); } - private onGame(){ - // 用户活跃注册打点 - PCSDK.stat.active(); - // 进入游戏页面 - SceneManager.I.switchScene(GameScene); + private checkUpdate() { + // 调用SDK的checkUpdate，微信版本有更新，会自动弹出更新确认框 + PCSDK.platform.checkUpdate(); + + // 自定义更新弹出框 + /* + PCSDK.platform.checkUpdate({ + showCancel: true, + content: '客官，xxx游戏有更新了！', + cancelText: '放弃' + }); + */ } } + ``` +
+4.0 **vibrateShort** + + ```javascript + PCSDK.platform.vibrateShort(): Promise + ``` + + 定义：使手机发生较短时间的振动（15 ms）。仅在 iPhone 7 / 7 Plus 以上及 Android 机型生效 + + 参数： + + ```javascript + 无 + ``` + + 示例： + + ```javascript + PCSDK.platform.vibrateShort(); + + ``` +4.1 **vibrateLong** + + ```javascript + PCSDK.platform.vibrateShort(): Promise + ``` + + 定义：使手机发生较长时间的振动（400 ms) + + 参数： + + ```javascript + 无 + ``` + + 示例： + + ```javascript + PCSDK.platform.vibrateLong(); + ``` \ No newline at end of file diff --git a/word/噗嗤SDK（PCSDK）.xmind b/word/噗嗤SDK（PCSDK）.xmind index 3250df4..5326a58 100644 Binary files a/word/噗嗤SDK（PCSDK）.xmind and b/word/噗嗤SDK（PCSDK）.xmind differ -- libgit2 0.21.0