在游戏中集成商店

在发布商帐户中创建并配置商品（虚拟物品、虚拟货币、捆绑包、密钥）后，在您的游戏中添加一个游戏内商店：

  1. 实现显示商品目录。
  2. 实现商品销售逻辑。

显示商品目录

注：
要调用艾克索拉API，您可以使用针对各游戏引擎和平台的现成SDK：

通过In-Game Store API调用实现商品目录的显示：

任务API
显示添加至商店的虚拟物品完整列表获取虚拟物品列表
在客户端侧显示可供购买的虚拟物品组列表获取项目组列表
在客户端侧获取商店中可供销售的虚拟货币列表获取虚拟货币列表
在客户端侧显示添加至商店的虚拟货币套餐完整列表获取虚拟货币套餐列表
显示添加至商店的捆绑包完整列表获取捆绑包列表
注：
获取目录方法返回发出请求时在商店中显示的商品。要获取尚未开始或已过显示时间段的商品的信息，请在请求目录时传入值为1的show_inactive_time_limited_items参数。

销售商品

您可以通过以下方式销售商品：

  1. 快速购买单项商品。可以通过此方式销售任意数量的单个SKU（例如100瓶相同的魔法药水或自定义数量的虚拟货币）。
  2. 购物车下单。通过此方式，用户可以将商品加入购物车、添加或删除商品以及更改商品数量。

快速购买

  1. 调用使用指定商品创建订单 API。响应中将传入用于打开支付UI的令牌。
  2. 用收到的支付令牌打开支付UI。
注：
折扣信息（个体折扣或与购买关联的折扣）只在支付UI中对用户提供。不支持使用促销码。
注：
要调用艾克索拉API，您可以使用针对各游戏引擎和平台的现成SDK：

购物车下单

实现以下逻辑：
  1. 设置购物车并获取令牌：
  2. 打开支付UI。

在客户端上设置购物车和购物车下单

自行实现添加和删除商品的逻辑。另外还需要考虑一个情况，即在调用设置购物车的API之前，您没有订单会应用哪些促销活动的信息，也就是说，总价和添加的奖励品的详情不可知。

  1. 玩家添加商品到购物车后，请调用在购物车里添加商品 API。所选商品的当前信息（折扣前后的价格、奖励品）将传入响应中。
  2. 调用使用当前购物车中的所有商品创建订单 API。订单ID和支付令牌将传入响应中。创建的订单将获得New的订单状态。
  3. 打开支付UI。
注：
要调用艾克索拉API，您可以使用针对各游戏引擎和平台的现成SDK：

在服务器上设置购物车和购物车下单

此方式下设置购物车的时间可能较长，因为每个购物车更改必须伴随API调用。

完成以下步骤：

  1. 更改购物车：

注：
如要获取购物车的当前状态，请调用获取当前用户的购物车 API。
  1. 调用使用当前购物车中的所有商品创建订单 API。订单ID和支付令牌将传入响应中。创建的订单将获得New的订单状态。
  2. 打开支付UI。

打开支付界面

要进行商品支付，请打开支付UI。用于打开支付UI的令牌将传入使用当前购物车中的所有商品创建订单 API响应中。

通过以下方式之一实现支付UI的打开：

测试支付流程

您可以在沙盒模式下测试支付流程，可使用测试银行卡和任意帐户进行。

注：

首次完成真实付款后，严格沙盒付款政策即生效。沙盒模式支付只对发布商帐户 > 公司设置 >中指定的用户可用。

只有与艾克索拉签署许可证协议后才能通过直接链接使用真实货币购买虚拟货币和物品。方法是在发布商帐户中前往协议与税务信息 > 协议部分，完成协议表单，然后等待确认。审核协议最多可能需要3个工作日。

要启用/禁用沙盒模式，需更改快速购买和购物车下单请求中sandbox参数的值。默认禁用沙盒模式。

获取订单状态

您可以使用以下方法获取用户订单状态：

  1. 在服务器侧通过Webhook。
  2. 在客户端侧通过WebSocket API或IGS API。

在服务器侧通过Webhook获取用户订单状态

在服务器侧配置Webhook后，可使用它们来获取订单详情和状态。

在客户端侧通过WebSocket API或IGS API获取用户订单状态

如没有服务器或您是在客户端侧实现购买处理逻辑，可使用以下方式：
  1. WebSocket API。
  2. Short-polling。

使用WebSocket API在客户端侧获取订单状态

本解决方案使用websocket在不获取订单详细信息的情况下获取订单状态。该方法适用于：客户端（如您的网站或移动应用）和艾克索拉服务器间只创建了一个连接，因此客户端或服务器上都没有额外负载。

注：
如果您自己没有服务器来处理Webhook，或者您使用客户端侧购买处理逻辑，可通过Centrifuge SDK来使用WebSocket API。

完成以下步骤：

  1. 创建连接，以便艾克索拉服务器和您的客户端识别订单状态消息：

Copy
Full screen
Small screen
  • 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
  1. 使用client.on函数来订阅事件，以便接收关于订单状态的新消息：
Copy
Full screen
Small screen
  • javascript
client.on('publication', (ctx) => {
   //handle the status
});
  1. 触发建立实际连接：
Copy
Full screen
Small screen
  • javascript
client.connect()
  1. 连接API历史记录方法，以便接收订单状态更改历史记录。
Copy
Full screen
Small screen
  • 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
   });
});

消息正文示例：

Copy
Full screen
Small screen
  • javascript
{
order_id: 59614241,
status: 'new'
}

可能出现以下订单状态：

  • New — 已创建订单但未支付
  • Paid — 订单已支付
  • Done — 订单已交付（已发送所有支付凭证，交付在艾克索拉侧、外部平台等进行）
  • Canceled — 订单已取消，付款已退给用户

Websocket使用建议：

  • 通过websocket接收响应的最大等待时间为5分钟。
  • 应在打开支付界面时建立连接。
  • 一旦收到最终订单状态，无论是Canceled或Done，都应中止连接。
  • 如果websocket的生命周期到期或连接出现任何问题，请使用短轮询。

    短轮询

    要在状态切换后获取订单中商品的详细信息，请调用获取订单API。

    注：
    将使用周期性订单状态轮询，即一个接收订单状态和订单信息的简单HTTP请求。建议的请求间隔时间为3秒。
    本文对您的有帮助吗？
    谢谢！
    我们还有其他可改进之处吗？ 留言
    非常抱歉
    请说明为何本文没有帮助到您。 留言
    感谢您的反馈！
    我们会查看您的留言并运用它改进用户体验。
    上次更新时间: 2024年11月8日

    发现了错别字或其他内容错误？ 请选择文本，然后按Ctrl+Enter。

报告问题
我们非常重视内容质量。您的反馈将帮助我们做得更好。
请留下邮箱以便我们后续跟进
感谢您的反馈！