设置订单状态跟踪
要将商品发放给用户,需确保付款已成功。
选择一种订单状态跟踪方式:
选择最适合您项目的方式来访问艾克索拉数据:
如没有服务器或您是在客户端侧实现购买处理逻辑,可使用以下方式:
使用WebSocket API在客户端侧获取订单状态
本解决方案使用websocket在不获取订单详细信息的情况下获取订单状态。该方法适用于:客户端(如您的网站或移动应用)和艾克索拉服务器间只创建了一个连接,因此客户端或服务器上都没有额外负载。
完成以下步骤:
- 创建连接,以便艾克索拉服务器和您的客户端识别订单状态消息:
- javascript
const client = new Centrifuge(
connectionURL,
{
data: {
user_external_id: user_external_id,
auth: auth,
project_id: project_id
}
}
)
connectionURL - wss://ws-store.xsolla.com/connection/websocket
auth - user JWT token
- 使用
client.on
函数来订阅事件,以便接收关于订单状态的新消息:
- javascript
client.on('publication', (ctx) => {
//handle the status
});
- 触发建立实际连接:
- javascript
client.connect()
- 连接API历史记录方法,以便接收订单状态更改历史记录。
- javascript
client.on('subscribed', function (ctx) {
client.history(ctx.channel, { limit: -1, since: { offset: 0 }, reverse: false }).then(function (resp) {
resp.publications.forEach((ctx) => {
/handle the status
});
}, function (err) {
//handle the status
});
});
消息正文示例:
- javascript
{
order_id: 59614241,
status: 'new'
}
可能出现以下订单状态:
New
— 已创建订单但未支付Paid
— 订单已支付Done
— 订单已交付(已发送所有支付凭证,交付在艾克索拉侧、外部平台等进行)Canceled
— 订单已取消,付款已退给用户
Websocket使用建议:
- 通过websocket接收响应的最大等待时间为5分钟。
- 应在打开支付界面时建立连接。
- 一旦收到最终订单状态,无论是
Canceled
或Done
,都应中止连接。 - 如果websocket的生命周期到期或连接出现任何问题,请使用短轮询。
短轮询
要在状态切换后获取订单中商品的详细信息,请调用获取订单API。
注:将使用周期性订单状态轮询,即一个接收订单状态和订单信息的简单HTTP请求。建议的请求间隔时间为3秒。
XsollaCatalog.Purchase
方法封装了若干跟踪订单状态的方法。关于跟踪机制的详细信息,请参阅Unity专用企业级SDK。
此外,您可以实现对订单状态和内容的处理,这些在购买方法的onSuccess
回调函数中传入。
使用本SDK时,可通过以下方式跟踪订单状态:
订阅订单状态更改
要订阅订单状态更改,请使用Store库中的getOrderStatus
SDK方法并向该方法传入以下参数:
listener
—OrderStatusListener
类型的监听器对象。orderId
— 以参数形式从通过购物车购买、一键购买或用虚拟货币进行购买收到的订单ID。
调用XStore.getOrderStatus方法的示例:
- kotlin
XStore.getOrderStatus(object : OrderStatusListener() {
override fun onStatusUpdate(status: OrderResponse.Status) {
if(status == OrderResponse.Status.DONE) {
Log.d("MainActivity", "Success")
}
}
override fun onFailure() {
Log.d("MainActivity", "Failure")
}
}, orderId)
建议打开支付UI时调用XStore.getOrderStatus
方法。
购买方法封装了多个订单状态跟踪方法。跟踪根据以下算法执行:
- 建立一个Web socket连接。
- 如建立Web socket连接成功,且订单状态变为
done
或cancel
,则停止跟踪。如Web socket连接失败或响应包含不正确的数据,则使用短轮询跟踪订单状态。 - 通过短轮询继续跟踪订单状态。每3秒钟发送一次简单HTTP订单状态请求。如订单状态变为
done
或cancel
,则停止跟踪。
请求订单状态
要请求支付交易的当前状态,请调用Store库的getOrder
方法,并传入以下参数:
orderId
— 购买商品时收到的订单ID。callback
— 检索订单信息成功的回调。实现回调时,请使用GetStatusCallback
接口并实现onSuccess
和onError
方法。callback
— 检索订单信息成功的回调。实现回调时,请使用GetStatusCallback
接口并实现onSuccess
和onError
方法。
订单状态信息传入一个InvoicesDataResponse
类型对象的onSuccess
方法中。该对象包含一个InvoiceData
对象数组。每个InvoiceData
对象对应订单处理过程中的一个特定阶段并包含该阶段的状态。
例如,如果用户在下单时一开始输入了无效的数据,则包含一个InvoicesDataResponse.CANCELED
状态的对象将显示在InvoiceData
列表中。如用户改正了数据并成功支付了订单,则一个新的InvoiceData
对象将显示在数组中并包含状态InvoicesDataResponse.Status.DONE
。
如收到了最终支付状态(InvoicesDataResponse.Status.DONE
或InvoicesDataResponse.Status.ERROR
),状态跟踪将停止。
示例:
- kotlin
XPayments.getStatus(<token>, <isSandbox>, object : GetStatusCallback {
override fun onSuccess(data: InvoicesDataResponse?) {
Log.d(TAG, "onSuccess is fired. Result data = $data")
}
override fun onError(throwable: Throwable?, errorMessage: String?) {
Log.d(TAG, "onError is fired. ErrorMessage = $errorMessage")
}
})
您可以使用CheckPendingOrder
SDK方法跟踪订单状态。请向该方法传入以下参数:
AccessToken
— 购买商品时收到的支付令牌。OrderId
— 购买商品时收到的订单ID。SuccessCallback
— 支付成功回调。ErrorCallback
— 请求错误回调。bIsUserInvolvedToPayment
— 用户在付款过程中是否参与。如使用真是货币购买,传入true
;如购买免费商品或使用虚拟货币购买,传入false
。
关于跟踪机制的详细信息,请参阅虚幻引擎专用企业级SDK。
要请求订单的状态和内容,请调用CheckOrder
SDK方法,并传入以下参数:
要跟踪所创建订单的状态并进行验证,需在应用程序的服务器侧配置Webhook的处理。
要完整运营一个游戏内商店,必须实现对主要Webhook的处理:
Webhook | 通知类型 | 描述 |
---|---|---|
用户验证 | user_validation | 在支付过程的不同阶段发送,用于确保用户已在游戏中注册。 |
支付 | payment | 订单付款时发送,包含支付数据及交易详情。 |
订单支付成功 | order_paid | 成功处理支付Webhook时发送,包含所购商品及交易ID的信息。使用此Webhook的数据向用户添加商品。 |
退款 | refund | 订单取消时发送,包含取消的付款数据及交易详情。 |
订单取消 | order_canceled | 成功处理退款Webhook时发送,包含所购商品及取消的交易的ID信息。使用此Webhook的数据移除购买的商品。 |
关于Webhook的完整列表及常规使用信息,请参阅Webhook文档。
设置Webhook的发送
要在艾克索拉侧配置Webhook:
- 在发布商帐户中打开您的项目。
- 在侧边栏中单击项目设置,然后前往Webhooks部分。
- 在Webhook URL字段中,指定艾克索拉要向其发送Webhook的URL。
- 单击启用Webhook。
添加Webhook监听器
Webhook监听器是一个程序代码,可以在指定的URL地址接收传入的Webhook、生成签名及向艾克索拉Webhook服务器发送响应。
生成签名
接收Webhook时,应确保数据传输的安全性。为此,必须从Webhook数据生成一个签名并确保它与HTTP请求头中发送的签名匹配。
要生成签名:
- 将请求正文中的JSON与项目密钥串联起来。
- 对第一步中得到的字符串应用SHA-1加密散列函数。
向Webhook发送响应
要确认收到Webhook,您的服务器必须返回:
200
、201
或204
HTTP代码(成功响应时)。- 带问题描述的
400
HTTP代码(如未找到指定用户或传入的签名无效)。
如您的服务器发生临时问题,您的Webhook处理程序也可以返回5xx
代码。
如果未收到对订单成功支付或订单取消Webhook的响应,或收到了包含5xx
代码的响应,将根据以下规则重新发送Webhook:
- 间隔5分钟尝试2次
- 间隔15分钟尝试7次
- 间隔60分钟尝试10次
自首次尝试起,12小时内最多尝试发送Webhook20次。
如果未收到对支付Webhook的响应或收到了包含5xx
代码的响应,也将尝试重新发送Webhook且重试的间隔逐渐拉长。12小时内最多尝试12次。
如果未收到对用户验证Webhook的响应或收到了包含400
或5xx
代码的响应,将不会重新发送用户验证Webhook。
该情况下会向用户显示一个错误,且不会发送支付和订单成功支付Webhook。
发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。