Cocos Creator插件SDK接入指南 | 微游H5出海开发者中心

修改历史

时间	版本
2024/08/06	1.0.1
2024/10/23	1.0.2

注意：针对非联网游戏类型，在遵循欧盟GDPR法规要求的前提下，建议采取以下数据管理措施：游戏运行过程中产生的用户数据应存储于设备本地，避免向服务器端上传任何数据；若当前游戏存在远程资源分包加载机制，需将其调整为本地资源分包模式，确保所有功能模块均无需依赖远程数据交互。

插件下载

在资源下载页面，根据自己的引擎版本去下载对应的的插件工程。

安装SDK插件

这里以cocoscreator 3.8为例：
1.导入插件包，点击扩展->扩展管理器。

选择项目，然后点击+号，导入扩展包。

导入成功后，打开扩展。

4.扩展打开后，会在菜单栏中增加微游SDK，点击 微游SDK->控制面板，打开控制面板。

控制面板如下图：

点击拷贝按钮后，SDK目录将被拷贝到assets目录下，另外声明文件夹minigame-types文件会被拷贝到根目录，如图:

此时就可以接入广告等接口。

5.打包之前勾选构建微游包，打包平台选择web-mobile后，就可以自动构建出微游包，若不想构建微游包，只需将构建微游包前面的✅去掉。

接入

当游戏结束加载，进入主场景后，在主场景初始化的时候调用 setGameReadyAsync

onLoad () {
	minigame.setGameReadyAsync();
}

使用前在游戏初始化地方(游戏入口)初始化SDK，并且实现声音控制的方法，由SDK统一管理激励和插屏广告播放期间的游戏音效：

MiniGameSDK.init();
MiniGameSDK.pauseSound = () => {
  // todo 处理关闭声音
}

MiniGameSDK.resumeSound = () => {
  // todo 处理恢复声音
}

初始化完成后，就可以调用相应的接口。

下面就是SDK接口的介绍：

语言

getLocale()

const lang = MiniGameSDK.getLocale(); // '假设当前环境是美国英语，则返回en_US' 
// 判断当前语言是否为英语
if (lang.includes("en")){
	console.info("current language is en");
}
// 或
if (lang.substr(0, 2) === "en"){
	console.info("current language is en");
}

数据存储（必接）

数据保存

setDataAsync (data: Object): Promise<void>

minigame.player
  .setDataAsync({
    achievements: ['medal1', 'medal2', 'medal3'],
    currentLife: 300,
  })
  .then(function() {
    console.log('data is set');
  });

获取数据

getDataAsync (keys: string[]): Promise<Object>

minigame.player
  .getDataAsync(['achievements', 'currentLife'])
  .then(function(data) {
     console.log('data is loaded');
     var achievements = data['achievements'];
     var currentLife = data['currentLife'];
  });

===========================================

以下接口正常情况下不用接入，除非我们运营有说接入才要接入。

打点

事件类型	事件名称	事件说明	事件定义	属性说明
游戏进度	创建角色	用户正式进入游戏开始游玩	create_role	游戏内创角时传，无角色的游戏可对应到游戏就绪用户可玩时传
游戏进度	完成关卡x	关卡记录	levelx	用户完成关卡x时传，若无关卡可报next_round
游戏进度	结算	结算弹窗弹出	minis_settlement	结算弹窗弹出时埋点，弹窗需要在底部空出一个空间，高度至少150px，如下图
游戏进度	关闭结算	关闭结算弹窗	minis_close_settlement	关闭结算弹窗时埋点

企业微信截图_5778b387-7551-4b0b-bcf6-7ed52a0cae03.png

onGameEvent(eventName: string, label: string)

eventName 事件名称
label 事件标签

// level: 关卡事件 ，level01：第一个关
MiniGameSDK.onGameEvent("level", "level01");

支付

内购接口

onReady(callBack: Function): void
设置一个回调，callback在支付可用时，会被触发，onReady一般在进入游戏后调用，callback里面可以先处理下补单的操作。

Examples:

minigame.payments.onReady(function () {
    // 先获取未消耗的订单
    minigame.payments.getPurchasesAsync().then(function(purchases) {
      console.log(purchases);
      // 遍历订单
      purchases.forEach((purchase) => {
          // 消耗订单
           minigame.payments.consumePurchaseAsync(purchase.purchaseToken)
                .then(function () {
                  // 消耗成功
                  // 游戏发送奖励给玩家
                });
          })
    });
});

getCatalogAsync(): Promise<Product[]>
获取游戏的产品目录

Examples:

minigame.payments.getCatalogAsync().then(function (catalog) {   
  console.log(catalog); // [{productID: '12345', ...}, ...]  
});

