SDK对接文档

主题

WARNING

💡 模块名:GameHelper.Pay

描述 ​

本系统提供内购支持；为了减小 SDK 包体，本模块设计成了一个可选模块，使用前请确认 SDK 包含支付模块。

各平台设备端支持情况

平台安卓IOS
微信√√
字节√√

接入说明 ​

准备工作 ​

请确保在 SDK 初始化时正确传入 gameConfig 参数，首次接入时建议打开 gameConfig.json 文件搜索"payConfig"关键字，若未检测到该关键字表示缺少支付配置，联系配置文件提供方获取完整的配置。

关于支付事件 ​

WARNING

💡 注意:

  • 支付模块已在接口内自动上报以下支付事件，游戏层无需上报：
  • pay_click 支付按钮点击
  • pay_success 支付成功
  • pay_fail 支付失败
  • in_app_purchase 支付流程事件

iOSpay 参数 ​

支持平台：微信

说明

该参数为一个可实时修改值的在线参数，仅在微信平台的 ios 设备上生效，配置 1 时表示隐藏支付入口，配为 0 时表示显示支付入口，用于控制 IOS 端是否显示支付入口；SDK 将其封装为 showPay 参数，游戏层只需要调用 GameHelper.Pay.showPay，根据结果处理游戏 UI；

获取商品列表 ​

支付组件会从支付服务器或者本地获取商品列表并返回给游戏；建议游戏内的商品名称、价格等都从商品列表中的 prodName、priceCny 属性读取和显示。

详细接口说明

购买商品 ​

调用购买商品接口时传入商品 ID，在 success 和 fail 回调内分别执行购买成功和购买失败的逻辑，普通小游戏可以在 success 回调内直接发放奖励，若为强联网游戏，请在收到游戏服务器的发货通知时发放奖励。

购买成功的 success 回调会返回一个对象，包含 prodId（商品 id）、prodName（商品名称）、price(单位:元)、currency(货币符号)、orderNo(自定义订单号)五个属性。

详细接口说明

异常订单查询 ​

建议每次启动游戏时调用一次异常订单查询接口，若存在未发货的异常订单，会将这些订单的商品 ID 以数组形式返回，需要根据返回的商品 ID 发放对应奖励。

javascript
GameHelper.Pay.queryOrder({
  success: (res) => {
    console.log("查询的异常订单有", res);
  },
});

强联网游戏上报道具发放事件（仅强联网游戏需要上报） ​

因强联网游戏是游戏服务器通知游戏客户端发货，所以当游戏客户端发货通知后，修改支付服务器的道具发货状态；

javascript
GameHelper.Pay.buySuccessFromUser("1254455445");

支付测试 ​

  • 微信平台安卓端和 IOS 端支付流程不同

  • 首次接入支付或者新增商品时可修改价格为较低数额，方便测试和减小测试数据对正式支付数据的影响

  • 修改价格时请注意：由于微信平台和字节平台对安卓端有金额限制，最低价格只能设置为 1 元；微信 IOS 端无限制，可设置为 0.01 元

接口索引 ​

属性 ​

属性类型描述值
showPayboolean是否显示支付入口（按钮）true:显示
false：不显示

showPay在各平台返回值逻辑处理如下：

微信

  • 安卓端固定返回 true
  • ios 端会根据 iOSpay 参数值返回对应 boolean 值

字节

  • 安卓端固定返回 true，ios 端固定返回 false

方法 ​

​

功能描述

获取所有商品信息列表

参数

Object callbacks

属性类型默认值是否必填说明
successfunction/是成功获取商品列表回调
failfunction/否商品列表获取失败回调

callbacks.success 回调函数

参数

Object res

属性类型说明
具体的商品 id1Object prodInfo成功获取商品列表回调
具体的商品 id2Object prodInfo成功获取商品列表回调
具体的商品 id3Object prodInfo成功获取商品列表回调
.........

Object prodInfo

