跳到主要内容

开发指南

查询商品信息​

这里的商品信息是指【苹果商品信息】、【谷歌商品信息】和 【Steam 商品信息】，不支持【网页商品信息】。通过此方法，传入对应平台的商品集合 productIds，可查询游戏在 Apple Store/Google Play/Steam 平台中设定的内购商品包含货币符号、货币价格等 sku 信息，具体信息可参见下文 商品数据结构定义。

/**
 * 根据 product ids 查询商品列表
 *
 * @param productIds      需要查询的商品 ID 集合 （Google Play 定义的商品 ID）
 * @param paymentCallback 支付结果回调
 */
XDGPayment.queryWithProductIds(List<String> productIds, XDGPaymentCallback<List<GoogleProductDetails>> paymentCallback)

商品数据结构定义​

public class GoogleProductDetails {
    private GoogleProductDetails() {
    }

    /**
     * 原始 json 字符串
     */
    private String originString;
    /**
     * 商品描述
     */
    private String description;
    /**
     * 商品名称
     */
    private String name;
    /**
     * 商品 ID
     */
    private String productId;
    /**
     * Google 结算库 BillingClient.ProductType 的类型: BillingClient.ProductType.INAPP(inapp)、BillingClient.ProductType.SUBS(subs)
     */
    private String productType;
    /**
     * 正在销售的产品的标题
     */
    private String title;
    /**
     * 一次性购买商品详情
     */
    private GoogleOneTimePurchaseOfferDetails googleOneTimePurchaseOfferDetails;

    /**
     * 获取商品描述
     * @return 商品描述
     */
    public String getDescription() {
        return description;
    }

    /**
     * 获取商品名称
     * @return 商品名称
     */
    public String getName() {
        return name;
    }

    /**
     * 获取商品 ID
     * @return 商品 ID
     */
    public String getProductId() {
        return productId;
    }

    /**
     * 获取商品类型
     * @return 商品类型（Google 结算库 BillingClient.ProductType 的类型: BillingClient.ProductType.INAPP(inapp)、BillingClient.ProductType.SUBS(subs) 的具体值）
     */
    public String getProductType() {
        return productType;
    }

    /**
     * 获取正在销售的产品的标题
     * @return 正在销售的产品的标题
     */
    public String getTitle() {
        return title;
    }

    /**
     * 获取一次性商品详细信息
     * @return 一次性商品详细信息
     */
    public GoogleOneTimePurchaseOfferDetails getGoogleOneTimePurchaseOfferDetails() {
        return googleOneTimePurchaseOfferDetails;
    }

    /**
     * 原始 json 字符串
     * @return String
     */
    @NonNull
    @Override
    public String toString() {
        return originString;
    }

    /**
     * 一次性商品数据结构定义
     */
    public static class GoogleOneTimePurchaseOfferDetails {
        /**
         * 格式化的付款价格，包括其货币符号
         */
        private final String formattedPrice;
        /**
         * 以微单位表示的支付价格，其中 1,000,000 微单位等于一个货币单位。
         */
        private final long priceAmountMicros;
        /**
         * ISO 4217 货币代码的价格
         */
        private final String priceCurrencyCode;

        /**
         * 返回带有货币符号的价格
         * @return formatted price for the payment, including its currency sign
         */
        public String getFormattedPrice() {
            return formattedPrice;
        }

        /**
         * 返回 1 微分为单位的价格
         * @return the price for the payment in micro-units, where 1,000,000 micro-units equal one unit of the currency.
         */
        public long getPriceAmountMicros() {
            return priceAmountMicros;
        }

        /**
         * 返回 ISO 4217 标准的价格
         * @return ISO 4217 currency code for price.
         */
        public String getPriceCurrencyCode() {
            return priceCurrencyCode;
        }
    }
}

商品支付​

这里支付指的是【苹果支付】，【谷歌支付】和【Steam 支付】

  • 苹果和谷歌支付需要同时在苹果或谷歌后台和 XDSDK 平台中配置商品信息，在接口中使用的 productId 为苹果或谷歌后台的商品 ID
  • Steam 支付则只需要在 XDSDK 平台配置商品信息，在接口中使用的 productId 为平台配置的商品 ID

SDK 会在对应平台调用 Apple/Google/Steam 的支付进行商品的购买。游戏传入的 orderId 、serverId、roleId、ext 字段会在支付完成时通过 s2s 的形式透传回游戏的 Server 端以便游戏可对支付进行校验。

信息
  • 这里的回调只当做【支付完成】看待，【支付成功】需要对接XDServer后，以服务端推送信息为准。
  • 由于 Apple 支付票据有概率会出现多票据合并的情况，此时会丢失游戏传入的 orderId，并由平台随机生成一个唯一的 orderId。
/**
 * 商品支付
 *
 * @param orderId 订单 ID。游戏侧订单号，服务端支付回调会包含该字段,如无该字段，传空
 * @param productId 商品 ID。Google Play 定义的商品 ID
 * @param roleId 角色 ID。支付角色 ID，服务端支付回调会包含该字段
 * @param serverId 服务器 ID。所在服务器 ID，不能有特殊字符，服务端支付回调会包含该字段
 * @param ext 附加信息。服务端支付回调会包含该字段
 * @param paymentCallback 支付结果回调
 */
