小川 / SdkGitbook

platform.md 22.5 KB

多平台接口模块：PCSDK.platform

2a7226b893b7a321f1c22f7d037b814665220185/outer/platform.md#">简介

所谓多平台指的是微信小游戏、QQ轻游戏、今日头条、oppo等游戏发布的平台。微信和QQ接口文档api相似度99%，微信、QQ、今日头条平台的接口api相似度80%以上，虽然相似度很高，但是仍需要针对差异性做一些处理。多平台接口模块就是想要在SDK内部去抹平了各个平台差异性的处理，达到同一个api调用，应用多个平台的作用。

此模块是参照微信小游戏提供的api进行封装的公用方法，提供了以下游戏中常用到的功能：

  1. 打开客服消息：openCustomerServiceConversation 整理来自wx.openCustomerServiceConversation

  2. 检测版本更新：checkUpdate 整理来自：wx.getUpdateManager

  3. 显示模态弹出框：showModal 整理来自：wx.showModal

  4. 复制文本：copy 整理来自：wx.setClipboardData

  5. 长震动：vibrateLong 整理来自：wx.vibrateLong

  6. 短震动：vibrateShort 整理来自：wx.vibrateShort

  7. 微信小游戏推荐弹窗组件GamePortal：isGamePortalPlaying 与 gamePortalShow 整理来自：wx.createGamePortal

  8. 微信小游戏插屏广告组件InterstitialAd：isInterstitialPlaying 与 interstitialShow 整理来自：wx.createInterstitialAd

  9. 微信小游戏推荐icon组件GameIcon：gameIconShow 与 gameIconDestroy 整理来自：wx.createGameIcon

接入API：

名称 功能说明
PCSDK.platform.openCustomerServiceConversation 进入客服会话，可打开一个普通的客服会话，也可打开客服会话发送体力、钻石和进入跳转充值等，具体用法请看
PCSDK.platform.checkUpdate 检测版本是否有更新，如果版本更新会弹出确认框
PCSDK.platform.copy 设置系统剪贴板的内容。微信小游戏调用成功后，会弹出 toast 提示"内容已复制"，持续 1.5s
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. openCustomerServiceConversation
   PCSDK.platform.openCustomerServiceConversation( params?: _CustomerServiceConversationObject ): void

定义：进入客服会话，可打开一个普通的客服会话，也可打开客服会话发送体力和进入跳转充值

参数：

   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    选传  接口调用结束的回调函数（调用成功、失败都会执行）
   }

返回值：

   void
   无

示例1：进入普通的客服会话

    PCSDK.platform.openCustomerServiceConversation();

示例2：应用场景如进入客服会话跳转领取体力、钻石等等： 示例为跳转客服领取18888钻石奖励，success函数中记录数据状态（用于客服返回，执行onShow生命周期函数时逻辑判断）。 

    // 跳转客服领取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接口，验证充值合理性并发放奖励，此接口需要后端支持。 

    // 跳转客服充值，开发者可根据示例修改，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事件
        }
    }
  1. checkUpdate
   PCSDK.platform.checkUpdate( params?: _ShowModalObject ): void

定义：检测版本是否有更新，如果版本有更新会弹出确认框，参数可不传递，不传递有版本更新会弹出下图的默认确认框；开发者可自定义弹出框的显示样式，参数与wx.showModal一模一样。 建议此api在游戏的入口调用。 sdk文件目录结构

参数：

   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   选传  接口调用结束的回调函数（调用成功、失败都会执行）
   }

返回值：

   void
   无

示例：在游戏入口类中检测是否有版本更新

1）、依照下面的示例接入checkUpdate api

    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文件目录结构 II、选择：自定义模式名称、勾选下次编译时模拟更新、选择模拟成功还是失败状态，点击确定。 sdk文件目录结构 III、开发工具会自动重新启动游戏，弹出更新框，看到弹出框接入成功。 sdk文件目录结构

  1. copy
   PCSDK.platform.copy( str: string ): Promise<any>

定义：设置系统剪贴板的内容。提示：微信小游戏调用成功后，会弹出 toast 提示"内容已复制"，持续 1.5s

参数：

   str string 必传 剪贴板的内容

返回值：

   Promise<any>
   Promise resolve复制系统剪贴板内容成功回调，reject失败回调

示例：

    PCSDK.platform.copy('这是我想要复制的内容')
        .then( ret => {
            // 打印复制的内容
            console.log(ret.data);
        })
        .catch(err => {
            console.warn('复制失败', err);
        });
  1. vibrateShort javascript PCSDK.platform.vibrateShort(): Promise<any> 定义：使手机发生较短时间的振动（15 ms）。仅在 iPhone 7 / 7 Plus 以上及 Android 机型生效 参数：
   无

示例：

   PCSDK.platform.vibrateShort();
  1. vibrateLong
   PCSDK.platform.vibrateLong(): Promise<any>

定义：使手机发生较长时间的振动（400 ms) 参数：

   无

示例：

   PCSDK.platform.vibrateLong();
  1. gamePortalShow javascript PCSDK.platform.gamePortalShow(adUnitId: string): Promise<any> 定义：传入adUnitId创建并展示小游戏推荐弹窗组件，Promise resolve创建展示成功回调，reject创建失败回调。

参数：

   adUnitId string 必传  小游戏推荐弹窗组件推荐单元id

返回值：

   Promise<any>
   Promise resolve创建展示成功回调，reject创建失败回调

示例：

    // 例子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);
    });
  1. isGamePortalPlaying
   PCSDK.platform.isGamePortalPlaying(): boolean

定义：是否正在加载小游戏推荐弹窗组件；在PCSDK.platform.gamePortalShow api内部，如果正在创建弹窗组件会在Promise reject返回错误提示信息。

参数：

   无

返回值：

   boolean

示例：

   let isPlaying = PCSDK.platform.isGamePortalPlaying();
  1. interstitialShow
   PCSDK.platform.interstitialShow(adUnitId: string): Promise<any>

定义：传入adUnitId创建并展示小游戏插屏广告组件，Promise resolve创建展示成功回调，reject创建失败回调

参数：

   adUnitId string 必传  小游戏插屏广告组件广告单元id

返回值：

   Promise<any>
   Promise resolve创建展示成功回调，reject创建失败回调

示例：

   // 例子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);
   });
  1. isInterstitialPlaying
   PCSDK.platform.isInterstitialPlaying(): boolean

定义：是否正在加载小游戏插屏广告组件；在PCSDK.platform.interstitialShow如果正在创建插屏广告会在Promise reject返回错误提示信息。

参数：

   无

返回值：

   boolean

示例：

   let isPlaying = PCSDK.platform.isInterstitialPlaying();
  1. gameIconShow javascript PCSDK.platform.gameIconShow(adUnitId: string, opts: { count: number, style: Array<_GameIconStyleItem> }): Promise<any>

定义：创建并显示小游戏推荐icon组件。

参数：

   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轴坐标
   }

返回值：

   Promise<any>
   Promise resolve创建展示成功回调，reject创建失败回调

示例：

   // 显示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失败');
                });
   }
  1. gameIconDestroy
   PCSDK.platform.gameIconDestroy(): void

定义：销毁正在展示的小游戏推荐icon组件。展示推荐icon组件广告后，请记得在页面关闭时候调用此api销毁GameIcon。

参数：

   无

返回值：

   void

示例：


   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();
   }