跳到主要内容

开发指南

查询商品信息​

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

// PaymentActivity.java

import com.xd.intl.payment.XDGPayment;
import com.xd.intl.payment.callback.XDGPaymentCallback;
import com.xd.intl.payment.constant.Constants;
import com.xd.intl.payment.entities.GoogleProductDetails;
import com.xd.intl.payment.wallet.XDGPaymentResult;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

// ...

private void queryProductIds() {
    // 需要查询的商品 ID 集合 （Google Play 定义的商品 ID）
    List<String> productIds = new ArrayList<>(Arrays.asList("product1", "product2"));
    // 支付结果回调
    XDGPaymentCallback<List<GoogleProductDetails>> callback = new XDGPaymentCallback<List<GoogleProductDetails>>() {
        @Override
        public void onPaymentCallback(XDGPaymentResult result, List<GoogleProductDetails> data) {
            if (result.code == Constants.PaymentResponseCode.OK) {
                if (data != null && !data.isEmpty()) {
                    // 查询成功
                    // queryProductsSuccess();
                } else {
                    // 查询商品为空
                }
            } else {
                // 查询失败
            }
        }
    };
    XDGPayment.queryWithProductIds(productIds, callback);
}

// ...

商品数据结构定义​

详情请参考 GoogleProductDetails 类。

商店平台支付​

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

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

SDK 会在对应平台调用系统级别的支付功能进行商品的购买。游戏传入的支付参数会在支付完成时通过 s2s 的形式透传回游戏的 Server 端以便游戏进行校验和发货。

信息
  • 这里的回调只当做【支付完成】看待，【支付成功】需要对接 XDServer 后，以服务端推送信息为准。
  • 由于 Apple 支付票据有概率会出现多票据合并的情况，此时会丢失游戏传入的 orderId，并由平台随机生成一个唯一的 orderId。

发起商品购买​

提示
  • SDK 在 v6.23.0 中增加了新接口支持 Apple 的批量购买，需要设置 quantity 的值。
  • 关于 Google 结算库的批量购买无法通过 SDK quantity 字段直接指定，详情请参考Google Pay 接入指引
  • 老接口仍然可以使用，但将无法支持部分新增功能。

使用 PaymentParams 类来构造支付参数。

// PaymentActivity.java

import com.xd.intl.payment.XDGPayment;
import com.xd.intl.payment.api.PaymentParams;
import com.xd.intl.payment.callback.XDGPaymentCallback;
import com.xd.intl.payment.constant.Constants;
import com.xd.intl.payment.wallet.XDGPaymentResult;

// ...

private void initiatePayment() {
    PaymentParams paymentParams = PaymentParams.newBuilder()
            .setGameOrderId("gameOrderId") // 订单 ID。游戏侧订单号，服务端支付回调会包含该字段,如无该字段，传空
            .setProductId("productId") // 商品 ID。Google Play 定义的商品 ID
            .setRoleId("roleId") // 角色 ID。支付角色 ID，服务端支付回调会包含该字段
            .setServerId("serverId") // 服务器 ID。所在服务器 ID，不能有特殊字符，服务端支付回调会包含该字段
            .setExt("ext") // 附加信息。服务端支付回调会包含该字段
            .build();

    // 支付结果回调
    XDGPaymentCallback<Object> callback = new XDGPaymentCallback<Object>() {
        @Override
        public void onPaymentCallback(XDGPaymentResult result, Object data) {
            if (result.code == Constants.PaymentResponseCode.OK) {
                // 支付成功
            } else {
                // 支付失败
            }
        }
    };

    XDGPayment.initiatePayment(PaymentActivity.this, paymentParams, callback);
}

// ...
支付老接口，可以继续使用，但可能不支持部分新功能
// PaymentActivity.java

import com.xd.intl.payment.XDGPayment;
import com.xd.intl.payment.callback.XDGPaymentCallback;
import com.xd.intl.payment.constant.Constants;
import com.xd.intl.payment.wallet.XDGPaymentResult;

// ...

private void payWithProduct() {
    // 支付结果回调
    XDGPaymentCallback<Object> callback = new XDGPaymentCallback<Object>() {
        @Override
        public void onPaymentCallback(XDGPaymentResult result, Object data) {
            if (result.code == Constants.PaymentResponseCode.OK) {
                // 支付成功
            } else {
                // 支付失败
            }
        }
    };

    XDGPayment.payWithProduct(
            "gameOrderId", // 订单 ID。游戏侧订单号，服务端支付回调会包含该字段,如无该字段，传空
            "productId", // 商品 ID。Google Play 定义的商品 ID
            "roleId", // 角色 ID。支付角色 ID，服务端支付回调会包含该字段
            "serverId", // 服务器 ID。所在服务器 ID，不能有特殊字符，服务端支付回调会包含该字段
            "ext", // 附加信息。服务端支付回调会包含该字段
            callback
    );
}

// ...

订单数据结构定义​


网页支付(Android、PC)​

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

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

// PaymentActivity.java

import com.xd.intl.payment.XDGPayment;
import com.xd.intl.payment.callback.XDGPaymentCallback;
import com.xd.intl.payment.constant.Constants;
import com.xd.intl.payment.wallet.XDGPaymentResult;

// ...

private void payWithWeb() {
    // 支付结果回调
    XDGPaymentCallback<Object> callback = new XDGPaymentCallback<Object>() {
        @Override
        public void onPaymentCallback(XDGPaymentResult result, Object data) {
            if (result.code == Constants.PaymentResponseCode.OK) {
                // 支付完成
            } else {
                // 支付失败
            }
        }
    };
    XDGPayment.payWithWeb(
            "gameOrderId", // 订单 ID。游戏侧订单号，服务端支付回调会包含该字段，如无该字段，传空。
            "productId", // 商品 ID。游戏的商品ID，必填
            "productName", // 商品名称。用于内嵌支付内部显示，必填
            1.00, // 商品价格，必填
            "roleId", // 角色 ID。支付角色 ID，服务端支付回调会包含该字段，必填
            "serverId", // 服务器 ID。所在服务器 ID，不能有特殊字符，服务端支付回调会包含该字段，必填
            "extras", // 附加信息。服务端支付回调会包含该字段，必填
            callback
    );
}

// ...

Android 原生支付（国内）​

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

// PaymentActivity.java

import com.xd.intl.payment.XDGPayment;
import com.xd.intl.payment.callback.XDGPaymentCallback;
import com.xd.intl.payment.constant.Constants;
import com.xd.intl.payment.wallet.XDGPaymentResult;

// ...

private void pay() {
    // 支付结果回调
    XDGPaymentCallback<Object> callback = 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 {
                    // 支付失败
                }
            }
        }
    };

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

    // SDK 内置 UI 支付
    XDGPayment.pay(params, callback);


    String payType = PayType.WECHAT_PAY; // 指定微信支付方式，支付宝支付方式为：PayType.ALIPAY
    // 无 UI 支付
    XDGPayment.pay(payType, params, callback);
}

// ...

应用外购买或掉单​

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

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

查询订单数据​

// 暂不支持

礼包码兑换或掉单补单​

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

// 暂不支持