XDGPayment.payWithProduct(String orderId, String productId, String roleId, String serverId, String ext, XDGPaymentCallback<Object> paymentCallback);

订单数据结构定义​


网页支付(Android、PC)​

安卓未上架 Google Play 平台的游戏或者 PC 平台的游戏可使用网页支付的形式进行游戏内的商品购买，同样的游戏定义的商品信息需要在平台中进行配置。 在网页支付中，因支付渠道回调可能存在延迟或用户误触关闭按钮的缘故，SDK 的支付回调的含义仅包含「支付完成」、「支付取消」、「其他错误」，游戏可通过回调作为触发点，通过轮询的方式查询支付最终的结果。

这里的回调也是当做【支付完成】看待，【支付成功】需要对接 XDServer 后，以服务端推送信息为准！

/**
 * 网页支付
 *
 * @param orderId         订单 ID。游戏侧订单号，服务端支付回调会包含该字段，如无该字段，传空。
 * @param productId       商品 ID。游戏的商品ID，必填
 * @param productName     商品名称。用于内嵌支付内部显示，必填
 * @param payAmount       商品价格，必填
 * @param roleId          角色 ID。支付角色 ID，服务端支付回调会包含该字段，必填
 * @param serverId        服务器 ID。所在服务器 ID，不能有特殊字符，服务端支付回调会包含该字段，必填
 * @param extras          附加信息。服务端支付回调会包含该字段，必填
 * @param paymentCallback 支付结果回调
 */
XDGPayment.payWithWeb(String orderId, 
                      String productId, 
                      String productName,
                      double payAmount,
                      String roleId, 
                      String serverId, 
                      String extras, 
                      XDGPaymentCallback<Object> paymentCallback);

public static class PaymentResponseCode {
    public final static int OK = 0x00000000; // 支付完成
    public final static int ERROR = 0xffffffff; // 支付错误
    public final static int NETWORK_ERROR = 0xfffffffe; // 网络错误
    public final static int USER_CANCEL = 0x00000001; // 支付取消
    public final static int PURCHASE_PROCESSING = 0x00000002; // 支付处理中
}

Android 原生支付（国内）​

XDSDK 在 6.10.1 的版本开始针对 Android 平台增加了支付宝、微信的原生支付，内部会判断是否在 TapTap 沙盒 或 TapTap 云玩 环境，在此环境会继续走网页支付的流程，游戏在国内环境中可调用下列方法进行支付宝、微信的原生支付。


// 支付参数指定
PayDetailsParams params = PayDetailsParams.newBuilder()
        .setGameOrderId(orderId) // 游戏订单 ID。游戏侧订单号，服务端支付回调会包含该字段，不建议为空，如无该字段，传空
        .setProductId(productId) // 游戏商品 ID。不可为空
        .setProductName(productName) // 游戏商品名称。走 Web 支付时 UI 预显示字段，可为空
        .setPayAmount(payAmount) // 商品价格。单位（元），走 Web 支付时 UI 预显示字段，可为 0
        .setRoleId(roleId) // 游戏角色 ID。支付角色 ID，服务端支付回调会包含该字段
        .setServerId(serverId) // 游戏服务器 ID。所在服务器 ID，不能有特殊字符，服务端支付回调会包含该字段
        .setExt(ext) // 附加参数。服务端支付回调会包含该字段
        .build();

// SDK 内置 UI 支付
XDGPayment.pay(params, new XDGPaymentCallback<Object>() {
    @Override
    public void onPaymentCallback(XDGPaymentResult result, Object data) {
        if (result != null) {
            int code = result.code;
            if (com.xd.intl.payment.constant.Constants.PaymentResponseCode.OK == code) {
                // 支付成功    
            } else if (com.xd.intl.payment.constant.Constants.PaymentResponseCode.USER_CANCEL == code) {
                // 支付取消
            } else {
                // 支付失败
                Log.e("支付失败：code = " + code + ", message = " + result.debugMessage)
            }   
        }
    }
});


String payType = PayType.WECHAT_PAY // 指定微信支付方式，支付宝支付方式为：PayType.ALIPAY
// 无 UI 支付
XDGPayment.pay(payType, params, new XDGPaymentCallback<Object>() {
    @Override
    public void onPaymentCallback(XDGPaymentResult result, Object data) {
        if (result != null) {
            int code = result.code;
            if (com.xd.intl.payment.constant.Constants.PaymentResponseCode.OK == code) {
                // 支付成功    
            } else if (com.xd.intl.payment.constant.Constants.PaymentResponseCode.USER_CANCEL == code) {
                // 支付取消
            } else {
                // 支付失败
                Log.e("支付失败：code = " + code + ", message = " + result.debugMessage)
            }
        }
    }
});

应用外购买或掉单​

当游戏需要支持 Apple 提供的商店兑换码（暂不支持 Google 商店）进行内购或者处理异常情况下的消费掉单时，需要使用如下的两个方法进行处理。

首先使用查询接口获取当前已知的兑换码订单或者掉单数据，游戏需要通过返回结果内的数据来和玩家确认商品信息和发放角色，然后使用兑换或补单接口进行订单确认和消费。

查询订单数据​

// 暂不支持

礼包码兑换或掉单补单​

在上述方法中返回的未完成订单，游戏可传入对应的参数进行 Apple/Google 的商品消费确认以保证用户购买的商品正常使用。

// 暂不支持