# 多平台接口模块：PCSDK.platform ------ #### **简介** 所谓多平台指的是微信小游戏、QQ轻游戏、今日头条、oppo等游戏发布的平台。微信和QQ接口文档api相似度99%，微信、QQ、今日头条平台的接口api相似度80%以上，虽然相似度很高，但是仍需要针对差异性做一些处理。多平台接口模块就是想要在SDK内部去抹平了各个平台差异性的处理，达到同一个api调用，应用多个平台的作用。 #### **此模块是参照微信小游戏提供的api进行封装的公用方法，提供了以下游戏中常用到的功能：** 1. **支付打点：logPay** (此模块保留logPay调用只是为了兼容已经接入的游戏，该api已经归类到【统计模块】下面的[支付打点](stat_pay.md)栏)。 2. **打开客服消息：openCustomerServiceConversation** 整理来自[wx.openCustomerServiceConversation](https://developers.weixin.qq.com/minigame/dev/api/open-api/customer-message/wx.openCustomerServiceConversation.html) 3. **检测版本更新：checkUpdate** 整理来自：[wx.getUpdateManager](https://developers.weixin.qq.com/minigame/dev/api/base/update/UpdateManager.html) 4. **显示模态弹出框：showModal** 整理来自：[wx.showModal](https://developers.weixin.qq.com/minigame/dev/api/ui/interaction/wx.showModal.html) 5. **复制文本：copy** 整理来自：[wx.setClipboardData](https://developers.weixin.qq.com/minigame/dev/api/device/clipboard/wx.setClipboardData.html) 6. **长震动：vibrateLong** 整理来自：[wx.vibrateLong](https://developers.weixin.qq.com/minigame/dev/api/device/vibrate/wx.vibrateLong.html) 7. **短震动：vibrateShort** 整理来自：[wx.vibrateShort](https://developers.weixin.qq.com/minigame/dev/api/device/vibrate/wx.vibrateShort.html) 9. **微信小游戏推荐弹窗组件GamePortal：isGamePortalPlaying 与 gamePortalShow** 整理来自：[wx.createGamePortal](https://developers.weixin.qq.com/minigame/dev/api/game-portal/GameBanner.html) 10. **微信小游戏插屏广告组件InterstitialAd：isInterstitialPlaying 与 interstitialShow** 整理来自：[wx.createInterstitialAd](https://developers.weixin.qq.com/minigame/dev/api/ad/InterstitialAd.html) 11. **微信小游戏推荐icon组件GameIcon：gameIconShow 与 gameIconDestroy** 整理来自：[wx.createGameIcon](https://developers.weixin.qq.com/minigame/dev/api/game-portal/wx.createGameIcon.html) #### **接入API：** | **名称** | **功能说明** | | ------------------------ | ------------------------------------------------------------ | | PCSDK.platform.logPay | 支付统计打点，支付完成（取消、成功、失败）的打点 | | PCSDK.platform.openCustomerServiceConversation | 进入客服会话，可打开一个普通的客服会话，也可打开客服会话发送体力、钻石和进入跳转充值等，[具体用法请看](platform.md#service)| | PCSDK.platform.checkUpdate | 检测版本是否有更新，如果版本更新会弹出确认框 | | PCSDK.platform.vibrateShort | 使手机发生较短时间的振动（15 ms） | | PCSDK.platform.vibrateLong | 使手机发生较长时间的振动（400 ms) | | PCSDK.platform.gamePortalShow | 传入adUnitId创建并展示小游戏推荐弹窗组件 | | PCSDK.platform.isGamePortalPlaying | 是否正在加载小游戏推荐弹窗组件 | | PCSDK.platform.interstitialShow | 传入adUnitId创建并展示小游戏插屏广告组件 | | PCSDK.platform.isInterstitialPlaying | 是否正在加载小游戏插屏广告组件 | | PCSDK.platform.gameIconShow | 创建并显示小游戏推荐icon组件 | | PCSDK.platform.gameIconDestroy | 销毁正在展示的小游戏推荐icon组件 |
1. **logPay** ```javascript 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 无 ``` 示例：客户端游戏支付完成后上报支付打点，下例只是演示logPay用法 ```javascript 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. **openCustomerServiceConversation** ```javascript PCSDK.platform.openCustomerServiceConversation( params?: _CustomerServiceConversationObject ): void ``` 定义：进入客服会话，可打开一个普通的客服会话，也可打开客服会话发送体力和进入跳转充值 参数： ```javascript 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 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接口，验证充值合理性并发放奖励，**此接口需要后端支持**。 ```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.platform.checkUpdate( params?: _ShowModalObject ): void ``` 定义：检测版本是否有更新，如果版本有更新会弹出确认框，参数可不传递，不传递有版本更新会弹出下图的默认确认框；开发者可自定义弹出框的显示样式，参数与[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 选传 接口调用结束的回调函数（调用成功、失败都会执行） } ``` 示例：在游戏入口类中检测是否有版本更新 1）、依照下面的示例接入checkUpdate api ```javascript class Main { constructor() { this.init(); } private init() { this.checkUpdate(); } private checkUpdate() { // 调用SDK的checkUpdate，微信版本有更新，会自动弹出更新确认框 PCSDK.platform.checkUpdate(); // 自定义更新弹出框 /* PCSDK.platform.checkUpdate({ showCancel: true, content: '客官，xxx游戏有更新了！', cancelText: '放弃' }); */ } } ``` 2）、接入代码完毕后，按照下图的操作本地开发工具调试是否接入成功。 I、选择：添加编译模式。 ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_030.png "🔍点击查看大图") II、选择：自定义模式名称、勾选下次编译时模拟更新、选择模拟成功还是失败状态，点击确定。 ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_031.png "🔍点击查看大图") III、开发工具会自动重新启动游戏，弹出更新框，看到弹出框接入成功。 ![sdk文件目录结构](https://dep.miso-lab.com/sdkword/sdk_032.png "🔍点击查看大图")
4. **vibrateShort** ```javascript PCSDK.platform.vibrateShort(): Promise ``` 定义：使手机发生较短时间的振动（15 ms）。仅在 iPhone 7 / 7 Plus 以上及 Android 机型生效 参数： ```javascript 无 ``` 示例： ```javascript PCSDK.platform.vibrateShort(); ``` 5. **vibrateLong** ```javascript PCSDK.platform.vibrateLong(): Promise ``` 定义：使手机发生较长时间的振动（400 ms) 参数： ```javascript 无 ``` 示例： ```javascript PCSDK.platform.vibrateLong(); ```
6. **gamePortalShow** ```javascript PCSDK.platform.gamePortalShow(adUnitId: string): Promise ``` 定义：传入adUnitId创建并展示小游戏推荐弹窗组件，Promise resolve创建展示成功回调，reject创建失败回调。 参数： ```javascript adUnitId string 必传 小游戏推荐弹窗组件推荐单元id ``` 返回值： ```javascript Promise Promise resolve创建展示成功回调，reject创建失败回到 ``` 示例： ```javascript // 例子1：显示弹窗组件 let adUnitId: string = 'PBgAAgPWNXGtCwcA'; PCSDK.platform.gamePortalShow(adUnitId); // 例子2：显示推荐弹窗组件，如果显示不成功，则显示小游戏插屏广告，插屏广告api使用请继续往下看。 let adUnitId: string = 'PBgAAgPWNXGtCwcA'; PCSDK.platform.gamePortalShow(adUnitId).catch(err => { // 推荐弹窗组件显示不成功显示插屏广告 adUnitId = 'adunit-4da0ec77513f8eea'; PCSDK.platform.interstitialShow(adUnitId); }); ``` 7. **isGamePortalPlaying** ```javascript PCSDK.platform.isGamePortalPlaying(): boolean ``` 定义：是否正在加载小游戏推荐弹窗组件；在PCSDK.platform.gamePortalShow api内部，如果正在创建弹窗组件会在Promise reject返回错误提示信息。 参数： ```javascript 无 ``` 返回值： ```javascript boolean ``` 示例： ```javascript let isPlaying = PCSDK.platform.isGamePortalPlaying(); ```
8. **interstitialShow** ```javascript PCSDK.platform.interstitialShow(adUnitId: string): Promise ``` 定义：传入adUnitId创建并展示小游戏插屏广告组件，Promise resolve创建展示成功回调，reject创建失败回调 参数： ```javascript adUnitId string 必传 小游戏插屏广告组件广告单元id ``` 返回值： ```javascript Promise Promise resolve创建展示成功回调，reject创建失败回到 ``` 示例： ```javascript // 例子1：显示插屏广告组件 let adUnitId: string = 'adunit-4da0ec77513f8eea'; PCSDK.platform.interstitialShow(adUnitId); // 例子2：显示插屏广告组件，如果显示不成功，则显示小游戏推荐弹窗组件。 let adUnitId: string = 'adunit-4da0ec77513f8eea'; PCSDK.platform.interstitialShow(adUnitId).catch( err => { // 加载不成功显示小游戏推荐弹窗组件 adUnitId = 'PBgAAgPWNXGtCwcA'; PCSDK.platform.gamePortalShow(adUnitId); }); ``` 9. **isInterstitialPlaying** ```javascript PCSDK.platform.isInterstitialPlaying(): boolean ``` 定义：是否正在加载小游戏插屏广告组件；在PCSDK.platform.interstitialShow如果正在创建插屏广告会在Promise reject返回错误提示信息。 参数： ```javascript 无 ``` 返回值： ```javascript boolean ``` 示例： ```javascript let isPlaying = PCSDK.platform.isInterstitialPlaying(); ```
10. **gameIconShow** ```javascript PCSDK.platform.gameIconShow(adUnitId: string, opts: { count: number, style: Array<_GameIconStyleItem> }): Promise ``` 定义：创建并显示小游戏推荐icon组件。 参数： ```javascript adUnitId string 必传 小游戏推荐icon组件广告单元id opts object 必传 扩展参数，目前支持count和style两个属性值 { count number 必传 游戏icon的数量，请注意，正式版下面渲染出来的icon数量会小于等于count，请注册做好样式兼容 style Array<_GameIconStyleItem> 必传 数组的每一项可以针对对应的icon设置位置和样式等信息，style的每一项称为_GameIconStyleItem } Object _GameIconStyleItem：单个游戏icon的位置和样式信息 { appNameHidden boolean 必传 游戏名称是否隐藏 color string 必传 游戏名称的颜色色值 size number 必传 游戏icon的宽高值 borderWidth number 必传 游戏icon的border尺寸 borderColor string 必传 游戏icon的border颜色色值 left number 必传 游戏icon的X轴坐标 top number 必传 游戏icon的Y轴坐标 } ``` 返回值： ```javascript Promise Promise resolve创建展示成功回调，reject创建失败回到 ``` 示例： ```javascript // 显示1个推荐icon组件 private showGameIcon(){ let adUnitId: string = 'PBgAAgPWNXGkQ4p0'; let {windowWidth} = PCSDK.platform.getSystemData(); PCSDK.platform.gameIconShow(adUnitId, { count: 1, style: [ { appNameHidden: false, color: "#FF0000", size: 50, borderWidth: 0, borderColor: "#FF0000", left: (windowWidth / 750) * 550, top: (windowWidth / 750) * 150 } ] }) .then(() => { // console.warn('显示GameIcon成功'); }) .catch((err) => { // console.warn('显示GameIcon失败'); }); } ``` 11. **gameIconDestroy** ```javascript PCSDK.platform.gameIconDestroy(): void ``` 定义：销毁正在展示的小游戏推荐icon组件。展示推荐icon组件广告后，请记得在页面关闭时候调用此api销毁GameIcon。 参数： ```javascript 无 ``` 返回值： ```javascript void ``` 示例： ```javascript private open(){ super.open(); this.showGameIcon(); } private close(){ super.close(); this.destoryGameIcon(); } // 显示2个推荐icon组件 private showGameIcon(){ let adUnitId: string = 'PBgAAgPWNXGkQ4p0'; let {windowWidth} = PCSDK.platform.getSystemData(); PCSDK.platform.gameIconShow(adUnitId, { count: 2, style: [ { appNameHidden: false, color: "#FF0000", size: 50, borderWidth: 0, borderColor: "#FF0000", left: (windowWidth / 750) * 450, top: (windowWidth / 750) * 150 }, { appNameHidden: false, color: "#FF0000", size: 50, borderWidth: 0, borderColor: "#FF0000", left: (windowWidth / 750) * 550, top: (windowWidth / 750) * 150 } ] }) .then(() => { // console.warn('显示GameIcon成功'); }) .catch((err) => { // console.warn('显示GameIcon失败'); }); } // 销毁展示创建的GameIcon组件 private destoryGameIcon(){ PCSDK.platform.gameIconDestroy(); } ```