purchaseAsync(purchaseConfig: PurchaseConfig): Promise<Purchase>
开始特定产品的购买流程, productID在接入的时候，我们会进行提供。

Examples:
```
minigame.payments.purchaseAsync(
{  productID: '12345',  
   developerPayload: '{"usdPrice":"xxx"}' // developerPayload为json字符串
}).then(function (purchase) {
  console.log(purchase);// {productID: '12345', purchaseToken: '54321', developerPayload: '{"usdPrice":"xxx"}', ...}
});
```
注意：developerPayload必传usdPrice，表示该商品的美元价格，比如0.99
如果是后端发货的游戏还需要上传游戏订单号，有些单机游戏也有支付，可以不传order
```
developerPayload: '{"usdPrice":"xxx", "orderId": "xxxxxxxxxxxxx"}'
```
后端发货的游戏需要接入后端支付接入文档

getPurchasesAsync(): Promise<Purchase[]>
获取玩家未消费的所有购买商品

Examples:

minigame.payments.getPurchasesAsync().then(function (purchases) {
  console.log(purchase);
  // [{productID: '12345', ...}, ...]
});

consumePurchaseAsync(purchaseToken: string): Promise<void>
消费当前玩家拥有的特定购买商品

Examples:

minigame.payments.consumePurchaseAsync('54321').then(function () {
  // 消耗成功
  // 游戏发送奖励给玩家
});

注意purchaseAsync支付成功后，需要马上调用消耗接口才能发放奖励,例如：

minigame.payments.purchaseAsync({
  productID: '12345',
  developerPayload: '{"usdPrice":"xxx","orderId": "xxxxxxxxxxxxx"}' // developerPayload为json字符串
}).then(function (purchase) {         
    minigame.payments.consumePurchaseAsync(purchase.purchaseToken)
      .then(function () {
          // 消耗成功
          // 游戏发送奖励给玩家
        });
});

2.类型定义

支付参数：

export interface PurchaseConfig {
  /**
   * 产品id
   */
  productID: string;
  /**
   * 可选参数，开发人员指定的内容，将包含在返回的购买签名请求里。
   */
  developerPayload?: string;
}

商品信息：

export interface Product {
  /**
   * 产品的名称
   */
  title: string;
  /**
   * 产品的游戏指定id
   */
  productID: string;
  /**
   * 产品的描述
   */
  description?: string;
  /**
   * 产品相关图片的链接
   */
  imageURI?: string;
  /**
   * 产品的价格
   */
  price: string;
  /**
   * 产品的货币代码，字符串类型
   */
  priceCurrencyCode: string;
  /**
   * 产品的价格，数字类型
   */
  priceAmount: number;
}

支付返回：

export interface Purchase {
  /**
   * 可选参数，开发人员指定的内容，将包含在返回的购买签名请求里。
   */
  developerPayload?: string;
  /**
   * 购买的当前状态，如“收费”或“退款”
   */
  paymentActionType: string;
  /**
   * 购买交易的标识符
   */
  paymentID: string;
  /**
   * 产品id
   */
  productID: string;
  /**
   * 包含与所购买项目关联的本地金额和货币
   */
  purchasePrice: string;
  /**
   * 发生购买时的Unix时间戳
   */
  purchaseTime: string;
  /**
   * 代表可用于消费者购买时的token
   */
  purchaseToken: string;
  /**
   * 购买请求的服务器签名编码
   */
  signedRequest: string;
}

onShare(shareConfig: SharePayload, callback: BoolCallback)

shareConfig 分享参数配置。
callback 分享回调，参数为是否分享成功。

MiniGameSDK.onShare({
  image: base64Picture, // base64-encoded picture
  text: 'your share text'
}, (isSuccess: boolean) => {
  if (isSuccess) {
    // console.info("minigame share success");
  } else {
    // console.error("minigame share failed");
  }
});

快捷方式

createShortcut(shortcutCallback: BoolCallback)

shortcutCallback 分享回调，参数为是否分享成功。

MiniGameSDK.createShortcut((isSuccess: boolean) => {
  if (isSuccess) {
    // console.info("minigame createShortcut success");
  } else {
    // console.error("minigame createShortcut failed");
  }
});

模拟线上环境

步骤：
1.打开https://developers.minigame.com/zh/testgame 。
2.将minigame.json中的isTest设置为false。
3.将接入SDK后的本地游戏链接，放进页面的地址栏中。

4.点击开始测试后，就可以模拟线上环境测试。

注意：若是Cocos Creator的游戏，接入SDK后，就可以直接用cocoscreator编辑器运行后的地址进行测试，如http://localhost:7457

大纲