属性类型说明
prodNamestring商品名称
priceCnystring商品的人民币价格
pricestring商品的游戏币价格
currencystring仅微信平台返回，货币符号
ratenumber仅微信平台返回，换算比率； priceCny/price 的结果，一般是 1 , 0.1 , 0.01
zoneIdstring仅微信平台返回，游戏币分区
prodDescstring仅字节平台返回，商品描述

示例

javascript
GameHelper.Pay.getProductInfo({
  success: (res) => {
    /**
         * res为所有商品信息的对象，如下：
            {
                "商品ID1"： {
                    prodName: "商品名称",
                    price: "商品价格",  微信平台该参数表示游戏币价格，为人民币按照比率换算后的游戏币价格
                    priceCny: "人民币价格",  仅微信平台会返回

                    // 以下参数仅微信平台会返回
                    currency: "CNY",
                    prodId: "wx.jycs.yongjiulirun",
                    rate: 0.1,
                    zoneId: "tcdsprod001",

                    // 以下参数仅字节平台会返回
                    prodDesc: "商品描述"
                }
                "商品ID2"： {
                    ...
                }
            }
         */

    // 使用商品价格参数时需注意，若需要使用单位为元的人民币价格参数，可优先读取priceCny属性，
    // 当priceCny未返回时以price属性作为人民币价格
    console.log("获取到的商品列表是", res);
  },
  fail: () => {
    console.log("获取商品列表失败");
  },
});

​

功能描述

购买商品

参数

Object orderCall

属性类型默认值是否必填说明
prodIdstring/是商品 id
successfunction/是成功获取商品列表回调
failfunction/否商品列表获取失败回调
eventPropertiesPAY_EVENT_PROPERTY/否自定义的支付事件属性集合

orderCall.success 回调函数

参数

Object res

属性类型说明
prodIdstring商品 id
prodNamestring商品名称
pricestring商品的人民币价格
currencystring货币符号
orderNostring支付服务器生成的自定义订单号

PAY_EVENT_PROPERTY

参数名称类型是否必填说明
pay_paramstring否自定义的字符串类型的属性参数
pay_param1
pay_param2
pay_param3
pay_param4
pay_typenumber否自定义的数字类型的属性参数
pay_type1
pay_type2
pay_type3
pay_type4

示例

javascript
GameHelper.Pay.createOrder({
  prodId: "商品ID", // 请修改为正式的商品ID
  success: (res) => {
    GameHelper.CCComFun.showToast({
      title: "商品购买成功",
    });
    console.log("购买成功，回调参数是", res);
  },
  fail() {
    console.log("购买失败");
  },
  eventProperties: {
    pay_param: "payParamTest",
    pay_param1: "payParamTest1",
    pay_param2: "payParamTest3",
    pay_param3: "payParamTest3",
    pay_param4: "payParamTest4",
    pay_type: 0,
    pay_type1: 1,
    pay_type2: 1,
    pay_type3: 1,
    pay_type4: 1,
  },
});

​

功能描述

查询已支付未发货的订单

参数

Object callback

属性类型默认值是否必填说明
successfunction/是查询到异常订单时执行

callback.success 回调函数

参数

Array<string> res

javascript
GameHelper.Pay.queryOrder({
  success: (res) => {
    console.log("查询的异常订单有", res);
    for (let i = 0, l = res.length; i < l; i++) {
      console.log("未发货的商品id是：", res[i]);
    }
  },
});

​

功能描述

仅强联网游戏需要调用，当强联网游戏收到游戏服务器的发货通知后，调用本接口上报道具发货状态

参数

string orderId

支付服务端返回的商品 id，由游戏服务器通知游戏客户端发货时一并下发

F&Q ​

Q:点击支付按钮后，出现“当前网络环境异常，请稍后再试”的提示

A:在控制台搜索“”关键字，检查所点击的商品按钮对应的商品 id 是否包含在 data 属性下。

点我快速对接